gnu.inet.nntp
Class NNTPConnection

java.lang.Object
  extended by gnu.inet.nntp.NNTPConnection
All 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, Jan Michalica

Field Summary
protected  boolean canPost
          Whether the host permits posting of articles.
static int DEFAULT_PORT
          The default NNTP port.
static int DEFAULT_SSL_PORT
          The default NNTPS port
protected  java.lang.String hostname
          The hostname of the host we are connected to.
protected  LineInputStream in
          The socket input stream.
static java.util.logging.Logger logger
          The logger used for NNTP protocol traces.
static java.util.logging.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  java.net.Socket socket
          The socket used for network communication.
protected  java.lang.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, CONTINUE_TLS_NEGOTIATION, DATE, DATE_OK, ENCRYPTION_OR_AUTH_REQUIRED, 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, STARTTLS, STAT, STREAMING_OK, SYNTAX_ERROR, TAKETHIS, TLS_INIT_ERROR, TRANSFER_FAILED, TRANSFER_PERMISSION_DENIED, TRY_AGAIN_LATER, XGTITLE, XGTITLE_LIST_FOLLOWS, XHDR, XINDEX, XOVER, XPAT, XPATH, XREPLIC, XROVER
 
Constructor Summary
NNTPConnection(java.lang.String hostname)
          Creates a new connection object.
NNTPConnection(java.lang.String hostname, int port)
          Creates a new connection object.
NNTPConnection(java.lang.String hostname, int port, int connectionTimeout, int timeout)
          Creates a new connection object.
NNTPConnection(java.lang.String hostname, int port, int connectionTimeout, int timeout, boolean secure, javax.net.ssl.TrustManager tm, boolean init)
          Creates a new connection object.
NNTPConnection(java.lang.String host, int port, javax.net.ssl.TrustManager tm)
          Creates a new secure connection using the specified trust manager.
 
Method Summary
 ArticleResponse article(int articleNumber)
          Send an article retrieval request to the server.
 ArticleResponse article(java.lang.String messageId)
          Send an article retrieval request to the server.
protected  ArticleResponse articleImpl(java.lang.String command, java.lang.String messageId)
          Performs an ARTICLE, BODY, HEAD, or STAT command.
 boolean authinfo(java.lang.String username, java.lang.String password)
          Basic authentication strategy.
 boolean authinfoGeneric(java.lang.String mechanism, java.lang.String username, java.lang.String password)
          Authenticates the connection using the specified SASL mechanism, username and password.
 boolean authinfoSimple(java.lang.String username, java.lang.String password)
          Implementation of NNTP simple authentication.
 ArticleResponse body(int articleNumber)
          Send an article body retrieval request to the server.
 ArticleResponse body(java.lang.String messageId)
          Send an article body retrieval request to the server.
 boolean check(java.lang.String messageId)
           
 java.util.Date date()
          Returns the date on the server.
