gnu.inet.nntp

Class NNTPConnection

java.lang.Object

gnu.inet.nntp.NNTPConnection

Implemented Interfaces:: NNTPConstants

public class NNTPConnection

extends Object

implements NNTPConstants

An NNTP client. This object is used to establish and manage a connection to an NNTP server.

Field Summary
`static int`	`DEFAULT_PORT` The default NNTP port.
`protected boolean`	`canPost` Whether the host permits posting of articles.
`protected boolean`	`debug` Whether to log protocol-level information to stderr.
`protected String`	`hostname` The hostname of the host we are connected to.
`protected LineInputStream`	`in` The socket input stream.
`protected CRLFOutputStream`	`out` The socket output stream.
`protected PendingData`	`pendingData` Pending data, if any.
`protected int`	`port` The port on the host we are connected to.
`protected Socket`	`socket` The socket used for network communication.
`protected String`	`welcome` The greeting issued by the host when we connected.

ARTICLE, ARTICLE_FOLLOWS, ARTICLE_NOT_WANTED, ARTICLE_NOT_WANTED_VIA_TAKETHIS, ARTICLE_POSTED, ARTICLE_REJECTED, ARTICLE_RETRIEVED, ARTICLE_TRANSFERRED, ARTICLE_TRANSFERRED_OK, ARTICLE_TRANSFER_FAILED, 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, DATE, DATE_OK, GROUP, GROUP_SELECTED, HEAD, HEAD_FOLLOWS, HELP, HELP_TEXT, IHAVE, INTERNAL_ERROR, LAST, LIST, LISTGROUP, LIST_ACTIVE, LIST_ACTIVE_TIMES, LIST_DISTRIBUTIONS, LIST_DISTRIB_PATS, LIST_FOLLOWS, LIST_NEWSGROUPS, LIST_OVERVIEW_FMT, LIST_SUBSCRIPTIONS, 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_AUTHINFOPASS, SEND_AUTHINFO_SIMPLE, SEND_TRANSFER_ARTICLE, SERVICE_DISCONTINUED, SLAVE, SLAVE_ACKNOWLEDGED, STAT, STREAMING_OK, SYNTAX_ERROR, TAKETHIS, TRANSFER_FAILED, TRANSFER_PERMISSION_DENIED, TRY_AGAIN_LATER, XGTITLE, XGTITLE_LIST_FOLLOWS, XHDR, XINDEX, XOVER, XPAT, XPATH, XREPLIC, XROVER

Constructor Summary
`NNTPConnection(String hostname)` Creates a new connection object.
`NNTPConnection(String hostname, int port)` Creates a new connection object.
`NNTPConnection(String hostname, int port, int connectionTimeout, int timeout, boolean debug)` Creates a new connection object.

Method Summary
`ArticleResponse`	`article(int articleNumber)` Send an article retrieval request to the server.
`ArticleResponse`	`article(String messageId)` Send an article retrieval request to the server.
`protected ArticleResponse`	`articleImpl(String command, String messageId)` Performs an ARTICLE, BODY, HEAD, or STAT command.
`boolean`	`authinfo(String username, String password)` Basic authentication strategy.
`boolean`	`authinfoGeneric(String mechanism, String username, String password)` Authenticates the connection using the specified SASL mechanism, username and password.
`boolean`	`authinfoSimple(String username, String password)` Implementation of NNTP simple authentication.
`ArticleResponse`	`body(int articleNumber)` Send an article body retrieval request to the server.
`ArticleResponse`	`body(String messageId)` Send an article body retrieval request to the server.
`boolean`	`check(String messageId)`
`Date`	`date()` Returns the date on the server.
`String`	`getWelcome()` Return the welcome message sent by the server in reply to the initial connection.
`GroupResponse`	`group(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(String messageId)` Send an article head retrieval request to the server.
`LineIterator`	`help()` Requests a help listing.
`PostStream`	`ihave(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(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(String group)` Returns a listing of all the article numbers in the specified newsgroup.
`PairIterator`	`listNewsgroups(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(Date since, String[] distributions)` Returns an iterator over the list of new groups on the server since the specified date.
`LineIterator`	`newNews(String newsgroup, Date since, 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(String line)` Parse a response object from a response line sent by the server.
`protected StatusResponse`	`parseResponse(String line, boolean isListGroup)` Parse a response object from a response line sent by the server.
`OutputStream`	`post()` Post an article.
`void`	`quit()` Close the connection.
`protected String`	`read()` Read a single line from the server.
`protected void`	`send(String line)` Send a single line to the server.
`void`	`slave()` Indicates to the server that this is a slave connection.
`ArticleResponse`	`stat(int articleNumber)` Send an article status request to the server.
`ArticleResponse`	`stat(String messageId)` Send an article status request to the server.
`OutputStream`	`takethis(String messageId)` Implements the out-of-order takethis command.
`PairIterator`	`xgtitle(String wildmat)` Returns an iterator over the list of newsgroup descriptions.
`HeaderIterator`	`xhdr(String header, String range)`
`OverviewIterator`	`xover(Range range)`

DEFAULT_PORT

public static final int DEFAULT_PORT

The default NNTP port.
Field Value:
119

canPost

protected boolean canPost

