gnu.inet.nntp

Class NNTPConnection

java.lang.Object
- gnu.inet.nntp.NNTPConnection

Implemented Interfaces:: NNTPConstants

public class NNTPConnection

extends java.lang.Object

implements NNTPConstants

An NNTP client. This object is used to establish and manage a connection to an NNTP server.

Author:: Chris Burdess

Field Summary
`static int`	`DEFAULT_PORT` The default NNTP port.
`static Level`	`NNTP_TRACE` The network trace level.
`protected boolean`	`canPost` Whether the host permits posting of articles.
`protected String`	`hostname` The hostname of the host we are connected to.
`protected LineInputStream`	`in` The socket input stream.
`static Logger`	`logger` The logger used for NNTP protocol traces.
`protected CRLFOutputStream`	`out` The socket output stream.
`protected PendingData`	`pendingData` Pending data, if any.
`protected int`	`port` The port on the host we are connected to.
`protected Socket`	`socket` The socket used for network communication.
`protected String`	`welcome` The greeting issued by the host when we connected.

ARTICLE, ARTICLE_FOLLOWS, ARTICLE_NOT_WANTED, ARTICLE_NOT_WANTED_VIA_TAKETHIS, ARTICLE_POSTED, ARTICLE_REJECTED, ARTICLE_RETRIEVED, ARTICLE_TRANSFERRED, ARTICLE_TRANSFERRED_OK, ARTICLE_TRANSFER_FAILED, AUTHINFO_GENERIC, AUTHINFO_OK, AUTHINFO_PASS, AUTHINFO_REJECTED, AUTHINFO_SIMPLE, AUTHINFO_SIMPLE_DENIED, AUTHINFO_SIMPLE_OK, AUTHINFO_SIMPLE_REQUIRED, AUTHINFO_USER, BODY, BODY_FOLLOWS, CHECK, CLOSING_CONNECTION, COMMAND_NOT_RECOGNIZED, DATE, DATE_OK, GROUP, GROUP_SELECTED, HEAD, HEAD_FOLLOWS, HELP, HELP_TEXT, IHAVE, INTERNAL_ERROR, LAST, LIST, LISTGROUP, LIST_ACTIVE, LIST_ACTIVE_TIMES, LIST_DISTRIBUTIONS, LIST_DISTRIB_PATS, LIST_FOLLOWS, LIST_NEWSGROUPS, LIST_OVERVIEW_FMT, LIST_SUBSCRIPTIONS, MODE_READER, MODE_STREAM, NEWGROUPS, NEWGROUPS_LIST_FOLLOWS, NEWNEWS, NEWNEWS_LIST_FOLLOWS, NEXT, NO_ARTICLE_SELECTED, NO_GROUP_SELECTED, NO_NEXT_ARTICLE, NO_POSTING_ALLOWED, NO_PREVIOUS_ARTICLE, NO_SUCH_ARTICLE, NO_SUCH_ARTICLE_NUMBER, NO_SUCH_GROUP, OVERVIEW_FOLLOWS, PERMISSION_DENIED, POST, POSTING_ALLOWED, POSTING_FAILED, POSTING_NOT_ALLOWED, QUIT, SEND_ARTICLE, SEND_ARTICLE_VIA_TAKETHIS, SEND_AUTHINFOPASS, SEND_AUTHINFO_SIMPLE, SEND_TRANSFER_ARTICLE, SERVICE_DISCONTINUED, SLAVE, SLAVE_ACKNOWLEDGED, STAT, STREAMING_OK, SYNTAX_ERROR, TAKETHIS, TRANSFER_FAILED, TRANSFER_PERMISSION_DENIED, TRY_AGAIN_LATER, XGTITLE, XGTITLE_LIST_FOLLOWS, XHDR, XINDEX, XOVER, XPAT, XPATH, XREPLIC, XROVER

Constructor Summary
`NNTPConnection(String hostname)` Creates a new connection object.
`NNTPConnection(String hostname, int port)` Creates a new connection object.
`NNTPConnection(String hostname, int port, int connectionTimeout, int timeout)` Creates a new connection object.

