An NNTP client.
This object is used to establish and manage a connection to an NNTP
server.
DEFAULT_PORT
public static final int DEFAULT_PORT
The default NNTP port.
DEFAULT_SSL_PORT
public static final int DEFAULT_SSL_PORT
The default NNTPS port
NNTP_TRACE
public static final Level NNTP_TRACE
The network trace level.
canPost
protected boolean canPost
Whether the host permits posting of articles.
hostname
protected String hostname
The hostname of the host we are connected to.
logger
public final Logger logger
The logger used for NNTP protocol traces.
pendingData
protected PendingData pendingData
Pending data, if any.
port
protected int port
The port on the host we are connected to.
socket
protected Socket socket
The socket used for network communication.
welcome
protected String welcome
The greeting issued by the host when we connected.
NNTPConnection
public NNTPConnection(String hostname)
throws IOException
Creates a new connection object.
hostname
- the hostname or IP address of the news server
NNTPConnection
public NNTPConnection(String hostname,
int port)
throws IOException
Creates a new connection object.
hostname
- the hostname or IP address of the news serverport
- the port to connect to
NNTPConnection
public NNTPConnection(String host,
int port,
TrustManager tm)
throws IOException
Creates a new secure connection using the specified trust manager.
host
- the name of the host to connect toport
- the port to connect to, or -1 for the defaulttm
- a trust manager used to check SSL certificates, or null to
use the default
NNTPConnection
public NNTPConnection(String hostname,
int port,
int connectionTimeout,
int timeout)
throws IOException
Creates a new connection object.
hostname
- the hostname or IP address of the news serverport
- the port to connect toconnectionTimeout
- the socket connection timeouttimeout
- the read timeout on the socket
NNTPConnection
public NNTPConnection(String hostname,
int port,
int connectionTimeout,
int timeout,
boolean secure,
TrustManager tm,
boolean init)
throws IOException
Creates a new connection object.
hostname
- the hostname or IP address of the news serverport
- the port to connect toconnectionTimeout
- the socket connection timeouttimeout
- the read timeout on the socketinit
- initialise the connection
article
public ArticleResponse article(String messageId)
throws IOException
Send an article retrieval request to the server.
messageId
- the message-id of the article to retrieve
- an article response consisting of the article number and
message-id, and an iterator over the lines of the article header and
body, separated by an empty line
article
public ArticleResponse article(int articleNumber)
throws IOException
Send an article retrieval request to the server.
articleNumber
- the article number of the article to retrieve
- an article response consisting of the article number and
message-id, and an iterator over the lines of the article header and
body, separated by an empty line
articleImpl
protected ArticleResponse articleImpl(String command,
String messageId)
throws IOException
Performs an ARTICLE, BODY, HEAD, or STAT command.
command
- one of the above commandsmessageId
- the article-number or message-id in string form
authinfo
public boolean authinfo(String username,
String password)
throws IOException
Basic authentication strategy.
username
- the user to authenticatepassword
- the(cleartext) password
- true on success, false on failure
authinfoGeneric
public boolean authinfoGeneric(String mechanism,
String username,
String password)
throws IOException
Authenticates the connection using the specified SASL mechanism,
username and password.
mechanism
- a SASL authentication mechanism, e.g. LOGIN, PLAIN,
CRAM-MD5, GSSAPIusername
- the authentication principalpassword
- the authentication credentials
authinfoSimple
public boolean authinfoSimple(String username,
String password)
throws IOException
Implementation of NNTP simple authentication.
Note that use of this authentication strategy is highly deprecated,
only use on servers that won't accept any other form of authentication.
body
public ArticleResponse body(String messageId)
throws IOException
Send an article body retrieval request to the server.
messageId
- the message-id of the article to body
- an article response consisting of the article number and
message-id, and an iterator over the lines of the article body
body
public ArticleResponse body(int articleNumber)
throws IOException
Send an article body retrieval request to the server.
articleNumber
- the article number of the article to body
- an article response consisting of the article number and
message-id, and an iterator over the lines of the article body
check
public boolean check(String messageId)
throws IOException
date
public Date date()
throws IOException
Returns the date on the server.
getSSLSocketFactory
protected SSLSocketFactory getSSLSocketFactory(TrustManager tm)
throws GeneralSecurityException
Returns a configured SSLSocketFactory to use in creating new SSL
sockets.
tm
- an optional trust manager to use
getWelcome
public String getWelcome()
Return the welcome message sent by the server in reply to the initial
connection.
This message sometimes contains disclaimers or help information that
may be relevant to the user.
group
public GroupResponse group(String name)
throws IOException
Send a group selection command to the server.
Returns a group status response.
name
- the name of the group to select
head
public ArticleResponse head(String messageId)
throws IOException
Send an article head retrieval request to the server.
messageId
- the message-id of the article to head
- an article response consisting of the article number and
message-id, and an iterator over the lines of the article header
head
public ArticleResponse head(int articleNumber)
throws IOException
Send an article head retrieval request to the server.
articleNumber
- the article number of the article to head
- an article response consisting of the article number and
message-id, and an iterator over the lines of the article header
help
public LineIterator help()
throws IOException
Requests a help listing.
- an iterator over a collection of help lines.
ihave
public PostStream ihave(String messageId)
throws IOException
Sends an ihave command indicating that the client has an article with
the specified message-id.
messageId
- the article message-id
- a PostStream if the server wants the specified article, null
otherwise
init
public void init()
throws IOException
Initialises the connection.
Unless the init parameter was provided with the value false,
do not call this method. Otherwise call it only once after e.g.
configuring logging.
last
public ArticleResponse last()
throws IOException
Sends a previous article positioning command to the server.
- the article number/message-id pair associated with the new
article
list
public GroupIterator list()
throws IOException
Send a group listing command to the server.
Returns a GroupIterator. This must be read fully before other commands
are issued.
listActive
public GroupIterator listActive(String wildmat)
throws IOException
Returns an iterator over the groups specified according to the wildmat
pattern. The iterator must be read fully before other commands are
issued.
wildmat
- the wildmat pattern. If null, returns all groups. If no
groups are matched, returns an empty iterator.
listActiveTimes
public ActiveTimesIterator listActiveTimes()
throws IOException
Returns an iterator over the active.times file.
Each ActiveTime object returned provides details of who created the
newsgroup and when.
listGroup
public ArticleNumberIterator listGroup(String group)
throws IOException
Returns a listing of all the article numbers in the specified
newsgroup. If the group
parameter is null, the currently
selected group is assumed.
group
- the name of the group to list articles for
listNewsgroups
public PairIterator listNewsgroups(String wildmat)
throws IOException
Returns an iterator over the group descriptions for the given groups.
wildmat
- if non-null, limits the groups in the iterator to the
specified pattern
- an iterator over group name/description pairs
listOverviewFmt
public LineIterator listOverviewFmt()
throws IOException
Returns an iterator over the order in which headers are stored in the
overview database.
Each line returned by the iterator contains one header field.
listSubscriptions
public GroupIterator listSubscriptions()
throws IOException
Returns a list of newsgroups suitable for new users of the server.
modeReader
public boolean modeReader()
throws IOException
Indicates to the server that this is a user-agent.
- true if posting is allowed, false otherwise.
modeStream
public boolean modeStream()
throws IOException
Attempt to initialise the connection in streaming mode.
This is generally used to bypass the lock step nature of NNTP in order
to perform a series of CHECK and TAKETHIS commands.
- true if the server supports streaming mode
newGroups
public LineIterator newGroups(Date since,
String[] distributions)
throws IOException
Returns an iterator over the list of new groups on the server since the
specified date.
NB this method suffers from a minor millenium bug.
since
- the date from which to list new groupsdistributions
- if non-null, an array of distributions to match
newNews
public LineIterator newNews(String newsgroup,
Date since,
String[] distributions)
throws IOException
Returns an iterator over the list of message-ids posted or received to
the specified newsgroup(s) since the specified date.
NB this method suffers from a minor millenium bug.
newsgroup
- the newsgroup wildmatsince
- the date from which to list new articlesdistributions
- if non-null, a list of distributions to match
next
public ArticleResponse next()
throws IOException
Sends a next article positioning command to the server.
- the article number/message-id pair associated with the new
article
parseResponse
protected StatusResponse parseResponse(String line)
throws ProtocolException
Parse a response object from a response line sent by the server.
parseResponse
protected StatusResponse parseResponse(String line,
boolean isListGroup)
throws ProtocolException
Parse a response object from a response line sent by the server.
isListGroup
- whether we are invoking the LISTGROUP command
post
public OutputStream post()
throws IOException
Post an article. This is a two-stage process.
If successful, returns an output stream to write the article to.
Clients should call write()
on the stream for all the
bytes of the article, and finally call close()
on the stream.
No other method should be called in between.
quit
public void quit()
throws IOException
Close the connection.
After calling this method, no further calls on this object are valid.
read
protected String read()
throws IOException
Read a single line from the server.
send
protected void send(String line)
throws IOException
Send a single line to the server.
slave
public void slave()
throws IOException
Indicates to the server that this is a slave connection.
starttls
public boolean starttls()
throws IOException
Negotiate TLS over the current connection.
This depends on many features, such as the JSSE classes being in the
classpath. Returns true if successful, false otherwise.
starttls
public boolean starttls(TrustManager tm)
throws IOException
This command performs a TLS negotiation.
See RFC 4642 for details.
tm
- the custom trust manager to use
- true if successful, false otherwise
stat
public ArticleResponse stat(String messageId)
throws IOException
Send an article status request to the server.
messageId
- the message-id of the article to stat
- an article response consisting of the article number and
message-id
stat
public ArticleResponse stat(int articleNumber)
throws IOException
Send an article status request to the server.
articleNumber
- the article number of the article to stat
- an article response consisting of the article number and
message-id
takethis
public OutputStream takethis(String messageId)
throws IOException
Implements the out-of-order takethis command.
The client uses the returned output stream to write all the bytes of the
article. When complete, it calls close()
on the
stream.
xgtitle
public PairIterator xgtitle(String wildmat)
throws IOException
Returns an iterator over the list of newsgroup descriptions.
wildmat
- if non-null, the newsgroups to match
xhdr
public HeaderIterator xhdr(String header,
String range)
throws IOException