All Implemented Interfaces:

NNTPConstants

public class NNTPConnection
extends java.lang.Object
implements NNTPConstants 

• Field Summary

  Fields

  Modifier and Type	Field and Description
  static int	DEFAULT_PORT The default NNTP port.
  static int	DEFAULT_SSL_PORT The default NNTPS port
  static java.util.logging.Level	NNTP_TRACE The network trace level.

  • Fields inherited from interface gnu.inet.nntp.NNTPConstants

    ARTICLE, ARTICLE_FOLLOWS, ARTICLE_NOT_WANTED, ARTICLE_NOT_WANTED_VIA_TAKETHIS, ARTICLE_POSTED, ARTICLE_REJECTED, ARTICLE_RETRIEVED, ARTICLE_TRANSFER_FAILED, ARTICLE_TRANSFERRED, ARTICLE_TRANSFERRED_OK, AUTHINFO_GENERIC, AUTHINFO_OK, AUTHINFO_PASS, AUTHINFO_REJECTED, AUTHINFO_SIMPLE, AUTHINFO_SIMPLE_DENIED, AUTHINFO_SIMPLE_OK, AUTHINFO_SIMPLE_REQUIRED, AUTHINFO_USER, BODY, BODY_FOLLOWS, CHECK, CLOSING_CONNECTION, COMMAND_NOT_RECOGNIZED, CONTINUE_TLS_NEGOTIATION, DATE, DATE_OK, ENCRYPTION_OR_AUTH_REQUIRED, GROUP, GROUP_SELECTED, HEAD, HEAD_FOLLOWS, HELP, HELP_TEXT, IHAVE, INTERNAL_ERROR, LAST, LIST, LIST_ACTIVE, LIST_ACTIVE_TIMES, LIST_DISTRIB_PATS, LIST_DISTRIBUTIONS, LIST_FOLLOWS, LIST_NEWSGROUPS, LIST_OVERVIEW_FMT, LIST_SUBSCRIPTIONS, LISTGROUP, MODE_READER, MODE_STREAM, NEWGROUPS, NEWGROUPS_LIST_FOLLOWS, NEWNEWS, NEWNEWS_LIST_FOLLOWS, NEXT, NO_ARTICLE_SELECTED, NO_GROUP_SELECTED, NO_NEXT_ARTICLE, NO_POSTING_ALLOWED, NO_PREVIOUS_ARTICLE, NO_SUCH_ARTICLE, NO_SUCH_ARTICLE_NUMBER, NO_SUCH_GROUP, OVERVIEW_FOLLOWS, PERMISSION_DENIED, POST, POSTING_ALLOWED, POSTING_FAILED, POSTING_NOT_ALLOWED, QUIT, SEND_ARTICLE, SEND_ARTICLE_VIA_TAKETHIS, SEND_AUTHINFO_SIMPLE, SEND_AUTHINFOPASS, SEND_TRANSFER_ARTICLE, SERVICE_DISCONTINUED, SLAVE, SLAVE_ACKNOWLEDGED, STARTTLS, STAT, STREAMING_OK, SYNTAX_ERROR, TAKETHIS, TLS_INIT_ERROR, TRANSFER_FAILED, TRANSFER_PERMISSION_DENIED, TRY_AGAIN_LATER, XGTITLE, XGTITLE_LIST_FOLLOWS, XHDR, XINDEX, XOVER, XPAT, XPATH, XREPLIC, XROVER

• Constructor Summary

  Constructors

  Constructor and Description
  NNTPConnection (java.lang.String hostname) Creates a new connection object.
  NNTPConnection (java.lang.String hostname, int port) Creates a new connection object.
  NNTPConnection (java.lang.String hostname, int port, int connectionTimeout, int timeout) Creates a new connection object.
  NNTPConnection (java.lang.String hostname, int port, int connectionTimeout, int timeout, boolean secure, javax.net.ssl.TrustManager tm) Creates a new connection object.
  NNTPConnection (java.lang.String host, int port, javax.net.ssl.TrustManager tm) Creates a new secure connection using the specified trust manager.