Method Summary
`ArticleResponse`	`article(String messageId)` Send an article retrieval request to the server.
`ArticleResponse`	`article(int articleNumber)` Send an article retrieval request to the server.
`protected ArticleResponse`	`articleImpl(String command, String messageId)` Performs an ARTICLE, BODY, HEAD, or STAT command.
`boolean`	`authinfo(String username, String password)` Basic authentication strategy.
`boolean`	`authinfoGeneric(String mechanism, String username, String password)` Authenticates the connection using the specified SASL mechanism, username and password.
`boolean`	`authinfoSimple(String username, String password)` Implementation of NNTP simple authentication.
`ArticleResponse`	`body(String messageId)` Send an article body retrieval request to the server.
`ArticleResponse`	`body(int articleNumber)` Send an article body retrieval request to the server.
`boolean`	`check(String messageId)`
`Date`	`date()` Returns the date on the server.
`String`	`getWelcome()` Return the welcome message sent by the server in reply to the initial connection.
`GroupResponse`	`group(String name)` Send a group selection command to the server.
`ArticleResponse`	`head(String messageId)` Send an article head retrieval request to the server.
`ArticleResponse`	`head(int articleNumber)` Send an article head retrieval request to the server.
`LineIterator`	`help()` Requests a help listing.
`PostStream`	`ihave(String messageId)` Sends an ihave command indicating that the client has an article with the specified message-id.
`ArticleResponse`	`last()` Sends a previous article positioning command to the server.
`GroupIterator`	`list()` Send a group listing command to the server.
`GroupIterator`	`listActive(String wildmat)` Returns an iterator over the groups specified according to the wildmat pattern.
`ActiveTimesIterator`	`listActiveTimes()` Returns an iterator over the active.times file.
`ArticleNumberIterator`	`listGroup(String group)` Returns a listing of all the article numbers in the specified newsgroup.
`PairIterator`	`listNewsgroups(String wildmat)` Returns an iterator over the group descriptions for the given groups.
`LineIterator`	`listOverviewFmt()` Returns an iterator over the order in which headers are stored in the overview database.
`GroupIterator`	`listSubscriptions()` Returns a list of newsgroups suitable for new users of the server.
`boolean`	`modeReader()` Indicates to the server that this is a user-agent.
`boolean`	`modeStream()` Attempt to initialise the connection in streaming mode.
`LineIterator`	`newGroups(Date since, String[] distributions)` Returns an iterator over the list of new groups on the server since the specified date.
`LineIterator`	`newNews(String newsgroup, Date since, String[] distributions)` Returns an iterator over the list of message-ids posted or received to the specified newsgroup(s) since the specified date.
`ArticleResponse`	`next()` Sends a next article positioning command to the server.
`protected StatusResponse`	`parseResponse(String line)` Parse a response object from a response line sent by the server.
`protected StatusResponse`	`parseResponse(String line, boolean isListGroup)` Parse a response object from a response line sent by the server.
`OutputStream`	`post()` Post an article.
`void`	`quit()` Close the connection.
`protected String`	`read()` Read a single line from the server.
`protected void`	`send(String line)` Send a single line to the server.
`void`	`slave()` Indicates to the server that this is a slave connection.
`ArticleResponse`	`stat(String messageId)` Send an article status request to the server.
`ArticleResponse`	`stat(int articleNumber)` Send an article status request to the server.
`OutputStream`	`takethis(String messageId)` Implements the out-of-order takethis command.
`PairIterator`	`xgtitle(String wildmat)` Returns an iterator over the list of newsgroup descriptions.
`HeaderIterator`	`xhdr(String header, String range)`
`OverviewIterator`	`xover(Range range)`

NNTPConnection

public NNTPConnection(String hostname)
            throws IOException

Creates a new connection object.
Parameters:
hostname - the hostname or IP address of the news server

NNTPConnection

public NNTPConnection(String hostname,
                      int port)
            throws IOException

Creates a new connection object.
Parameters:
hostname - the hostname or IP address of the news server
port - the port to connect to

NNTPConnection

public NNTPConnection(String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout)
            throws IOException

Creates a new connection object.
Parameters:
hostname - the hostname or IP address of the news server
port - the port to connect to
connectionTimeout - the socket connection timeout
timeout - the read timeout on the socket

article

public ArticleResponse article(String messageId)
            throws IOException

Send an article retrieval request to the server.
Parameters:
messageId - the message-id of the article to retrieve
Returns:
an article response consisting of the article number and message-id, and an iterator over the lines of the article header and body, separated by an empty line

article

public ArticleResponse article(int articleNumber)
            throws IOException

