NNTPClient encapsulates all the functionality necessary to post and
retrieve articles from an NNTP server. As with all classes derived
from
SocketClient
,
you must first connect to the server with
connect
before doing anything, and finally
disconnect()
after you're completely finished interacting with the server.
Remember that the
isAllowedToPost()
method is defined in
NNTP
.
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
org.apache.commons.net.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.
authenticate
public boolean authenticate(String username,
String password)
throws IOException
Log into a news server by sending the AUTHINFO USER/AUTHINFO
PASS command sequence. This is usually sent in response to a
480 reply code from the NNTP server.
username
- a valid usernamepassword
- the corresponding password
- True for successful login, false for a failure
completePendingCommand
public boolean completePendingCommand()
throws IOException
There are a few NNTPClient methods that do not complete the
entire sequence of NNTP commands to complete a transaction. These
commands require some action by the programmer after the reception
of a positive preliminary command. After the programmer's code
completes its actions, it must call this method to receive
the completion reply from the server and verify the success of the
entire transaction.
For example
writer = client.postArticle();
if(writer == null) // failure
return false;
header = new SimpleNNTPHeader("foobar@foo.com", "Just testing");
header.addNewsgroup("alt.test");
writer.write(header.toString());
writer.write("This is just a test");
writer.close();
if(!client.completePendingCommand()) // failure
return false;
- True if successfully completed, false if not.
forwardArticle
public Writer forwardArticle(String articleId)
throws IOException
listHelp
public String listHelp()
throws IOException
List the command help from the server.
- The sever help information.
listNewNews
public String[] listNewNews(NewGroupsOrNewsQuery query)
throws IOException
List all new articles added to the NNTP server since a particular
date subject to the conditions of the specified query. If no new
new news is found, a zero length array will be returned. If the
command fails, null will be returned. You must add at least one
newsgroup to the query, else the command will fail. Each String
in the returned array is a unique message identifier including the
enclosing < and >.
query
- The query restricting how to search for new news. You
must add at least one newsgroup to the query.
- An array of String instances containing the unique message
identifiers for each new article added to the NNTP server. If no
new news is found, a zero length array will be returned. If the
command fails, null will be returned.
listNewNewsgroups
public NewsgroupInfo[] listNewNewsgroups(NewGroupsOrNewsQuery query)
throws IOException
List all new newsgroups added to the NNTP server since a particular
date subject to the conditions of the specified query. If no new
newsgroups were added, a zero length array will be returned. If the
command fails, null will be returned.
query
- The query restricting how to search for new newsgroups.
- An array of NewsgroupInfo instances containing the information
for each new newsgroup added to the NNTP server. If no newsgroups
were added, a zero length array will be returned. If the command
fails, null will be returned.
listNewsgroups
public NewsgroupInfo[] listNewsgroups()
throws IOException
List all newsgroups served by the NNTP server. If no newsgroups
are served, a zero length array will be returned. If the command
fails, null will be returned.
- An array of NewsgroupInfo instances containing the information
for each newsgroup served by the NNTP server. If no newsgroups
are served, a zero length array will be returned. If the command
fails, null will be returned.
listNewsgroups
public NewsgroupInfo[] listNewsgroups(String wildmat)
throws IOException
An overloaded listNewsgroups() command that allows us to
specify with a pattern what groups we want to list. Wraps the
LIST ACTIVE command.
wildmat
- a pseudo-regex pattern (cf. RFC 2980)
- An array of NewsgroupInfo instances containing the information
for each newsgroup served by the NNTP server corresponding to the
supplied pattern. If no such newsgroups are served, a zero length
array will be returned. If the command fails, null will be returned.
logout
public boolean logout()
throws IOException
Logs out of the news server gracefully by sending the QUIT command.
However, you must still disconnect from the server before you can open
a new connection.
- True if successfully completed, false if not.
postArticle
public Writer postArticle()
throws IOException
Post an article to the NNTP server. This method returns a
DotTerminatedMessageWriter instance to which the article can be
written. Null is returned if the posting attempt fails. You
should check
isAllowedToPost()
before trying to post. However, a posting
attempt can fail due to malformed headers.
You must not issue any commands to the NNTP server (i.e., call any
(other methods) until you finish writing to the returned Writer
instance and close it. The NNTP protocol uses the same stream for
issuing commands as it does for returning results. Therefore the
returned Writer actually writes directly to the NNTP connection.
After you close the writer, you can execute new commands. If you
do not follow these requirements your program will not work properly.
Different NNTP servers will require different header formats, but
you can use the provided
SimpleNNTPHeader
class to construct the bare minimum acceptable header for most
news readers. To construct more complicated headers you should
refer to RFC 822. When the Java Mail API is finalized, you will be
able to use it to compose fully compliant Internet text messages.
The DotTerminatedMessageWriter takes care of doubling line-leading
dots and ending the message with a single dot upon closing, so all
you have to worry about is writing the header and the message.
Upon closing the returned Writer, you need to call
completePendingCommand()
to finalize the posting and verify its success or failure from
the server reply.
- A DotTerminatedMessageWriter to which the article (including
header) can be written. Returns null if the command fails.
retrieveArticle
public Reader retrieveArticle()
throws IOException
Same as retrieveArticle(null)
**
retrieveArticle
public Reader retrieveArticle(String articleId)
throws IOException
Same as retrieveArticle(articleId, null)
**
retrieveArticle
public Reader retrieveArticle(String articleId,
ArticlePointer pointer)
throws IOException
Retrieves an article from the NNTP server. The article is referenced
by its unique article identifier (including the enclosing < and >).
The article number and identifier contained in the server reply
are returned through an ArticlePointer. The
articleId
field of the ArticlePointer cannot always be trusted because some
NNTP servers do not correctly follow the RFC 977 reply format.
A DotTerminatedMessageReader is returned from which the article can
be read. If the article does not exist, null is returned.
You must not issue any commands to the NNTP server (i.e., call any
other methods) until you finish reading the message from the returned
Reader instance.
The NNTP protocol uses the same stream for issuing commands as it does
for returning results. Therefore the returned Reader actually reads
directly from the NNTP connection. After the end of message has been
reached, new commands can be executed and their replies read. If
you do not follow these requirements, your program will not work
properly.
articleId
- The unique article identifier of the article to
retrieve. If this parameter is null, the currently selected
article is retrieved.pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- A DotTerminatedMessageReader instance from which the article
be read. null if the article does not exist.
retrieveArticle
public Reader retrieveArticle(int articleNumber)
throws IOException
Same as retrieveArticle(articleNumber, null)
**
retrieveArticle
public Reader retrieveArticle(int articleNumber,
ArticlePointer pointer)
throws IOException
Retrieves an article from the currently selected newsgroup. The
article is referenced by its article number.
The article number and identifier contained in the server reply
are returned through an ArticlePointer. The
articleId
field of the ArticlePointer cannot always be trusted because some
NNTP servers do not correctly follow the RFC 977 reply format.
A DotTerminatedMessageReader is returned from which the article can
be read. If the article does not exist, null is returned.
You must not issue any commands to the NNTP server (i.e., call any
other methods) until you finish reading the message from the returned
Reader instance.
The NNTP protocol uses the same stream for issuing commands as it does
for returning results. Therefore the returned Reader actually reads
directly from the NNTP connection. After the end of message has been
reached, new commands can be executed and their replies read. If
you do not follow these requirements, your program will not work
properly.
articleNumber
- The number of the the article to
retrieve.pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- A DotTerminatedMessageReader instance from which the article
be read. null if the article does not exist.
retrieveArticleBody
public Reader retrieveArticleBody()
throws IOException
Same as retrieveArticleBody(null)
**
retrieveArticleBody
public Reader retrieveArticleBody(String articleId)
throws IOException
Same as retrieveArticleBody(articleId, null)
**
retrieveArticleBody
public Reader retrieveArticleBody(String articleId,
ArticlePointer pointer)
throws IOException
Retrieves an article body from the NNTP server. The article is
referenced
by its unique article identifier (including the enclosing < and >).
The article number and identifier contained in the server reply
are returned through an ArticlePointer. The
articleId
field of the ArticlePointer cannot always be trusted because some
NNTP servers do not correctly follow the RFC 977 reply format.
A DotTerminatedMessageReader is returned from which the article can
be read. If the article does not exist, null is returned.
You must not issue any commands to the NNTP server (i.e., call any
other methods) until you finish reading the message from the returned
Reader instance.
The NNTP protocol uses the same stream for issuing commands as it does
for returning results. Therefore the returned Reader actually reads
directly from the NNTP connection. After the end of message has been
reached, new commands can be executed and their replies read. If
you do not follow these requirements, your program will not work
properly.
articleId
- The unique article identifier of the article whose
body is being retrieved. If this parameter is null, the
body of the currently selected article is retrieved.pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- A DotTerminatedMessageReader instance from which the article
body can be read. null if the article does not exist.
retrieveArticleBody
public Reader retrieveArticleBody(int articleNumber)
throws IOException
Same as retrieveArticleBody(articleNumber, null)
**
retrieveArticleBody
public Reader retrieveArticleBody(int articleNumber,
ArticlePointer pointer)
throws IOException
Retrieves an article body from the currently selected newsgroup. The
article is referenced by its article number.
The article number and identifier contained in the server reply
are returned through an ArticlePointer. The
articleId
field of the ArticlePointer cannot always be trusted because some
NNTP servers do not correctly follow the RFC 977 reply format.
A DotTerminatedMessageReader is returned from which the article can
be read. If the article does not exist, null is returned.
You must not issue any commands to the NNTP server (i.e., call any
other methods) until you finish reading the message from the returned
Reader instance.
The NNTP protocol uses the same stream for issuing commands as it does
for returning results. Therefore the returned Reader actually reads
directly from the NNTP connection. After the end of message has been
reached, new commands can be executed and their replies read. If
you do not follow these requirements, your program will not work
properly.
articleNumber
- The number of the the article whose body is
being retrieved.pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- A DotTerminatedMessageReader instance from which the article
body can be read. null if the article does not exist.
retrieveArticleHeader
public Reader retrieveArticleHeader()
throws IOException
Same as retrieveArticleHeader(null)
**
retrieveArticleHeader
public Reader retrieveArticleHeader(String articleId)
throws IOException
Same as retrieveArticleHeader(articleId, null)
**
retrieveArticleHeader
public Reader retrieveArticleHeader(String articleId,
ArticlePointer pointer)
throws IOException
Retrieves an article header from the NNTP server. The article is
referenced
by its unique article identifier (including the enclosing < and >).
The article number and identifier contained in the server reply
are returned through an ArticlePointer. The
articleId
field of the ArticlePointer cannot always be trusted because some
NNTP servers do not correctly follow the RFC 977 reply format.
A DotTerminatedMessageReader is returned from which the article can
be read. If the article does not exist, null is returned.
You must not issue any commands to the NNTP server (i.e., call any
other methods) until you finish reading the message from the returned
Reader instance.
The NNTP protocol uses the same stream for issuing commands as it does
for returning results. Therefore the returned Reader actually reads
directly from the NNTP connection. After the end of message has been
reached, new commands can be executed and their replies read. If
you do not follow these requirements, your program will not work
properly.
articleId
- The unique article identifier of the article whose
header is being retrieved. If this parameter is null, the
header of the currently selected article is retrieved.pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- A DotTerminatedMessageReader instance from which the article
header can be read. null if the article does not exist.
retrieveArticleHeader
public Reader retrieveArticleHeader(int articleNumber)
throws IOException
Same as retrieveArticleHeader(articleNumber, null)
**
retrieveArticleHeader
public Reader retrieveArticleHeader(int articleNumber,
ArticlePointer pointer)
throws IOException
Retrieves an article header from the currently selected newsgroup. The
article is referenced by its article number.
The article number and identifier contained in the server reply
are returned through an ArticlePointer. The
articleId
field of the ArticlePointer cannot always be trusted because some
NNTP servers do not correctly follow the RFC 977 reply format.
A DotTerminatedMessageReader is returned from which the article can
be read. If the article does not exist, null is returned.
You must not issue any commands to the NNTP server (i.e., call any
other methods) until you finish reading the message from the returned
Reader instance.
The NNTP protocol uses the same stream for issuing commands as it does
for returning results. Therefore the returned Reader actually reads
directly from the NNTP connection. After the end of message has been
reached, new commands can be executed and their replies read. If
you do not follow these requirements, your program will not work
properly.
articleNumber
- The number of the the article whose header is
being retrieved.pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- A DotTerminatedMessageReader instance from which the article
header can be read. null if the article does not exist.
retrieveArticleInfo
public Reader retrieveArticleInfo(int articleNumber)
throws IOException
Return article headers for a specified post.
articleNumber
- the article to retrieve headers for
- a DotTerminatedReader if successful, null otherwise
retrieveArticleInfo
public Reader retrieveArticleInfo(int lowArticleNumber,
int highArticleNumber)
throws IOException
Return article headers for all articles between lowArticleNumber
and highArticleNumber, inclusively.
lowArticleNumber
- highArticleNumber
-
- a DotTerminatedReader if successful, null otherwise
retrieveHeader
public Reader retrieveHeader(String header,
int articleNumber)
throws IOException
Return an article header for a specified post.
header
- the header to retrievearticleNumber
- the article to retrieve the header for
- a DotTerminatedReader if successful, null otherwise
retrieveHeader
public Reader retrieveHeader(String header,
int lowArticleNumber,
int highArticleNumber)
throws IOException
Return an article header for all articles between lowArticleNumber
and highArticleNumber, inclusively.
header
- lowArticleNumber
- highArticleNumber
-
- a DotTerminatedReader if successful, null otherwise
selectArticle
public boolean selectArticle(ArticlePointer pointer)
throws IOException
Same as selectArticle(null, articleId)
. Useful
for retrieving the current article number.
selectArticle
public boolean selectArticle(String articleId)
throws IOException
Same as selectArticle(articleId, null)
**
selectArticle
public boolean selectArticle(String articleId,
ArticlePointer pointer)
throws IOException
Select an article by its unique identifier (including enclosing
< and >) and return its article number and id through the
pointer parameter. This is achieved through the STAT command.
According to RFC 977, this will NOT set the current article pointer
on the server. To do that, you must reference the article by its
number.
articleId
- The unique article identifier of the article that
is being selectedd. If this parameter is null, the
body of the current article is selectedpointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- True if successful, false if not.
selectArticle
public boolean selectArticle(int articleNumber)
throws IOException
Same as selectArticle(articleNumber, null)
**
selectArticle
public boolean selectArticle(int articleNumber,
ArticlePointer pointer)
throws IOException
Select an article in the currently selected newsgroup by its number.
and return its article number and id through the
pointer parameter. This is achieved through the STAT command.
According to RFC 977, this WILL set the current article pointer
on the server. Use this command to select an article before retrieving
it, or to obtain an article's unique identifier given its number.
articleNumber
- The number of the article to select from the
currently selected newsgroup.pointer
- A parameter through which to return the article's
number and unique id. Although the articleId field cannot always
be trusted because of server deviations from RFC 977 reply formats,
we haven't found a server that misformats this information in response
to this particular command. You may set this parameter to null if
you do not desire to retrieve the returned article information.
- True if successful, false if not.
selectNewsgroup
public boolean selectNewsgroup(String newsgroup)
throws IOException
Same as selectNewsgroup(newsgroup, null)
**
selectNewsgroup
public boolean selectNewsgroup(String newsgroup,
NewsgroupInfo info)
throws IOException
Select the specified newsgroup to be the target of for future article
retrieval and posting operations. Also return the newsgroup
information contained in the server reply through the info parameter.
newsgroup
- The newsgroup to select.info
- A parameter through which the newsgroup information of
the selected newsgroup contained in the server reply is returned.
Set this to null if you do not desire this information.
- True if the newsgroup exists and was selected, false otherwise.
selectNextArticle
public boolean selectNextArticle()
throws IOException
Same as selectNextArticle(null)
**
selectNextArticle
public boolean selectNextArticle(ArticlePointer pointer)
throws IOException
Select the article following the currently selected article in the
currently selected newsgroup and return its number and unique id
through the pointer parameter. Because of deviating server
implementations, the articleId information cannot be trusted. To
obtain the article identifier, issue a
selectArticle(pointer.articleNumber, pointer)
immediately
afterward.
pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- True if successful, false if not (e.g., there is no following
article).
selectPreviousArticle
public boolean selectPreviousArticle()
throws IOException
Same as selectPreviousArticle(null)
**
selectPreviousArticle
public boolean selectPreviousArticle(ArticlePointer pointer)
throws IOException
Select the article preceeding the currently selected article in the
currently selected newsgroup and return its number and unique id
through the pointer parameter. Because of deviating server
implementations, the articleId information cannot be trusted. To
obtain the article identifier, issue a
selectArticle(pointer.articleNumber, pointer)
immediately
afterward.
pointer
- A parameter through which to return the article's
number and unique id. The articleId field cannot always be trusted
because of server deviations from RFC 977 reply formats. You may
set this parameter to null if you do not desire to retrieve the
returned article information.
- True if successful, false if not (e.g., there is no previous
article).