• Method Summary

  Methods

  Modifier and Type	Method and Description
  ArticleResponse	article (int articleNumber) Send an article retrieval request to the server.
  ArticleResponse	article (java.lang.String messageId) Send an article retrieval request to the server.
  protected ArticleResponse	articleImpl (java.lang.String command, java.lang.String messageId) Performs an ARTICLE, BODY, HEAD, or STAT command.
  boolean	authinfo (java.lang.String username, java.lang.String password) Basic authentication strategy.
  boolean	authinfoGeneric (java.lang.String mechanism, java.lang.String username, java.lang.String password) Authenticates the connection using the specified SASL mechanism, username and password.
  boolean	authinfoSimple (java.lang.String username, java.lang.String password) Implementation of NNTP simple authentication.
  ArticleResponse	body (int articleNumber) Send an article body retrieval request to the server.
  ArticleResponse	body (java.lang.String messageId) Send an article body retrieval request to the server.
  boolean	check (java.lang.String messageId)
  java.util.Date	date () Returns the date on the server.
  java.util.logging.Logger	getLogger () Returns the logger used by this connection for debug output.
  protected javax.net.ssl.SSLSocketFactory	getSSLSocketFactory (javax.net.ssl.TrustManager tm) Returns a configured SSLSocketFactory to use in creating new SSL sockets.
  java.lang.String	getWelcome () Return the welcome message sent by the server in reply to the initial connection.
  GroupResponse	group (java.lang.String name) Send a group selection command to the server.
  ArticleResponse	head (int articleNumber) Send an article head retrieval request to the server.
  ArticleResponse	head (java.lang.String messageId) Send an article head retrieval request to the server.
  LineIterator	help () Requests a help listing.
  PostStream	ihave (java.lang.String messageId) Sends an ihave command indicating that the client has an article with the specified message-id.
  ArticleResponse	last () Sends a previous article positioning command to the server.
  GroupIterator	list () Send a group listing command to the server.
  GroupIterator	listActive (java.lang.String wildmat) Returns an iterator over the groups specified according to the wildmat pattern.
  ActiveTimesIterator	listActiveTimes () Returns an iterator over the active.times file.
  ArticleNumberIterator	listGroup (java.lang.String group) Returns a listing of all the article numbers in the specified newsgroup.
  PairIterator	listNewsgroups (java.lang.String wildmat) Returns an iterator over the group descriptions for the given groups.
  LineIterator	listOverviewFmt () Returns an iterator over the order in which headers are stored in the overview database.
  GroupIterator	listSubscriptions () Returns a list of newsgroups suitable for new users of the server.
  boolean	modeReader () Indicates to the server that this is a user-agent.
  boolean	modeStream () Attempt to initialise the connection in streaming mode.
  LineIterator	newGroups (java.util.Date since, java.lang.String[] distributions) Returns an iterator over the list of new groups on the server since the specified date.
  LineIterator	newNews (java.lang.String newsgroup, java.util.Date since, java.lang.String[] distributions) Returns an iterator over the list of message-ids posted or received to the specified newsgroup(s) since the specified date.
  ArticleResponse	next () Sends a next article positioning command to the server.
  protected StatusResponse	parseResponse (java.lang.String line) Parse a response object from a response line sent by the server.
  protected StatusResponse	parseResponse (java.lang.String line, boolean isListGroup) Parse a response object from a response line sent by the server.
  java.io.OutputStream	post () Post an article.
  void	quit () Close the connection.
  protected java.lang.String	read () Read a single line from the server.
  protected void	send (java.lang.String line) Send a single line to the server.
  void	slave () Indicates to the server that this is a slave connection.
  boolean	starttls () Negotiate TLS over the current connection.
  boolean	starttls (javax.net.ssl.TrustManager tm) This command performs a TLS negotiation.
  ArticleResponse	stat (int articleNumber) Send an article status request to the server.
  ArticleResponse	stat (java.lang.String messageId) Send an article status request to the server.
  java.io.OutputStream	takethis (java.lang.String messageId) Implements the out-of-order takethis command.
  PairIterator	xgtitle (java.lang.String wildmat) Returns an iterator over the list of newsgroup descriptions.
  HeaderIterator	xhdr (java.lang.String header, java.lang.String range)
  OverviewIterator	xover (Range range)

  • Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