Send an article retrieval request to the server.
Parameters:
articleNumber - the article number of the article to retrieve
Returns:
an article response consisting of the article number and message-id, and an iterator over the lines of the article header and body, separated by an empty line

articleImpl

protected ArticleResponse articleImpl(String command,
                                      String messageId)
            throws IOException

Performs an ARTICLE, BODY, HEAD, or STAT command.
Parameters:
command - one of the above commands
messageId - the article-number or message-id in string form

authinfo

public boolean authinfo(String username,
                        String password)
            throws IOException

Basic authentication strategy.
Parameters:
username - the user to authenticate
password - the(cleartext) password
Returns:
true on success, false on failure

authinfoGeneric

public boolean authinfoGeneric(String mechanism,
                               String username,
                               String password)
            throws IOException

Authenticates the connection using the specified SASL mechanism, username and password.
Parameters:
mechanism - a SASL authentication mechanism, e.g. LOGIN, PLAIN, CRAM-MD5, GSSAPI
username - the authentication principal
password - the authentication credentials

authinfoSimple

public boolean authinfoSimple(String username,
                              String password)
            throws IOException

Implementation of NNTP simple authentication. Note that use of this authentication strategy is highly deprecated, only use on servers that won't accept any other form of authentication.

body

public ArticleResponse body(String messageId)
            throws IOException

Send an article body retrieval request to the server.
Parameters:
messageId - the message-id of the article to body
Returns:
an article response consisting of the article number and message-id, and an iterator over the lines of the article body

body

public ArticleResponse body(int articleNumber)
            throws IOException

Send an article body retrieval request to the server.
Parameters:
articleNumber - the article number of the article to body
Returns:
an article response consisting of the article number and message-id, and an iterator over the lines of the article body

check

public boolean check(String messageId)
            throws IOException

date

public Date date()
            throws IOException

Returns the date on the server.

getWelcome

public String getWelcome()

Return the welcome message sent by the server in reply to the initial connection. This message sometimes contains disclaimers or help information that may be relevant to the user.

group

public GroupResponse group(String name)
            throws IOException

Send a group selection command to the server. Returns a group status response.
Parameters:
name - the name of the group to select

head

public ArticleResponse head(String messageId)
            throws IOException

Send an article head retrieval request to the server.
Parameters:
messageId - the message-id of the article to head
Returns:
an article response consisting of the article number and message-id, and an iterator over the lines of the article header

head

public ArticleResponse head(int articleNumber)
            throws IOException

Send an article head retrieval request to the server.
Parameters:
articleNumber - the article number of the article to head
Returns:
an article response consisting of the article number and message-id, and an iterator over the lines of the article header

help

public LineIterator help()
            throws IOException

Requests a help listing.
Returns:
an iterator over a collection of help lines.

ihave

public PostStream ihave(String messageId)
            throws IOException

Sends an ihave command indicating that the client has an article with the specified message-id.
Parameters:
messageId - the article message-id
Returns:
a PostStream if the server wants the specified article, null otherwise

last

public ArticleResponse last()
            throws IOException

Sends a previous article positioning command to the server.
Returns:
the article number/message-id pair associated with the new article

list

public GroupIterator list()
            throws IOException

Send a group listing command to the server. Returns a GroupIterator. This must be read fully before other commands are issued.

listActive

public GroupIterator listActive(String wildmat)
            throws IOException

Returns an iterator over the groups specified according to the wildmat pattern. The iterator must be read fully before other commands are issued.
Parameters:
wildmat - the wildmat pattern. If null, returns all groups. If no groups are matched, returns an empty iterator.

listActiveTimes

public ActiveTimesIterator listActiveTimes()
            throws IOException

Returns an iterator over the active.times file. Each ActiveTime object returned provides details of who created the newsgroup and when.

listGroup

public ArticleNumberIterator listGroup(String group)
            throws IOException

Returns a listing of all the article numbers in the specified newsgroup. If the group parameter is null, the currently selected group is assumed.
Parameters:
group - the name of the group to list articles for

listNewsgroups

public PairIterator listNewsgroups(String wildmat)
            throws IOException

Returns an iterator over the group descriptions for the given groups.
Parameters:
wildmat - if non-null, limits the groups in the iterator to the specified pattern
Returns:
an iterator over group name/description pairs
See Also:
xgtitle(String)

listOverviewFmt

public LineIterator listOverviewFmt()
            throws IOException

