NNTPConnection (gnu-classpath-ext-inetlib 1.1.1 API)

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

All Implemented Interfaces:

NNTPConstants
```
public class NNTPConnection
extends 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

Fields
Modifier and Type	Field and Description
`protected boolean`	`canPost` Whether the host permits posting of articles.
`static int`	`DEFAULT_PORT` The default NNTP port.
`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.
`static Level`	`NNTP_TRACE` The network trace level.
`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.

Fields inherited from interface gnu.inet.nntp.NNTPConstants
ARTICLE, ARTICLE_FOLLOWS, ARTICLE_NOT_WANTED, ARTICLE_NOT_WANTED_VIA_TAKETHIS, ARTICLE_POSTED, ARTICLE_REJECTED, ARTICLE_RETRIEVED, ARTICLE_TRANSFER_FAILED, ARTICLE_TRANSFERRED, ARTICLE_TRANSFERRED_OK, 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, LIST_ACTIVE, LIST_ACTIVE_TIMES, LIST_DISTRIB_PATS, LIST_DISTRIBUTIONS, LIST_FOLLOWS, LIST_NEWSGROUPS, LIST_OVERVIEW_FMT, LIST_SUBSCRIPTIONS, LISTGROUP, 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_AUTHINFO_SIMPLE, SEND_AUTHINFOPASS, 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

Constructors
Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ArticleResponse`	`article(int articleNumber)` Send an article retrieval request to the server.
`ArticleResponse`	`article(String messageId)` 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(int articleNumber)` Send an article body retrieval request to the server.
`ArticleResponse`	`body(String messageId)` 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(int articleNumber)` Send an article head retrieval request to the server.
`ArticleResponse`	`head(String messageId)` 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(int articleNumber)` Send an article status request to the server.
`ArticleResponse`	`stat(String messageId)` 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)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - logger
```
public static final Logger logger
```
    The logger used for NNTP protocol traces.
  - NNTP_TRACE
```
public static final Level NNTP_TRACE
```
    The network trace level.
  - DEFAULT_PORT
```
public static final int DEFAULT_PORT
```
    The default NNTP port.
    
    See Also:
    
    Constant Field Values
  - hostname
```
protected String hostname
```
    The hostname of the host we are connected to.
  - port
```
protected int port
```
    The port on the host we are connected to.
  - socket
```
protected Socket socket
```
    The socket used for network communication.
  - in
```
protected LineInputStream in
```
    The socket input stream.
  - out
```
protected CRLFOutputStream out
```
    The socket output stream.
  - canPost
```
protected boolean canPost
```
    Whether the host permits posting of articles.
  - welcome
```
protected String welcome
```
    The greeting issued by the host when we connected.
  - pendingData
```
protected PendingData pendingData
```
    Pending data, if any.
- Constructor Detail
  - NNTPConnection
```
public NNTPConnection(String hostname)
               throws IOException
```
    Creates a new connection object.
    
    Parameters:
    
    hostname - the hostname or IP address of the news server
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
- Method Detail
  - 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.
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - help
```
public LineIterator help()
                  throws IOException
```
    Requests a help listing.
    
    Returns:
    
    an iterator over a collection of help lines.
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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.
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - next
```
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
    
    Throws:
    
    IOException
  - 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.
    
    Throws:
    
    IOException
    
    See Also:
    
    postComplete()
  - quit
```
public void quit()
          throws IOException
```
    Close the connection. After calling this method, no further calls on this object are valid.
    
    Throws:
    
    IOException
  - slave
```
public void slave()
           throws IOException
```
    Indicates to the server that this is a slave connection.
    
    Throws:
    
    IOException
  - check
```
public boolean check(String messageId)
              throws IOException
```
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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.
    
    Throws:
    
    IOException
    
    See Also:
    
    takethisComplete()
  - 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.
    
    Throws:
    
    IOException
  - 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.
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
    
    See Also:
    
    xgtitle(java.lang.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.
    
    Throws:
    
    IOException
    
    See Also:
    
    xover(gnu.inet.nntp.Range)
  - listSubscriptions
```
public GroupIterator listSubscriptions()
                                throws IOException
```
    Returns a list of newsgroups suitable for new users of the server.
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - modeReader
```
public boolean modeReader()
                   throws IOException
```
    Indicates to the server that this is a user-agent.
    
    Returns:
    
    true if posting is allowed, false otherwise.
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - xhdr
```
public HeaderIterator xhdr(String header,
                           String range)
                    throws IOException
```
    Throws:
    
    IOException
  - xover
```
public OverviewIterator xover(Range range)
                       throws IOException
```
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - 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.
    
    Throws:
    
    IOException
  - 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
    
    Throws:
    
    IOException
  - date
```
public Date date()
          throws IOException
```
    Returns the date on the server.
    
    Throws:
    
    IOException
  - parseResponse
```
protected StatusResponse parseResponse(String line)
                                throws ProtocolException
```
    Parse a response object from a response line sent by the server.
    
    Throws:
    
    ProtocolException
  - 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
    
    Throws:
    
    ProtocolException
  - send
```
protected void send(String line)
             throws IOException
```
    Send a single line to the server.
    
    Parameters:
    
    line - the line to send
    
    Throws:
    
    IOException
  - read
```
protected String read()
               throws IOException
```
    Read a single line from the server.
    
    Returns:
    
    a line of text
    
    Throws:
    
    IOException

Class NNTPConnection

Field Summary

Fields inherited from interface gnu.inet.nntp.NNTPConstants

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logger

NNTP_TRACE

DEFAULT_PORT

hostname

port

socket

in

out

canPost

welcome

pendingData

Constructor Detail

NNTPConnection

NNTPConnection

NNTPConnection

Method Detail

getWelcome

article

article

head

head

body

body

stat

stat

articleImpl

group

help

ihave

last

list

newGroups

newNews

next

post

quit

slave

check

modeStream

takethis

listActive

listActiveTimes

listNewsgroups

listOverviewFmt

listSubscriptions

listGroup

modeReader

xgtitle

xhdr

xover

authinfo

authinfoSimple

authinfoGeneric

date

parseResponse

parseResponse

send

read