org.apache.commons.net.nntp

Class NNTP

Known Direct Subclasses:
NNTPClient

public class NNTP
extends SocketClient

The NNTP class is not meant to be used by itself and is provided only so that you may easily implement your own NNTP client if you so desire. If you have no need to perform your own implementation, you should use NNTPClient. The NNTP class is made public to provide access to various NNTP constants and to make it easier for adventurous programmers (or those with special needs) to interact with the NNTP protocol and implement their own clients. A set of methods with names corresponding to the NNTP command names are provided to facilitate this interaction.

You should keep in mind that the NNTP server may choose to prematurely close a connection if the client has been idle for longer than a given time period or if the server is being shutdown by the operator or some other reason. The NNTP class will detect a premature NNTP server connection closing when it receives a NNTPReply.SERVICE_DISCONTINUED response to a command. When that occurs, the NNTP class method encountering that reply will throw an NNTPConnectionClosedException . NNTPConectionClosedException is a subclass of IOException and therefore need not be caught separately, but if you are going to catch it separately, its catch block must appear before the more general IOException catch block. When you encounter an NNTPConnectionClosedException , you must disconnect the connection with disconnect() to properly clean up the system resources used by NNTP. Before disconnecting, you may check the last reply code and text with getReplyCode and getReplyString.

Rather than list it separately for each method, we mention here that every method communicating with the server and throwing an IOException can also throw a MalformedServerReplyException , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the reply received from the server deviates enough from the protocol specification that it cannot be interpreted in a useful manner despite attempts to be as lenient as possible.

See Also:
NNTPClient, NNTPConnectionClosedException, MalformedServerReplyException

Field Summary

static int
DEFAULT_PORT
The default NNTP port.
protected ProtocolCommandSupport
_commandSupport_
A ProtocolCommandSupport object used to manage the registering of ProtocolCommandListeners and te firing of ProtocolCommandEvents.
protected BufferedReader
_reader_
Wraps SocketClient._input_ to communicate with server.
protected BufferedWriter
_writer_
Wraps SocketClient._output_ to communicate with server.

Fields inherited from class org.apache.commons.net.SocketClient

NETASCII_EOL, _defaultPort_, _input_, _isConnected_, _output_, _socketFactory_, _socket_, _timeout_

Constructor Summary

NNTP()
The default NNTP constructor.

Method Summary

protected void
_connectAction_()
Initiates control connections and gets initial reply, determining if the client is allowed to post to the server.
void
addProtocolCommandListener(ProtocolCommandListener listener)
Adds a ProtocolCommandListener.
int
article()
A convenience method to send the NNTP ARTICLE command to the server, receive the initial reply, and return the reply code.
int
article(String messageId)
A convenience method to send the NNTP ARTICLE command to the server, receive the initial reply, and return the reply code.
int
article(int articleNumber)
A convenience method to send the NNTP ARTICLE command to the server, receive the initial reply, and return the reply code.
int
authinfoPass(String password)
A convenience method to send the AUTHINFO PASS command to the server, receive the reply, and return the reply code.
int
authinfoUser(String username)
A convenience method to send the AUTHINFO USER command to the server, receive the reply, and return the reply code.
int
body()
A convenience method to send the NNTP BODY command to the server, receive the initial reply, and return the reply code.
int
body(String messageId)
A convenience method to send the NNTP BODY command to the server, receive the initial reply, and return the reply code.
int
body(int articleNumber)
A convenience method to send the NNTP BODY command to the server, receive the initial reply, and return the reply code.
void
disconnect()
Closes the connection to the NNTP server and sets to null some internal data so that the memory may be reclaimed by the garbage collector.
int
getReply()
Fetches a reply from the NNTP server and returns the integer reply code.
int
getReplyCode()
Returns the integer value of the reply code of the last NNTP reply.
String
getReplyString()
Returns the entire text of the last NNTP server response exactly as it was received, not including the end of line marker.
int
group(String newsgroup)
A convenience method to send the NNTP GROUP command to the server, receive the reply, and return the reply code.
int
head()
A convenience method to send the NNTP HEAD command to the server, receive the initial reply, and return the reply code.
int
head(String messageId)
A convenience method to send the NNTP HEAD command to the server, receive the initial reply, and return the reply code.
int
head(int articleNumber)
A convenience method to send the NNTP HEAD command to the server, receive the initial reply, and return the reply code.
int
help()
A convenience method to send the NNTP HELP command to the server, receive the reply, and return the reply code.
int
ihave(String messageId)
A convenience method to send the NNTP IHAVE command to the server, receive the reply, and return the reply code.
boolean
isAllowedToPost()
Indicates whether or not the client is allowed to post articles to the server it is currently connected to.
int
last()
A convenience method to send the NNTP LAST command to the server, receive the reply, and return the reply code.
int
list()
A convenience method to send the NNTP LIST command to the server, receive the reply, and return the reply code.
int
listActive(String wildmat)
A convenience wrapper for the extended LIST command that takes an argument, allowing us to selectively list multiple groups.
int
newgroups(String date, String time, boolean GMT, String distributions)
A convenience method to send the NNTP NEWGROUPS command to the server, receive the reply, and return the reply code.
int
newnews(String newsgroups, String date, String time, boolean GMT, String distributions)
A convenience method to send the NNTP NEWGROUPS command to the server, receive the reply, and return the reply code.
int
next()
A convenience method to send the NNTP NEXT command to the server, receive the reply, and return the reply code.
int
post()
A convenience method to send the NNTP POST command to the server, receive the reply, and return the reply code.
int
quit()
A convenience method to send the NNTP QUIT command to the server, receive the reply, and return the reply code.
void
removeProtocolCommandListener(ProtocolCommandListener listener)
Removes a ProtocolCommandListener.
int
sendCommand(String command)
Sends an NNTP command with no arguments to the server, waits for a reply and returns the numerical response code.
int
sendCommand(String command, String args)
Sends an NNTP command to the server, waits for a reply and returns the numerical response code.
int
sendCommand(int command)
Sends an NNTP command with no arguments to the server, waits for a reply and returns the numerical response code.
int
sendCommand(int command, String args)
Sends an NNTP command to the server, waits for a reply and returns the numerical response code.
int
stat()
A convenience method to send the NNTP STAT command to the server, receive the initial reply, and return the reply code.
int
stat(String messageId)
A convenience method to send the NNTP STAT command to the server, receive the initial reply, and return the reply code.
int
stat(int articleNumber)
A convenience method to send the NNTP STAT command to the server, receive the initial reply, and return the reply code.
int
xhdr(String header, String selectedArticles)
A convenience method to send the NNTP XHDR command to the server, receive the reply, and return the reply code.
int
xover(String selectedArticles)
A convenience method to send the NNTP XOVER command to the server, receive the reply, and return the reply code.

