gnu.inet.nntp

Class NNTPConnection

java.lang.Object

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

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.
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

Constructors

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

Methods

Modifier and Type	Method and Description
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