org.apache.commons.net.nntp
public class NNTPClient extends 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
{@link org.apache.commons.net.nntp.NNTPReply#SERVICE_DISCONTINUED NNTPReply.SERVICE_DISCONTINUED }
response to a command.
When that occurs, the NNTP class method encountering that reply will throw
an {@link org.apache.commons.net.nntp.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
{@link org.apache.commons.net.nntp.NNTPConnectionClosedException}
, you must disconnect the connection with
{@link org.apache.commons.net.nntp.NNTP#disconnect disconnect() }
to properly clean up the
system resources used by NNTP. Before disconnecting, you may check the
last reply code and text with
{@link org.apache.commons.net.nntp.NNTP#getReplyCode getReplyCode } and
{@link org.apache.commons.net.nntp.NNTP#getReplyString 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 {@link 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.
See Also: NNTP NNTPConnectionClosedException
Method Summary | |
---|---|
boolean | authenticate(String username, String password)
Log into a news server by sending the AUTHINFO USER/AUTHINFO
PASS command sequence. |
boolean | completePendingCommand()
There are a few NNTPClient methods that do not complete the
entire sequence of NNTP commands to complete a transaction. |
Writer | forwardArticle(String articleId) |
String | listHelp()
List the command help from the server.
|
String[] | listNewNews(NewGroupsOrNewsQuery query)
List all new articles added to the NNTP server since a particular
date subject to the conditions of the specified query. |
NewsgroupInfo[] | listNewNewsgroups(NewGroupsOrNewsQuery query)
List all new newsgroups added to the NNTP server since a particular
date subject to the conditions of the specified query. |
NewsgroupInfo[] | listNewsgroups()
List all newsgroups served by the NNTP server. |
NewsgroupInfo[] | listNewsgroups(String wildmat)
An overloaded listNewsgroups() command that allows us to
specify with a pattern what groups we want to list. |
boolean | logout()
Logs out of the news server gracefully by sending the QUIT command.
|
Writer | postArticle()
Post an article to the NNTP server. |
Reader | retrieveArticle(String articleId, ArticlePointer pointer)
Retrieves an article from the NNTP server. |
Reader | retrieveArticle(String articleId) Same as retrieveArticle(articleId, null) ** |
Reader | retrieveArticle() Same as retrieveArticle(null) ** |
Reader | retrieveArticle(int articleNumber, ArticlePointer pointer)
Retrieves an article from the currently selected newsgroup. |
Reader | retrieveArticle(int articleNumber) Same as retrieveArticle(articleNumber, null) ** |
Reader | retrieveArticleBody(String articleId, ArticlePointer pointer)
Retrieves an article body from the NNTP server. |
Reader | retrieveArticleBody(String articleId) Same as retrieveArticleBody(articleId, null) ** |
Reader | retrieveArticleBody() Same as retrieveArticleBody(null) ** |
Reader | retrieveArticleBody(int articleNumber, ArticlePointer pointer)
Retrieves an article body from the currently selected newsgroup. |
Reader | retrieveArticleBody(int articleNumber) Same as retrieveArticleBody(articleNumber, null) ** |
Reader | retrieveArticleHeader(String articleId, ArticlePointer pointer)
Retrieves an article header from the NNTP server. |
Reader | retrieveArticleHeader(String articleId) Same as retrieveArticleHeader(articleId, null) ** |
Reader | retrieveArticleHeader() Same as retrieveArticleHeader(null) ** |
Reader | retrieveArticleHeader(int articleNumber, ArticlePointer pointer)
Retrieves an article header from the currently selected newsgroup. |
Reader | retrieveArticleHeader(int articleNumber) Same as retrieveArticleHeader(articleNumber, null) ** |
Reader | retrieveArticleInfo(int articleNumber)
Return article headers for a specified post.
|
Reader | retrieveArticleInfo(int lowArticleNumber, int highArticleNumber)
Return article headers for all articles between lowArticleNumber
and highArticleNumber, inclusively.
|
Reader | retrieveHeader(String header, int articleNumber)
Return an article header for a specified post.
|
Reader | retrieveHeader(String header, int lowArticleNumber, int highArticleNumber)
Return an article header for all articles between lowArticleNumber
and highArticleNumber, inclusively.
|
boolean | selectArticle(String articleId, ArticlePointer pointer)
Select an article by its unique identifier (including enclosing
< and >) and return its article number and id through the
pointer parameter. |
boolean | selectArticle(String articleId) Same as selectArticle(articleId, null) ** |
boolean | selectArticle(ArticlePointer pointer)
Same as selectArticle(null, articleId) . |
boolean | selectArticle(int articleNumber, ArticlePointer pointer)
Select an article in the currently selected newsgroup by its number.
and return its article number and id through the
pointer parameter. |
boolean | selectArticle(int articleNumber) Same as selectArticle(articleNumber, null) ** |
boolean | selectNewsgroup(String newsgroup, NewsgroupInfo info)
Select the specified newsgroup to be the target of for future article
retrieval and posting operations. |
boolean | selectNewsgroup(String newsgroup) Same as selectNewsgroup(newsgroup, null) ** |
boolean | selectNextArticle(ArticlePointer pointer)
Select the article following the currently selected article in the
currently selected newsgroup and return its number and unique id
through the pointer parameter. |
boolean | selectNextArticle() Same as selectNextArticle(null) ** |
boolean | selectPreviousArticle(ArticlePointer pointer)
Select the article preceeding the currently selected article in the
currently selected newsgroup and return its number and unique id
through the pointer parameter. |
boolean | selectPreviousArticle() Same as selectPreviousArticle(null) ** |
Parameters: username a valid username password the corresponding password
Returns: True for successful login, false for a failure
Throws: IOException
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;
Returns: True if successfully completed, false if not.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Returns: The sever help information.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: query The query restricting how to search for new news. You must add at least one newsgroup to the query.
Returns: 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.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: query The query restricting how to search for new newsgroups.
Returns: 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.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Returns: 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.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Parameters: wildmat a pseudo-regex pattern (cf. RFC 2980)
Returns: 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.
Throws: IOException
Returns: True if successfully completed, false if not.
Throws: IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
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 {@link org.apache.commons.net.nntp.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 {@link #completePendingCommand completePendingCommand() } to finalize the posting and verify its success or failure from the server reply.
Returns: A DotTerminatedMessageWriter to which the article (including header) can be written. Returns null if the command fails.
Throws: IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
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.
Parameters: 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.
Returns: A DotTerminatedMessageReader instance from which the article be read. null if the article does not exist.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
retrieveArticle(articleId, null)
** retrieveArticle(null)
** 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.
Parameters: 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.
Returns: A DotTerminatedMessageReader instance from which the article be read. null if the article does not exist.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
retrieveArticle(articleNumber, null)
** 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.
Parameters: 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.
Returns: A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
retrieveArticleBody(articleId, null)
** retrieveArticleBody(null)
** 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.
Parameters: 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.
Returns: A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
retrieveArticleBody(articleNumber, null)
** 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.
Parameters: 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.
Returns: A DotTerminatedMessageReader instance from which the article header can be read. null if the article does not exist.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
retrieveArticleHeader(articleId, null)
** retrieveArticleHeader(null)
** 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.
Parameters: 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.
Returns: A DotTerminatedMessageReader instance from which the article header can be read. null if the article does not exist.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
retrieveArticleHeader(articleNumber, null)
**Parameters: articleNumber the article to retrieve headers for
Returns: a DotTerminatedReader if successful, null otherwise
Throws: IOException
Parameters: lowArticleNumber highArticleNumber
Returns: a DotTerminatedReader if successful, null otherwise
Throws: IOException
Parameters: header the header to retrieve articleNumber the article to retrieve the header for
Returns: a DotTerminatedReader if successful, null otherwise
Throws: IOException
Parameters: header lowArticleNumber highArticleNumber
Returns: a DotTerminatedReader if successful, null otherwise
Throws: IOException
Parameters: articleId The unique article identifier of the article that is being selectedd. If this parameter is null, the body of the current article is selected 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.
Returns: True if successful, false if not.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
selectArticle(articleId, null)
** selectArticle(null, articleId)
. Useful
for retrieving the current article number.
Parameters: 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.
Returns: True if successful, false if not.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
selectArticle(articleNumber, null)
**Parameters: 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.
Returns: True if the newsgroup exists and was selected, false otherwise.
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
selectNewsgroup(newsgroup, null)
** selectArticle(pointer.articleNumber, pointer)
immediately
afterward.
Parameters: 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.
Returns: True if successful, false if not (e.g., there is no following article).
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
selectNextArticle(null)
** selectArticle(pointer.articleNumber, pointer)
immediately
afterward.
Parameters: 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.
Returns: True if successful, false if not (e.g., there is no previous article).
Throws: NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself. IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
selectPreviousArticle(null)
**