protected  javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.TrustManager tm)
          Returns a configured SSLSocketFactory to use in creating new SSL sockets.
 java.lang.String getWelcome()
          Return the welcome message sent by the server in reply to the initial connection.
 GroupResponse group(java.lang.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(java.lang.String messageId)
          Send an article head retrieval request to the server.
 LineIterator help()
          Requests a help listing.
 PostStream ihave(java.lang.String messageId)
          Sends an ihave command indicating that the client has an article with the specified message-id.
 void init()
          Initialises the connection.
 ArticleResponse last()
          Sends a previous article positioning command to the server.
 GroupIterator list()
          Send a group listing command to the server.
 GroupIterator listActive(java.lang.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(java.lang.String group)
          Returns a listing of all the article numbers in the specified newsgroup.
 PairIterator listNewsgroups(java.lang.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(java.util.Date since, java.lang.String[] distributions)
          Returns an iterator over the list of new groups on the server since the specified date.
 LineIterator newNews(java.lang.String newsgroup, java.util.Date since, java.lang.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(java.lang.String line)
          Parse a response object from a response line sent by the server.
protected  StatusResponse parseResponse(java.lang.String line, boolean isListGroup)
          Parse a response object from a response line sent by the server.
 java.io.OutputStream post()
          Post an article.
 void quit()
          Close the connection.
protected  java.lang.String read()
          Read a single line from the server.
protected  void send(java.lang.String line)
          Send a single line to the server.
 void slave()
          Indicates to the server that this is a slave connection.
 boolean starttls()
          Negotiate TLS over the current connection.
 boolean starttls(javax.net.ssl.TrustManager tm)
          This command performs a TLS negotiation.
 ArticleResponse stat(int articleNumber)
          Send an article status request to the server.
 ArticleResponse stat(java.lang.String messageId)
          Send an article status request to the server.
 java.io.OutputStream takethis(java.lang.String messageId)
          Implements the out-of-order takethis command.
 PairIterator xgtitle(java.lang.String wildmat)
          Returns an iterator over the list of newsgroup descriptions.
 HeaderIterator xhdr(java.lang.String header, java.lang.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

NNTP_TRACE

public static final java.util.logging.Level NNTP_TRACE
The network trace level.


DEFAULT_PORT

public static final int DEFAULT_PORT
The default NNTP port.

See Also:
Constant Field Values

DEFAULT_SSL_PORT

public static final int DEFAULT_SSL_PORT
The default NNTPS port

See Also:
Constant Field Values

logger

public static final java.util.logging.Logger logger
The logger used for NNTP protocol traces.


hostname

protected java.lang.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 java.net.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 java.lang.String welcome
The greeting issued by the host when we connected.


pendingData

protected PendingData pendingData
Pending data, if any.

Constructor Detail

NNTPConnection

public NNTPConnection(java.lang.String hostname)
               throws java.io.IOException
Creates a new connection object.

Parameters:
hostname - the hostname or IP address of the news server
Throws:
java.io.IOException

NNTPConnection

public NNTPConnection(java.lang.String hostname,
                      int port)
               throws java.io.IOException
Creates a new connection object.

Parameters:
hostname - the hostname or IP address of the news server
port - the port to connect to
Throws:
java.io.IOException

NNTPConnection

public NNTPConnection(java.lang.String host,
                      int port,
                      javax.net.ssl.TrustManager tm)
               throws java.io.IOException
Creates a new secure connection using the specified trust manager.

Parameters:
host - the name of the host to connect to
port - the port to connect to, or -1 for the default
tm - a trust manager used to check SSL certificates, or null to use the default
Throws:
java.io.IOException

NNTPConnection

public NNTPConnection(java.lang.String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout)
               throws java.io.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:
java.io.IOException

NNTPConnection

public NNTPConnection(java.lang.String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean secure,
                      javax.net.ssl.TrustManager tm,
                      boolean init)
               throws java.io.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
init - initialise the connection
Throws:
java.io.IOException
Method Detail

getSSLSocketFactory

protected javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.TrustManager tm)
                                                      throws java.security.GeneralSecurityException
Returns a configured SSLSocketFactory to use in creating new SSL sockets.

Parameters:
tm - an optional trust manager to use
Throws:
java.security.GeneralSecurityException

init

public void init()
          throws java.io.IOException
Initialises the connection. Unless the init parameter was provided with the value false, do not call this method. Otherwise call it only once after e.g. configuring logging.

Throws:
java.io.IOException

starttls

public boolean starttls()
                 throws java.io.IOException
Negotiate TLS over the current connection. This depends on many features, such as the JSSE classes being in the classpath. Returns true if successful, false otherwise.

Throws:
java.io.IOException

starttls

public boolean starttls(javax.net.ssl.TrustManager tm)
                 throws java.io.IOException
This command performs a TLS negotiation. See RFC 4642 for details.

Parameters:
tm - the custom trust manager to use
Returns:
true if successful, false otherwise
Throws:
java.io.IOException

getWelcome

public java.lang.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 java.io.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:
java.io.IOException

article

public ArticleResponse article(java.lang.String messageId)
                        throws java.io.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:
java.io.IOException

head

public ArticleResponse head(int articleNumber)
                     throws java.io.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:
java.io.IOException

head

public ArticleResponse head(java.lang.String messageId)
                     throws java.io.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:
java.io.IOException

body

public ArticleResponse body(int articleNumber)
                     throws java.io.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:
java.io.IOException

body

public ArticleResponse body(java.lang.String messageId)
                     throws java.io.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:
java.io.IOException

stat

public ArticleResponse stat(int articleNumber)
                     throws java.io.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:
java.io.IOException

stat

public ArticleResponse stat(java.lang.String messageId)
                     throws java.io.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:
java.io.IOException

articleImpl

protected ArticleResponse articleImpl(java.lang.String command,
                                      java.lang.String messageId)
                               throws java.io.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:
java.io.IOException

group

public GroupResponse group(java.lang.String name)
                    throws java.io.IOException
Send a group selection command to the server. Returns a group status response.

Parameters:
name - the name of the group to select
Throws:
java.io.IOException

help

public LineIterator help()
                  throws java.io.IOException
Requests a help listing.

Returns:
an iterator over a collection of help lines.
Throws:
java.io.IOException

ihave

public PostStream ihave(java.lang.String messageId)
                 throws java.io.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:
java.io.IOException

last

public ArticleResponse last()
                     throws java.io.IOException
Sends a previous article positioning command to the server.

Returns:
the article number/message-id pair associated with the new article
Throws:
java.io.IOException

list

public GroupIterator list()
                   throws java.io.IOException
Send a group listing command to the server. Returns a GroupIterator. This must be read fully before other commands are issued.

Throws:
java.io.IOException

newGroups

public LineIterator newGroups(java.util.Date since,
                              java.lang.String[] distributions)
                       throws java.io.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:
java.io.IOException

newNews

public LineIterator newNews(java.lang.String newsgroup,
                            java.util.Date since,
                            java.lang.String[] distributions)
                     throws java.io.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:
java.io.IOException

next

public ArticleResponse next()
                     throws java.io.IOException
Sends a next article positioning command to the server.

Returns:
the article number/message-id pair associated with the new article
Throws:
java.io.IOException

post

public java.io.OutputStream post()
                          throws java.io.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:
java.io.IOException
See Also:
postComplete()

quit

public void quit()
          throws java.io.IOException
Close the connection. After calling this method, no further calls on this object are valid.

Throws:
java.io.IOException

slave

public void slave()
           throws java.io.IOException
Indicates to the server that this is a slave connection.

Throws:
java.io.IOException

check

public boolean check(java.lang.String messageId)
              throws java.io.IOException
Throws:
java.io.IOException

modeStream

public boolean modeStream()
                   throws java.io.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:
java.io.IOException

takethis

public java.io.OutputStream takethis(java.lang.String messageId)
                              throws java.io.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:
java.io.IOException
See Also:
takethisComplete()

listActive

public GroupIterator listActive(java.lang.String wildmat)
                         throws java.io.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:
java.io.IOException

listActiveTimes

public ActiveTimesIterator listActiveTimes()
                                    throws java.io.IOException
Returns an iterator over the active.times file. Each ActiveTime object returned provides details of who created the newsgroup and when.

Throws:
java.io.IOException

listNewsgroups

public PairIterator listNewsgroups(java.lang.String wildmat)
                            throws java.io.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:
java.io.IOException
See Also:
xgtitle(java.lang.String)

listOverviewFmt

public LineIterator listOverviewFmt()
                             throws java.io.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:
java.io.IOException
See Also:
xover(gnu.inet.nntp.Range)

listSubscriptions

public GroupIterator listSubscriptions()
                                throws java.io.IOException
Returns a list of newsgroups suitable for new users of the server.

Throws:
java.io.IOException

listGroup

public ArticleNumberIterator listGroup(java.lang.String group)
                                throws java.io.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:
java.io.IOException

modeReader

public boolean modeReader()
                   throws java.io.IOException
Indicates to the server that this is a user-agent.

Returns:
true if posting is allowed, false otherwise.
Throws:
java.io.IOException

xgtitle

public PairIterator xgtitle(java.lang.String wildmat)
                     throws java.io.IOException
Returns an iterator over the list of newsgroup descriptions.

Parameters:
wildmat - if non-null, the newsgroups to match
Throws:
java.io.IOException

xhdr

public HeaderIterator xhdr(java.lang.String header,
                           java.lang.String range)
                    throws java.io.IOException
Throws:
java.io.IOException

xover

public OverviewIterator xover(Range range)
                       throws java.io.IOException
Throws:
java.io.IOException

authinfo

public boolean authinfo(java.lang.String username,
                        java.lang.String password)
                 throws java.io.IOException
Basic authentication strategy.

Parameters:
username - the user to authenticate
password - the(cleartext) password
Returns:
true on success, false on failure
Throws:
java.io.IOException

authinfoSimple

public boolean authinfoSimple(java.lang.String username,
                              java.lang.String password)
                       throws java.io.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:
java.io.IOException

authinfoGeneric

public boolean authinfoGeneric(java.lang.String mechanism,
                               java.lang.String username,
                               java.lang.String password)
                        throws java.io.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:
java.io.IOException

date

public java.util.Date date()
                    throws java.io.IOException
Returns the date on the server.

Throws:
java.io.IOException

parseResponse

protected StatusResponse parseResponse(java.lang.String line)
                                throws java.net.ProtocolException
Parse a response object from a response line sent by the server.

Throws:
java.net.ProtocolException

parseResponse

protected StatusResponse parseResponse(java.lang.String line,
                                       boolean isListGroup)
                                throws java.net.ProtocolException
Parse a response object from a response line sent by the server.

Parameters:
isListGroup - whether we are invoking the LISTGROUP command
Throws:
java.net.ProtocolException

send

protected void send(java.lang.String line)
             throws java.io.IOException
Send a single line to the server.

Parameters:
line - the line to send
Throws:
java.io.IOException

read

protected java.lang.String read()
                         throws java.io.IOException
Read a single line from the server.

Returns:
a line of text
Throws:
java.io.IOException


© Copyright 2003 The Free Software Foundation, all rights reserved