Whether the host permits posting of articles.

debug

protected boolean debug

Whether to log protocol-level information to stderr.

hostname

protected String hostname

The hostname of the host we are connected to.

in

protected LineInputStream in

The socket input stream.

out

protected CRLFOutputStream out

The socket output stream.

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.
Parameters:
hostname - the hostname or IP address of the news server

NNTPConnection

public NNTPConnection(String hostname,
                      int port)
            throws IOException

Creates a new connection object.
Parameters:
hostname - the hostname or IP address of the news server
port - the port to connect to

NNTPConnection

public NNTPConnection(String hostname,
                      int port,
                      int connectionTimeout,
                      int timeout,
                      boolean debug)
            throws 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
debug - whether to use debugging

article

public ArticleResponse article(int articleNumber)
            throws 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

article

public ArticleResponse article(String messageId)
            throws 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

articleImpl

protected ArticleResponse articleImpl(String command,
                                      String messageId)
            throws 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

authinfo

public boolean authinfo(String username,
                        String password)
            throws IOException

Basic authentication strategy.
Parameters:
username - the user to authenticate
password - the(cleartext) password
Returns:
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.
Parameters:
mechanism - a SASL authentication mechanism, e.g. LOGIN, PLAIN, CRAM-MD5, GSSAPI
username - the authentication principal
password - 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(int articleNumber)
            throws 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

body

public ArticleResponse body(String messageId)
            throws 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

check

public boolean check(String messageId)
            throws IOException

date

public Date date()
            throws IOException

Returns the date on the server.

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.
Parameters:
name - the name of the group to select

head

public ArticleResponse head(int articleNumber)
            throws 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

head

public ArticleResponse head(String messageId)
            throws 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

help

public LineIterator help()
            throws IOException

Requests a help listing.
Returns:
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.
Parameters:
messageId - the article message-id
Returns:
a PostStream if the server wants the specified article, null otherwise

last

public ArticleResponse last()
            throws IOException

Sends a previous article positioning command to the server.
Returns:
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.
Parameters:
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.
Parameters:
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.
Parameters:
wildmat - if non-null, limits the groups in the iterator to the specified pattern
Returns:
an iterator over group name/description pairs
See Also:
xgtitle(String)

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.
See Also:
xover(Range)

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.
Returns:
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.
Returns:
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.
Parameters:
since - the date from which to list new groups
distributions - 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.
Parameters:
newsgroup - the newsgroup wildmat
since - the date from which to list new articles
distributions - if non-null, a list of distributions to match

public ArticleResponse next()
            throws IOException

Sends a next article positioning command to the server.
Returns:
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.
Parameters:
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.
See Also:
NNTPConnection

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.
Returns:
a line of text

send

protected void send(String line)
            throws IOException

Send a single line to the server.
Parameters:
line - the line to send

slave

public void slave()
            throws IOException

Indicates to the server that this is a slave connection.

stat

public ArticleResponse stat(int articleNumber)
            throws 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

stat

public ArticleResponse stat(String messageId)
            throws 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

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.
See Also:
NNTPConnection

xgtitle

public PairIterator xgtitle(String wildmat)
            throws IOException

Returns an iterator over the list of newsgroup descriptions.
Parameters:
wildmat - if non-null, the newsgroups to match

xhdr

public HeaderIterator xhdr(String header,
                           String range)
            throws IOException

xover

public OverviewIterator xover(Range range)
            throws IOException

* NNTPConnection.java * Copyright (C) 2002 The Free Software Foundation * * This file is part of GNU inetlib, a library. * * GNU inetlib is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * GNU inetlib is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * * Linking this library statically or dynamically with other modules is * making a combined work based on this library. Thus, the terms and * conditions of the GNU General Public License cover the whole * combination. * * As a special exception, the copyright holders of this library give you * permission to link this library with independent modules to produce an * executable, regardless of the license terms of these independent * modules, and to copy and distribute the resulting executable under * terms of your choice, provided that you also meet, for each linked * independent module, the terms and conditions of the license of that * module. An independent module is a module which is not derived from * or based on this library. If you modify this library, you may extend * this exception to your version of the library, but you are not * obliged to do so. If you do not wish to do so, delete this * exception statement from your version.

Overview Package Class Use Source Tree Index Deprecated About
Prev Class \| Next Class	Frames \| No Frames
Summary: Nested \| Field \| Method \| Constr	Detail: Nested \| Field \| Method \| Constr

gnu.inet.nntp

Class NNTPConnection

Field Summary

Fields inherited from interface gnu.inet.nntp.NNTPConstants

Constructor Summary

Method Summary

Field Details

DEFAULT_PORT

canPost

debug

hostname

in

out

pendingData

port

socket

welcome

Constructor Details

NNTPConnection

NNTPConnection

NNTPConnection

Method Details

article

article

articleImpl

authinfo

authinfoGeneric

authinfoSimple

body

body

check

date

getWelcome

group

head

head

help

ihave

last

list

listActive

listActiveTimes

listGroup

listNewsgroups

listOverviewFmt

listSubscriptions

modeReader

modeStream

newGroups

newNews

next

parseResponse

parseResponse

post

quit

read

send

slave

stat

stat

takethis

xgtitle

xhdr

xover