• Field Detail

  • NNTP_TRACE

    public static final java.util.logging.Level NNTP_TRACE

    The network trace level.

  • DEFAULT_PORT

    public static final int DEFAULT_PORT

    The default NNTP port.

    See Also:

    Constant Field Values

  • DEFAULT_SSL_PORT

    public static final int DEFAULT_SSL_PORT

    The default NNTPS port

    See Also:

    Constant Field Values

• Constructor Detail

  • NNTPConnection

    public NNTPConnection(java.lang.String hostname)
     throws java.io.IOException

    Creates a new connection object.

    Parameters:

    hostname - the hostname or IP address of the news server

    Throws:

    java.io.IOException

  • NNTPConnection

    public NNTPConnection(java.lang.String hostname,
     int port)
     throws java.io.IOException

    Creates a new connection object.

    Parameters:

    hostname - the hostname or IP address of the news server

    port - the port to connect to

    Throws:

    java.io.IOException

  • NNTPConnection

    public NNTPConnection(java.lang.String host,
     int port,
     javax.net.ssl.TrustManager tm)
     throws java.io.IOException

    Creates a new secure connection using the specified trust manager.

    Parameters:

    host - the name of the host to connect to

    port - the port to connect to, or -1 for the default

    tm - a trust manager used to check SSL certificates, or null to use the default

    Throws:

    java.io.IOException

  • NNTPConnection

    public NNTPConnection(java.lang.String hostname,
     int port,
     int connectionTimeout,
     int timeout)
     throws java.io.IOException

    Creates a new connection object.

    Parameters:

    hostname - the hostname or IP address of the news server

    port - the port to connect to

    connectionTimeout - the socket connection timeout

    timeout - the read timeout on the socket

    Throws:

    java.io.IOException

  • NNTPConnection

    public NNTPConnection(java.lang.String hostname,
     int port,
     int connectionTimeout,
     int timeout,
     boolean secure,
     javax.net.ssl.TrustManager tm)

    Creates a new connection object.

    Parameters:

    hostname - the hostname or IP address of the news server

    port - the port to connect to

    connectionTimeout - the socket connection timeout

    timeout - the read timeout on the socket