Methods inherited from class org.apache.commons.net.SocketClient

_connectAction_, connect, connect, connect, connect, connect, connect, disconnect, getDefaultPort, getDefaultTimeout, getLocalAddress, getLocalPort, getRemoteAddress, getRemotePort, getSoLinger, getSoTimeout, getTcpNoDelay, isConnected, setDefaultPort, setDefaultTimeout, setSoLinger, setSoTimeout, setSocketFactory, setTcpNoDelay, verifyRemote

Field Details

DEFAULT_PORT

public static final int DEFAULT_PORT
The default NNTP port. Its value is 119 according to RFC 977. **
Field Value:
119

_commandSupport_

protected ProtocolCommandSupport _commandSupport_
A ProtocolCommandSupport object used to manage the registering of ProtocolCommandListeners and te firing of ProtocolCommandEvents.

_reader_

protected BufferedReader _reader_
Wraps SocketClient._input_ to communicate with server. Initialized by _connectAction_(). All server reads should be done through this variable.

_writer_

protected BufferedWriter _writer_
Wraps SocketClient._output_ to communicate with server. Initialized by _connectAction_(). All server reads should be done through this variable.

Constructor Details

NNTP

public NNTP()
The default NNTP constructor. Sets the default port to DEFAULT_PORT and initializes internal data structures for saving NNTP reply information.

Method Details

_connectAction_

protected void _connectAction_()
            throws IOException
Overrides:
_connectAction_ in interface SocketClient

addProtocolCommandListener

public void addProtocolCommandListener(ProtocolCommandListener listener)
Adds a ProtocolCommandListener. Delegates this task to _commandSupport_.

Parameters:
listener - The ProtocolCommandListener to add.

article

public int article()
            throws IOException
A convenience method to send the NNTP ARTICLE command to the server, receive the initial reply, and return the reply code.

Returns:
The reply code received from the server.

article

public int article(String messageId)
            throws IOException
A convenience method to send the NNTP ARTICLE command to the server, receive the initial reply, and return the reply code.

Parameters:
messageId - The message identifier of the requested article, including the encapsulating &lt and &gt characters.
Returns:
The reply code received from the server.

article

public int article(int articleNumber)
            throws IOException
A convenience method to send the NNTP ARTICLE command to the server, receive the initial reply, and return the reply code.

Parameters:
articleNumber - The number of the article to request from the currently selected newsgroup.
Returns:
The reply code received from the server.

authinfoPass

public int authinfoPass(String password)
            throws IOException