Returns an iterator over the order in which headers are stored in the overview database. Each line returned by the iterator contains one header field.
See Also:
xover(Range)

listSubscriptions

public GroupIterator listSubscriptions()
            throws IOException

Returns a list of newsgroups suitable for new users of the server.

modeReader

public boolean modeReader()
            throws IOException

Indicates to the server that this is a user-agent.
Returns:
true if posting is allowed, false otherwise.

modeStream

public boolean modeStream()
            throws IOException

Attempt to initialise the connection in streaming mode. This is generally used to bypass the lock step nature of NNTP in order to perform a series of CHECK and TAKETHIS commands.
Returns:
true if the server supports streaming mode

newGroups

public LineIterator newGroups(Date since,
                              String[] distributions)
            throws IOException

Returns an iterator over the list of new groups on the server since the specified date. NB this method suffers from a minor millenium bug.
Parameters:
since - the date from which to list new groups
distributions - if non-null, an array of distributions to match

newNews

public LineIterator newNews(String newsgroup,
                            Date since,
                            String[] distributions)
            throws IOException

Returns an iterator over the list of message-ids posted or received to the specified newsgroup(s) since the specified date. NB this method suffers from a minor millenium bug.
Parameters:
newsgroup - the newsgroup wildmat
since - the date from which to list new articles
distributions - if non-null, a list of distributions to match

public ArticleResponse next()
            throws IOException

Sends a next article positioning command to the server.
Returns:
the article number/message-id pair associated with the new article

parseResponse

protected StatusResponse parseResponse(String line)
            throws ProtocolException

Parse a response object from a response line sent by the server.

parseResponse

protected StatusResponse parseResponse(String line,
                                       boolean isListGroup)
            throws ProtocolException

Parse a response object from a response line sent by the server.
Parameters:
isListGroup - whether we are invoking the LISTGROUP command

post

public OutputStream post()
            throws IOException

Post an article. This is a two-stage process. If successful, returns an output stream to write the article to. Clients should call write() on the stream for all the bytes of the article, and finally call close() on the stream. No other method should be called in between.
See Also:
NNTPConnection

quit

public void quit()
            throws IOException

Close the connection. After calling this method, no further calls on this object are valid.

read

protected String read()
            throws IOException

Read a single line from the server.
Returns:
a line of text

send

protected void send(String line)
            throws IOException

Send a single line to the server.
Parameters:
line - the line to send

slave

public void slave()
            throws IOException

Indicates to the server that this is a slave connection.

stat

public ArticleResponse stat(String messageId)
            throws IOException

Send an article status request to the server.
Parameters:
messageId - the message-id of the article to stat
Returns:
an article response consisting of the article number and message-id

stat

public ArticleResponse stat(int articleNumber)
            throws IOException

Send an article status request to the server.
Parameters:
articleNumber - the article number of the article to stat
Returns:
an article response consisting of the article number and message-id

takethis

public OutputStream takethis(String messageId)
            throws IOException

Implements the out-of-order takethis command. The client uses the returned output stream to write all the bytes of the article. When complete, it calls close() on the stream.
See Also:
NNTPConnection

xgtitle

public PairIterator xgtitle(String wildmat)
            throws IOException

Returns an iterator over the list of newsgroup descriptions.
Parameters:
wildmat - if non-null, the newsgroups to match

xhdr

public HeaderIterator xhdr(String header,
                           String range)
            throws IOException

xover

public OverviewIterator xover(Range range)
            throws IOException

Overview Package Class Use Tree Index Deprecated About
Prev Class \| Next Class	Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr

gnu.inet.nntp

Class NNTPConnection

Field Summary

Fields inherited from interface gnu.inet.nntp.NNTPConstants

Constructor Summary

Method Summary

Field Details

DEFAULT_PORT

NNTP_TRACE

canPost

hostname

in

logger

out

pendingData

port

socket

welcome

Constructor Details

NNTPConnection

NNTPConnection

NNTPConnection

Method Details

article

article

articleImpl

authinfo

authinfoGeneric

authinfoSimple

body

body

check

date

getWelcome

group

head

head

help

ihave

last

list

listActive

listActiveTimes

listGroup

listNewsgroups

listOverviewFmt

listSubscriptions

modeReader

modeStream

newGroups

newNews

next

parseResponse

parseResponse

post

quit

read

send

slave

stat

stat

takethis

xgtitle

xhdr

xover