|
|||||||||
| Home >> All >> org >> apache >> commons >> net >> [ nntp overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
org.apache.commons.net.nntp
Class NNTPClient

java.lang.Objectorg.apache.commons.net.SocketClient
org.apache.commons.net.nntp.NNTP
org.apache.commons.net.nntp.NNTPClient
- public class NNTPClient
- extends NNTP
NNTPClient encapsulates all the functionality necessary to post and retrieve articles from an NNTP server. As with all classes derived from org.apache.commons.net.SocketClient, you must first connect to the server with connect 55 before doing anything, and finally disconnect() 55 after you're completely finished interacting with the server. Remember that the isAllowedToPost() 55 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 55
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() 55
to properly clean up the
system resources used by NNTP. Before disconnecting, you may check the
last reply code and text with
getReplyCode 55 and
getReplyString 55 .
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.
| Field Summary |
| Fields inherited from class org.apache.commons.net.nntp.NNTP |
_commandSupport_, _isAllowedToPost, _reader_, _replyCode, _replyString, _writer_, DEFAULT_PORT |
| Fields inherited from class org.apache.commons.net.SocketClient |
_defaultPort_, _input_, _isConnected_, _output_, _socket_, _socketFactory_, _timeout_, NETASCII_EOL |
| Constructor Summary | |
NNTPClient()
|
|
| Method Summary | |
private void |
__parseArticlePointer(java.lang.String reply,
ArticlePointer pointer)
|
private void |
__parseGroupReply(java.lang.String reply,
NewsgroupInfo info)
|
private NewsgroupInfo |
__parseNewsgroupListEntry(java.lang.String entry)
|
private NewsgroupInfo[] |
__readNewsgroupListing()
|
private java.io.Reader |
__retrieve(int command,
int articleNumber,
ArticlePointer pointer)
|
private java.io.Reader |
__retrieve(int command,
java.lang.String articleId,
ArticlePointer pointer)
|
private java.io.Reader |
__retrieveArticleInfo(java.lang.String articleRange)
Private implementation of XOVER functionality. |
private java.io.Reader |
__retrieveHeader(java.lang.String header,
java.lang.String articleRange)
Private implementation of XHDR functionality. |
boolean |
authenticate(java.lang.String username,
java.lang.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. |
java.io.Writer |
forwardArticle(java.lang.String articleId)
|
java.lang.String |
listHelp()
List the command help from the server. |
java.lang.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(java.lang.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. |
java.io.Writer |
postArticle()
Post an article to the NNTP server. |
java.io.Reader |
retrieveArticle()
Same as retrieveArticle(null) |
java.io.Reader |
retrieveArticle(int articleNumber)
Same as retrieveArticle(articleNumber, null) |
java.io.Reader |
retrieveArticle(int articleNumber,
ArticlePointer pointer)
Retrieves an article from the currently selected newsgroup. |
java.io.Reader |
retrieveArticle(java.lang.String articleId)
Same as retrieveArticle(articleId, null) |
java.io.Reader |
retrieveArticle(java.lang.String articleId,
ArticlePointer pointer)
Retrieves an article from the NNTP server. |
java.io.Reader |
retrieveArticleBody()
Same as retrieveArticleBody(null) |
java.io.Reader |
retrieveArticleBody(int articleNumber)
Same as retrieveArticleBody(articleNumber, null) |
java.io.Reader |
retrieveArticleBody(int articleNumber,
ArticlePointer pointer)
Retrieves an article body from the currently selected newsgroup. |
java.io.Reader |
retrieveArticleBody(java.lang.String articleId)
Same as retrieveArticleBody(articleId, null) |
java.io.Reader |
retrieveArticleBody(java.lang.String articleId,
ArticlePointer pointer)
Retrieves an article body from the NNTP server. |
java.io.Reader |
retrieveArticleHeader()
Same as retrieveArticleHeader(null) |
java.io.Reader |
retrieveArticleHeader(int articleNumber)
Same as retrieveArticleHeader(articleNumber, null) |
java.io.Reader |
retrieveArticleHeader(int articleNumber,
ArticlePointer pointer)
Retrieves an article header from the currently selected newsgroup. |
java.io.Reader |
retrieveArticleHeader(java.lang.String articleId)
Same as retrieveArticleHeader(articleId, null) |
java.io.Reader |
retrieveArticleHeader(java.lang.String articleId,
ArticlePointer pointer)
Retrieves an article header from the NNTP server. |
java.io.Reader |
retrieveArticleInfo(int articleNumber)
Return article headers for a specified post. |
java.io.Reader |
retrieveArticleInfo(int lowArticleNumber,
int highArticleNumber)
Return article headers for all articles between lowArticleNumber and highArticleNumber, inclusively. |
java.io.Reader |
retrieveHeader(java.lang.String header,
int articleNumber)
Return an article header for a specified post. |
java.io.Reader |
retrieveHeader(java.lang.String header,
int lowArticleNumber,
int highArticleNumber)
Return an article header for all articles between lowArticleNumber and highArticleNumber, inclusively. |
boolean |
selectArticle(ArticlePointer pointer)
Same as selectArticle(null, articleId) . |
boolean |
selectArticle(int articleNumber)
Same as selectArticle(articleNumber, null) |
boolean |
selectArticle(int articleNumber,
ArticlePointer pointer)
Select an article in the currently selected newsgroup by its number. |
boolean |
selectArticle(java.lang.String articleId)
Same as selectArticle(articleId, null) |
boolean |
selectArticle(java.lang.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 |
selectNewsgroup(java.lang.String newsgroup)
Same as selectNewsgroup(newsgroup, null) |
boolean |
selectNewsgroup(java.lang.String newsgroup,
NewsgroupInfo info)
Select the specified newsgroup to be the target of for future article retrieval and posting operations. |
boolean |
selectNextArticle()
Same as selectNextArticle(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 |
selectPreviousArticle()
Same as selectPreviousArticle(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. |
| Methods inherited from class org.apache.commons.net.nntp.NNTP |
_connectAction_, addProtocolCommandListener, article, article, article, authinfoPass, authinfoUser, body, body, body, disconnect, getReply, getReplyCode, getReplyString, group, head, head, head, help, ihave, isAllowedToPost, last, list, listActive, newgroups, newnews, next, post, quit, removeProtocolCommandListener, sendCommand, sendCommand, sendCommand, sendCommand, stat, stat, stat, xhdr, xover |
| Methods inherited from class org.apache.commons.net.SocketClient |
connect, connect, connect, connect, connect, connect, getDefaultPort, getDefaultTimeout, getLocalAddress, getLocalPort, getRemoteAddress, getRemotePort, getSoLinger, getSoTimeout, getTcpNoDelay, isConnected, setDefaultPort, setDefaultTimeout, setSocketFactory, setSoLinger, setSoTimeout, setTcpNoDelay, verifyRemote |
| Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
NNTPClient
public NNTPClient()
| Method Detail |
__parseArticlePointer
private void __parseArticlePointer(java.lang.String reply, ArticlePointer pointer) throws org.apache.commons.net.MalformedServerReplyException
__parseGroupReply
private void __parseGroupReply(java.lang.String reply, NewsgroupInfo info) throws org.apache.commons.net.MalformedServerReplyException
__parseNewsgroupListEntry
private NewsgroupInfo __parseNewsgroupListEntry(java.lang.String entry)
__readNewsgroupListing
private NewsgroupInfo[] __readNewsgroupListing() throws java.io.IOException
__retrieve
private java.io.Reader __retrieve(int command, java.lang.String articleId, ArticlePointer pointer) throws java.io.IOException
__retrieve
private java.io.Reader __retrieve(int command, int articleNumber, ArticlePointer pointer) throws java.io.IOException
retrieveArticle
public java.io.Reader retrieveArticle(java.lang.String articleId, ArticlePointer pointer) throws java.io.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
articleIdfield 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.
retrieveArticle
public java.io.Reader retrieveArticle(java.lang.String articleId) throws java.io.IOException
- Same as
retrieveArticle(articleId, null)
retrieveArticle
public java.io.Reader retrieveArticle() throws java.io.IOException
- Same as
retrieveArticle(null)
retrieveArticle
public java.io.Reader retrieveArticle(int articleNumber, ArticlePointer pointer) throws java.io.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
articleIdfield 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.
retrieveArticle
public java.io.Reader retrieveArticle(int articleNumber) throws java.io.IOException
- Same as
retrieveArticle(articleNumber, null)
retrieveArticleHeader
public java.io.Reader retrieveArticleHeader(java.lang.String articleId, ArticlePointer pointer) throws java.io.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
articleIdfield 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.
retrieveArticleHeader
public java.io.Reader retrieveArticleHeader(java.lang.String articleId) throws java.io.IOException
- Same as
retrieveArticleHeader(articleId, null)
retrieveArticleHeader
public java.io.Reader retrieveArticleHeader() throws java.io.IOException
- Same as
retrieveArticleHeader(null)
retrieveArticleHeader
public java.io.Reader retrieveArticleHeader(int articleNumber, ArticlePointer pointer) throws java.io.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
articleIdfield 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.
retrieveArticleHeader
public java.io.Reader retrieveArticleHeader(int articleNumber) throws java.io.IOException
- Same as
retrieveArticleHeader(articleNumber, null)
retrieveArticleBody
public java.io.Reader retrieveArticleBody(java.lang.String articleId, ArticlePointer pointer) throws java.io.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
articleIdfield 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.
retrieveArticleBody
public java.io.Reader retrieveArticleBody(java.lang.String articleId) throws java.io.IOException
- Same as
retrieveArticleBody(articleId, null)
retrieveArticleBody
public java.io.Reader retrieveArticleBody() throws java.io.IOException
- Same as
retrieveArticleBody(null)
retrieveArticleBody
public java.io.Reader retrieveArticleBody(int articleNumber, ArticlePointer pointer) throws java.io.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
articleIdfield 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.
retrieveArticleBody
public java.io.Reader retrieveArticleBody(int articleNumber) throws java.io.IOException
- Same as
retrieveArticleBody(articleNumber, null)
selectNewsgroup
public boolean selectNewsgroup(java.lang.String newsgroup, NewsgroupInfo info) throws java.io.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.
selectNewsgroup
public boolean selectNewsgroup(java.lang.String newsgroup) throws java.io.IOException
- Same as
selectNewsgroup(newsgroup, null)
listHelp
public java.lang.String listHelp() throws java.io.IOException
- List the command help from the server.
selectArticle
public boolean selectArticle(java.lang.String articleId, ArticlePointer pointer) throws java.io.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.
selectArticle
public boolean selectArticle(java.lang.String articleId) throws java.io.IOException
- Same as
selectArticle(articleId, null)
selectArticle
public boolean selectArticle(ArticlePointer pointer) throws java.io.IOException
- Same as
selectArticle(null, articleId). Useful for retrieving the current article number.
selectArticle
public boolean selectArticle(int articleNumber,
ArticlePointer pointer)
throws java.io.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.
selectArticle
public boolean selectArticle(int articleNumber)
throws java.io.IOException
- Same as
selectArticle(articleNumber, null)
selectPreviousArticle
public boolean selectPreviousArticle(ArticlePointer pointer) throws java.io.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.
selectPreviousArticle
public boolean selectPreviousArticle()
throws java.io.IOException
- Same as
selectPreviousArticle(null)
selectNextArticle
public boolean selectNextArticle(ArticlePointer pointer) throws java.io.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.
selectNextArticle
public boolean selectNextArticle()
throws java.io.IOException
- Same as
selectNextArticle(null)
listNewsgroups
public NewsgroupInfo[] listNewsgroups() throws java.io.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.
listNewsgroups
public NewsgroupInfo[] listNewsgroups(java.lang.String wildmat) throws java.io.IOException
- An overloaded listNewsgroups() command that allows us to
specify with a pattern what groups we want to list. Wraps the
LIST ACTIVE command.
listNewNewsgroups
public NewsgroupInfo[] listNewNewsgroups(NewGroupsOrNewsQuery query) throws java.io.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.
listNewNews
public java.lang.String[] listNewNews(NewGroupsOrNewsQuery query) throws java.io.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 >.
completePendingCommand
public boolean completePendingCommand()
throws java.io.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;
postArticle
public java.io.Writer postArticle() throws java.io.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() 55
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() 55 to finalize the posting and verify its success or failure from the server reply.
forwardArticle
public java.io.Writer forwardArticle(java.lang.String articleId) throws java.io.IOException
logout
public boolean logout()
throws java.io.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.
authenticate
public boolean authenticate(java.lang.String username, java.lang.String password) throws java.io.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.
__retrieveArticleInfo
private java.io.Reader __retrieveArticleInfo(java.lang.String articleRange) throws java.io.IOException
- Private implementation of XOVER functionality.
See
NNTP.xover(java.lang.String)55 for legal agument formats. Alternatively, read RFC 2980 :-)
retrieveArticleInfo
public java.io.Reader retrieveArticleInfo(int articleNumber) throws java.io.IOException
- Return article headers for a specified post.
retrieveArticleInfo
public java.io.Reader retrieveArticleInfo(int lowArticleNumber, int highArticleNumber) throws java.io.IOException
- Return article headers for all articles between lowArticleNumber
and highArticleNumber, inclusively.
__retrieveHeader
private java.io.Reader __retrieveHeader(java.lang.String header, java.lang.String articleRange) throws java.io.IOException
- Private implementation of XHDR functionality.
See
NNTP.xhdr(java.lang.String, java.lang.String)55 for legal agument formats. Alternatively, read RFC 1036.
retrieveHeader
public java.io.Reader retrieveHeader(java.lang.String header, int articleNumber) throws java.io.IOException
- Return an article header for a specified post.
retrieveHeader
public java.io.Reader retrieveHeader(java.lang.String header, int lowArticleNumber, int highArticleNumber) throws java.io.IOException
- Return an article header for all articles between lowArticleNumber
and highArticleNumber, inclusively.
|
|||||||||
| Home >> All >> org >> apache >> commons >> net >> [ nntp overview ] | PREV CLASS NEXT CLASS | ||||||||
SUMMARY: JAVADOC | SOURCE | DOWNLOAD | NESTED | FIELD | CONSTR | METHOD |
DETAIL: FIELD | CONSTR | METHOD | ||||||||
JAVADOC