A convenience method to send the AUTHINFO PASS command to the server, receive the reply, and return the reply code. If this step is required, it should immediately follow the AUTHINFO USER command (See RFC 2980)

Parameters:
password - a valid password.
Returns:
The reply code received from the server. The server should return a 281 or 502 for this command.

authinfoUser

public int authinfoUser(String username)
            throws IOException
A convenience method to send the AUTHINFO USER command to the server, receive the reply, and return the reply code. (See RFC 2980)

Parameters:
username - A valid username.
Returns:
The reply code received from the server. The server should return a 381 or 281 for this command.

body

public int body()
            throws IOException
A convenience method to send the NNTP BODY command to the server, receive the initial reply, and return the reply code.

Returns:
The reply code received from the server.

body

public int body(String messageId)
            throws IOException
A convenience method to send the NNTP BODY command to the server, receive the initial reply, and return the reply code.

Parameters:
messageId - The message identifier of the requested article, including the encapsulating &lt and &gt characters.
Returns:
The reply code received from the server.

body

public int body(int articleNumber)
            throws IOException
A convenience method to send the NNTP BODY command to the server, receive the initial reply, and return the reply code.

Parameters:
articleNumber - The number of the article to request from the currently selected newsgroup.
Returns:
The reply code received from the server.

disconnect

public void disconnect()
            throws IOException
Closes the connection to the NNTP server and sets to null some internal data so that the memory may be reclaimed by the garbage collector. The reply text and code information from the last command is voided so that the memory it used may be reclaimed.

Overrides:
disconnect in interface SocketClient

getReply

public int getReply()
            throws IOException
Fetches a reply from the NNTP server and returns the integer reply code. After calling this method, the actual reply text can be accessed from getReplyString. Only use this method if you are implementing your own NNTP client or if you need to fetch a secondary response from the NNTP server.

Returns:
The integer value of the reply code of the fetched NNTP reply. in response to the command.

getReplyCode

public int getReplyCode()
Returns the integer value of the reply code of the last NNTP reply. You will usually only use this method after you connect to the NNTP server to check that the connection was successful since connect is of type void.

Returns:
The integer value of the reply code of the last NNTP reply.

getReplyString

public String getReplyString()
Returns the entire text of the last NNTP server response exactly as it was received, not including the end of line marker.

Returns:
The entire text from the last NNTP response as a String.

group

public int group(String newsgroup)
            throws IOException
A convenience method to send the NNTP GROUP command to the server, receive the reply, and return the reply code.

Parameters:
newsgroup - The name of the newsgroup to select.
Returns:
The reply code received from the server.

head

public int head()
            throws IOException
A convenience method to send the NNTP HEAD command to the server, receive the initial reply, and return the reply code.

Returns:
The reply code received from the server.

head

public int head(String messageId)
            throws IOException
A convenience method to send the NNTP HEAD command to the server, receive the initial reply, and return the reply code.

Parameters:
messageId - The message identifier of the requested article, including the encapsulating &lt and &gt characters.
Returns:
The reply code received from the server.

head

public int head(int articleNumber)
            throws IOException
A convenience method to send the NNTP HEAD command to the server, receive the initial reply, and return the reply code.

Parameters:
articleNumber - The number of the article to request from the currently selected newsgroup.
Returns:
The reply code received from the server.

help

public int help()
            throws IOException
A convenience method to send the NNTP HELP command to the server, receive the reply, and return the reply code.

Returns:
The reply code received from the server.

ihave

public int ihave(String messageId)
            throws IOException
A convenience method to send the NNTP IHAVE command to the server, receive the reply, and return the reply code.

Parameters:
messageId - The article identifier, including the encapsulating &lt and &gt characters.
Returns:
The reply code received from the server.

isAllowedToPost

public boolean isAllowedToPost()
Indicates whether or not the client is allowed to post articles to the server it is currently connected to.

Returns:
True if the client can post articles to the server, false otherwise.

last

public int last()
            throws IOException
A convenience method to send the NNTP LAST command to the server, receive the reply, and return the reply code.

Returns:
The reply code received from the server.

list

public int list()
            throws IOException
A convenience method to send the NNTP LIST command to the server, receive the reply, and return the reply code.

Returns:
The reply code received from the server.

listActive

public int listActive(String wildmat)
            throws IOException
A convenience wrapper for the extended LIST command that takes an argument, allowing us to selectively list multiple groups.

Parameters:
wildmat - A wildmat (pseudo-regex) pattern. See RFC 2980 for details.
Returns:
the reply code received from the server.

newgroups

public int newgroups(String date,
                     String time,
                     boolean GMT,
                     String distributions)
            throws IOException