• Method Detail

  • getSSLSocketFactory

    protected javax.net.ssl.SSLSocketFactory getSSLSocketFactory(javax.net.ssl.TrustManager tm)
     throws java.security.GeneralSecurityException

    Returns a configured SSLSocketFactory to use in creating new SSL sockets.

    Parameters:

    tm - an optional trust manager to use

    Throws:

    java.security.GeneralSecurityException

  • getLogger

    public java.util.logging.Logger getLogger()

    Returns the logger used by this connection for debug output.

  • starttls

    public boolean starttls()
     throws java.io.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.

    Throws:

    java.io.IOException

  • starttls

    public boolean starttls(javax.net.ssl.TrustManager tm)
     throws java.io.IOException

    This command performs a TLS negotiation. See RFC 4642 for details.

    Parameters:

    tm - the custom trust manager to use

    Returns:

    true if successful, false otherwise

    Throws:

    java.io.IOException

  • getWelcome

    public java.lang.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.

  • article

    public ArticleResponse article(int articleNumber)
     throws java.io.IOException

    Send an article retrieval request to the server.

    Parameters:

    articleNumber - the article number of the article to retrieve

    Returns:

    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

    Throws:

    java.io.IOException

  • article

    public ArticleResponse article(java.lang.String messageId)
     throws java.io.IOException

    Send an article retrieval request to the server.

    Parameters:

    messageId - the message-id of the article to retrieve

    Returns:

    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

    Throws:

    java.io.IOException

  • head

    public ArticleResponse head(int articleNumber)
     throws java.io.IOException

    Send an article head retrieval request to the server.

    Parameters:

    articleNumber - the article number of the article to head

    Returns:

    an article response consisting of the article number and message-id, and an iterator over the lines of the article header

    Throws:

    java.io.IOException

  • head

    public ArticleResponse head(java.lang.String messageId)
     throws java.io.IOException

    Send an article head retrieval request to the server.

    Parameters:

    messageId - the message-id of the article to head

    Returns:

    an article response consisting of the article number and message-id, and an iterator over the lines of the article header

    Throws:

    java.io.IOException

  • body

    public ArticleResponse body(int articleNumber)
     throws java.io.IOException

    Send an article body retrieval request to the server.

    Parameters:

    articleNumber - the article number of the article to body

    Returns:

    an article response consisting of the article number and message-id, and an iterator over the lines of the article body

    Throws:

    java.io.IOException

  • body

    public ArticleResponse body(java.lang.String messageId)
     throws java.io.IOException

    Send an article body retrieval request to the server.

    Parameters:

    messageId - the message-id of the article to body

    Returns:

    an article response consisting of the article number and message-id, and an iterator over the lines of the article body

    Throws:

    java.io.IOException

  • stat

    public ArticleResponse stat(int articleNumber)
     throws java.io.IOException

    Send an article status request to the server.

    Parameters:

    articleNumber - the article number of the article to stat

    Returns:

    an article response consisting of the article number and message-id

    Throws:

    java.io.IOException

  • stat

    public ArticleResponse stat(java.lang.String messageId)
     throws java.io.IOException

    Send an article status request to the server.

    Parameters:

    messageId - the message-id of the article to stat

    Returns:

    an article response consisting of the article number and message-id

    Throws:

    java.io.IOException

  • articleImpl

    protected ArticleResponse articleImpl(java.lang.String command,
     java.lang.String messageId)
     throws java.io.IOException

    Performs an ARTICLE, BODY, HEAD, or STAT command.

    Parameters:

    command - one of the above commands

    messageId - the article-number or message-id in string form

    Throws:

    java.io.IOException

  • group

    public GroupResponse group(java.lang.String name)
     throws java.io.IOException

    Send a group selection command to the server. Returns a group status response.

    Parameters:

    name - the name of the group to select

    Throws:

    java.io.IOException

  • help

    public LineIterator help()
     throws java.io.IOException

    Requests a help listing.

    Returns:

    an iterator over a collection of help lines.

    Throws:

    java.io.IOException

  • ihave

    public PostStream ihave(java.lang.String messageId)
     throws java.io.IOException

    Sends an ihave command indicating that the client has an article with the specified message-id.

    Parameters:

    messageId - the article message-id

    Returns:

    a PostStream if the server wants the specified article, null otherwise

    Throws:

    java.io.IOException

  • last

    public ArticleResponse last()
     throws java.io.IOException

    Sends a previous article positioning command to the server.

    Returns:

    the article number/message-id pair associated with the new article

    Throws:

    java.io.IOException

  • list

    public GroupIterator list()
     throws java.io.IOException

    Send a group listing command to the server. Returns a GroupIterator. This must be read fully before other commands are issued.

    Throws:

    java.io.IOException

  • newGroups

    public LineIterator newGroups(java.util.Date since,
     java.lang.String[] distributions)
     throws java.io.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.

    Parameters:

    since - the date from which to list new groups

    distributions - if non-null, an array of distributions to match

    Throws:

    java.io.IOException

  • newNews

    public LineIterator newNews(java.lang.String newsgroup,
     java.util.Date since,
     java.lang.String[] distributions)
     throws java.io.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.

    Parameters:

    newsgroup - the newsgroup wildmat

    since - the date from which to list new articles

    distributions - if non-null, a list of distributions to match

    Throws:

    java.io.IOException

  • next

    public ArticleResponse next()
     throws java.io.IOException

    Sends a next article positioning command to the server.

    Returns:

    the article number/message-id pair associated with the new article

    Throws:

    java.io.IOException

  • post

    public java.io.OutputStream post()
     throws java.io.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.

    Throws:

    java.io.IOException

    See Also:

    postComplete()

  • quit

    public void quit()
     throws java.io.IOException

    Close the connection. After calling this method, no further calls on this object are valid.

    Throws:

    java.io.IOException

  • slave

    public void slave()
     throws java.io.IOException

    Indicates to the server that this is a slave connection.

    Throws:

    java.io.IOException

  • check

    public boolean check(java.lang.String messageId)
     throws java.io.IOException

    Throws:

    java.io.IOException

  • modeStream

    public boolean modeStream()
     throws java.io.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.

    Returns:

    true if the server supports streaming mode

    Throws:

    java.io.IOException

  • takethis

    public java.io.OutputStream takethis(java.lang.String messageId)
     throws java.io.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.

    Throws:

    java.io.IOException

    See Also:

    takethisComplete()

  • listActive

    public GroupIterator listActive(java.lang.String wildmat)
     throws java.io.IOException

    Returns an iterator over the groups specified according to the wildmat pattern. The iterator must be read fully before other commands are issued.

    Parameters:

    wildmat - the wildmat pattern. If null, returns all groups. If no groups are matched, returns an empty iterator.

    Throws:

    java.io.IOException

  • listActiveTimes

    public ActiveTimesIterator listActiveTimes()
     throws java.io.IOException

    Returns an iterator over the active.times file. Each ActiveTime object returned provides details of who created the newsgroup and when.

    Throws:

    java.io.IOException

  • listNewsgroups

    public PairIterator listNewsgroups(java.lang.String wildmat)
     throws java.io.IOException

    Returns an iterator over the group descriptions for the given groups.

    Parameters:

    wildmat - if non-null, limits the groups in the iterator to the specified pattern

    Returns:

    an iterator over group name/description pairs

    Throws:

    java.io.IOException

    See Also:

    xgtitle(java.lang.String)

  • listOverviewFmt

    public LineIterator listOverviewFmt()
     throws java.io.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.

    Throws:

    java.io.IOException

    See Also:

    xover(gnu.inet.nntp.Range)

  • listSubscriptions

    public GroupIterator listSubscriptions()
     throws java.io.IOException

    Returns a list of newsgroups suitable for new users of the server.

    Throws:

    java.io.IOException

  • listGroup

    public ArticleNumberIterator listGroup(java.lang.String group)
     throws java.io.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.

    Parameters:

    group - the name of the group to list articles for

    Throws:

    java.io.IOException

  • modeReader

    public boolean modeReader()
     throws java.io.IOException

    Indicates to the server that this is a user-agent.

    Returns:

    true if posting is allowed, false otherwise.

    Throws:

    java.io.IOException

  • xgtitle

    public PairIterator xgtitle(java.lang.String wildmat)
     throws java.io.IOException

    Returns an iterator over the list of newsgroup descriptions.

    Parameters:

    wildmat - if non-null, the newsgroups to match

    Throws:

    java.io.IOException

  • xhdr

    public HeaderIterator xhdr(java.lang.String header,
     java.lang.String range)
     throws java.io.IOException

    Throws:

    java.io.IOException

  • xover

    public OverviewIterator xover(Range range)
     throws java.io.IOException

    Throws:

    java.io.IOException

  • authinfo

    public boolean authinfo(java.lang.String username,
     java.lang.String password)
     throws java.io.IOException

    Basic authentication strategy.

    Parameters:

    username - the user to authenticate

    password - the(cleartext) password

    Returns:

    true on success, false on failure

    Throws:

    java.io.IOException

  • authinfoSimple

    public boolean authinfoSimple(java.lang.String username,
     java.lang.String password)
     throws java.io.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.

    Throws:

    java.io.IOException

  • authinfoGeneric

    public boolean authinfoGeneric(java.lang.String mechanism,
     java.lang.String username,
     java.lang.String password)
     throws java.io.IOException

    Authenticates the connection using the specified SASL mechanism, username and password.

    Parameters:

    mechanism - a SASL authentication mechanism, e.g. LOGIN, PLAIN, CRAM-MD5, GSSAPI

    username - the authentication principal

    password - the authentication credentials

    Throws:

    java.io.IOException

  • date

    public java.util.Date date()
     throws java.io.IOException

    Returns the date on the server.

    Throws:

    java.io.IOException

  • parseResponse

    protected StatusResponse parseResponse(java.lang.String line)
     throws java.net.ProtocolException

    Parse a response object from a response line sent by the server.

    Throws:

    java.net.ProtocolException

  • parseResponse

    protected StatusResponse parseResponse(java.lang.String line,
     boolean isListGroup)
     throws java.net.ProtocolException

    Parse a response object from a response line sent by the server.

    Parameters:

    isListGroup - whether we are invoking the LISTGROUP command

    Throws:

    java.net.ProtocolException

  • send

    protected void send(java.lang.String line)
     throws java.io.IOException

    Send a single line to the server.

    Parameters:

    line - the line to send

    Throws:

    java.io.IOException

  • read

    protected java.lang.String read()
     throws java.io.IOException

    Read a single line from the server.

    Returns:

    a line of text

    Throws:

    java.io.IOException