A convenience method to send the NNTP NEWGROUPS command to the server, receive the reply, and return the reply code.

Parameters:
date - The date after which to check for new groups. Date format is YYMMDD
time - The time after which to check for new groups. Time format is HHMMSS using a 24-hour clock.
GMT - True if the time is in GMT, false if local server time.
distributions - Comma-separated distribution list to check for new groups. Set to null if no distributions.
Returns:
The reply code received from the server.

newnews

public int newnews(String newsgroups,
                   String date,
                   String time,
                   boolean GMT,
                   String distributions)
            throws IOException
A convenience method to send the NNTP NEWGROUPS command to the server, receive the reply, and return the reply code.

Parameters:
newsgroups - A comma-separated list of newsgroups to check for new news.
date - The date after which to check for new news. Date format is YYMMDD
time - The time after which to check for new news. Time format is HHMMSS using a 24-hour clock.
GMT - True if the time is in GMT, false if local server time.
distributions - Comma-separated distribution list to check for new news. Set to null if no distributions.
Returns:
The reply code received from the server.

next

public int next()
            throws IOException
A convenience method to send the NNTP NEXT command to the server, receive the reply, and return the reply code.

Returns:
The reply code received from the server.

post

public int post()
            throws IOException
A convenience method to send the NNTP POST command to the server, receive the reply, and return the reply code.

Returns:
The reply code received from the server.

quit

public int quit()
            throws IOException
A convenience method to send the NNTP QUIT command to the server, receive the reply, and return the reply code.

Returns:
The reply code received from the server.

removeProtocolCommandListener

public void removeProtocolCommandListener(ProtocolCommandListener listener)
Removes a ProtocolCommandListener. Delegates this task to _commandSupport_.

Parameters:
listener - The ProtocolCommandListener to remove.

sendCommand

public int sendCommand(String command)
            throws IOException
Parameters:
command - The text representation of the NNTP command to send.
Returns:
The integer value of the NNTP reply code returned by the server in response to the command. in response to the command.

sendCommand

public int sendCommand(String command,
                       String args)
            throws IOException
Parameters:
command - The text representation of the NNTP command to send.
args - The arguments to the NNTP command. If this parameter is set to null, then the command is sent with no argument.
Returns:
The integer value of the NNTP reply code returned by the server in response to the command.

sendCommand

public int sendCommand(int command)
            throws IOException
Parameters:
command - The NNTPCommand constant corresponding to the NNTP command to send.
Returns:
The integer value of the NNTP reply code returned by the server in response to the command. in response to the command.

sendCommand

public int sendCommand(int command,
                       String args)
            throws IOException
Parameters:
command - The NNTPCommand constant corresponding to the NNTP command to send.
args - The arguments to the NNTP command. If this parameter is set to null, then the command is sent with no argument.
Returns:
The integer value of the NNTP reply code returned by the server in response to the command. in response to the command.

stat

public int stat()
            throws IOException
A convenience method to send the NNTP STAT command to the server, receive the initial reply, and return the reply code.

Returns:
The reply code received from the server.

stat

public int stat(String messageId)
            throws IOException
A convenience method to send the NNTP STAT command to the server, receive the initial reply, and return the reply code.

Parameters:
messageId - The message identifier of the requested article, including the encapsulating &lt and &gt characters.
Returns:
The reply code received from the server.

stat

public int stat(int articleNumber)
            throws IOException
A convenience method to send the NNTP STAT command to the server, receive the initial reply, and return the reply code.

Parameters:
articleNumber - The number of the article to request from the currently selected newsgroup.
Returns:
The reply code received from the server.

xhdr

public int xhdr(String header,
                String selectedArticles)
            throws IOException
A convenience method to send the NNTP XHDR command to the server, receive the reply, and return the reply code.

Parameters:
header - a String naming a header line (e.g., "subject"). See RFC-1036 for a list of valid header lines.
selectedArticles - a String representation of the range of article headers required. This may be an article number, or a range of article numbers in the form "XXXX-YYYY", where XXXX and YYYY are valid article numbers in the current group. It also may be of the form "XXX-", meaning "return XXX and all following articles" In this revision, the last format is not possible (yet).
Returns:
The reply code received from the server.

xover

public int xover(String selectedArticles)
            throws IOException
A convenience method to send the NNTP XOVER command to the server, receive the reply, and return the reply code.

Parameters:
selectedArticles - a String representation of the range of article headers required. This may be an article number, or a range of article numbers in the form "XXXX-YYYY", where XXXX and YYYY are valid article numbers in the current group. It also may be of the form "XXX-", meaning "return XXX and all following articles" In this revision, the last format is not possible (yet).
Returns:
The reply code received from the server.