org.rakeshv.net
Class NNTPSocket

java.lang.Object
  java.net.Socket
      org.rakeshv.net.NNTPSocket

public class NNTPSocket
extends java.net.Socket

This class is a sub-class of the Socket class, and implements most of the commands provided by the NNTP protocol. See RFC 977 for a description of the NNTP protocol and the supported features.

accessor and mutator methods have been made final to help the Java optimiser.

This class developed by Rakesh Vidyadharan and distributed under a BSD style licence. You are free to use, modify, redistribute this program. I am in no way responsible for any problems or bugs in the program.

Copyright © 2001 Rakesh Vidyadharan

Author:

Rakesh Vidyadharan 22^nd November 2001

Field Summary

static boolean	CHECK_COMMAND_RESPONSE Constant that indicates that the putNNTPCommand method should check the first line of the server response for a success message (message begins with a '2').
static java.lang.String	COMMAND_TERMINATOR The command termination character(s) to be sent to the NNTP server after each command.
private int	currentArticleID Store the current news article being accessed.
private java.io.PrintStream	errorStream The PrintStream object that is used to display errors.
private java.lang.String	newsGroupName Store the current newsgroup being accessed.
private int	nntpPort The NNTP port to connect to.
private java.lang.String	nntpServer The NNTP host to connect to.
static boolean	NO_CHECK_COMMAND_RESPONSE Constant that indicates that the putNNTPCommand method should not check the server response.
static boolean	NO_WILD_CARDS Constant that indicates that no wild cards are to be used while listing news groups using the getNewsGroups method.
private java.io.BufferedReader	reader The BufferedReader object that reads the responses from the NNTP server.
private java.lang.String	responseLine A String object that stores the current line of response read from the NNTP server.
static boolean	RETURN_GROUP_DETAILS Constant that indicates that the full response from the NNTP server should be returned by the getNewsGroups( boolean ) and getNewsGroups( String, boolean, boolean ) method's.
static boolean	RETURN_GROUP_NAMES Constant that indicates that only the news group names should be returned by the getNewsGroups( boolean ) and getNewsGroups( String, boolean, boolean ) method's.
static boolean	USE_WILD_CARDS Constant that indicates that user requested use of wild cards while listing news groups using the getNewsGroups method.
private java.io.BufferedWriter	writer The BufferedWriter object that sends the commands to the NNTP server.

Constructor Summary

private	NNTPSocket() Default Constructor.
	NNTPSocket(java.lang.String server) Open a Socket connection to the specified NNTP server on the default NNTP port 119.
	NNTPSocket(java.lang.String server, int port) Open a Socket connection to the specified NNTP server on the specified NNTP port.
	NNTPSocket(java.lang.String server, int port, java.io.PrintStream err) Open a Socket connection to the specified NNTP server on the specified port.

Method Summary

void	close() Close the connection to the NNTP server.
java.lang.String	getArticleBody() Get the body of the current article from the current newsgroup.
java.lang.String	getArticleBody(int articleID) Get the body of the specified article from the current newsgroup.
java.lang.String	getArticleBody(java.lang.String groupName, int articleID) Get the body of the specified article from the specified newsgroup.
java.lang.String	getArticleHead() Get the head of the current article from the current newsgroup.
java.lang.String	getArticleHead(int articleID) Get the head of the specified article from the current newsgroup.
java.lang.String	getArticleHead(java.lang.String groupName, int articleID) Get the head of the specified article from the specified newsgroup.
int	getCurrentArticleID() The article-id of the current article
int	getFirstArticleID() Get the article-id for the first article in the current newsgroup.
int	getFirstArticleID(java.lang.String groupName) Get the article-id for the first article in the newsgroup.
java.lang.String	getFullArticle() Get the head and body of the current article from the current newsgroup.
java.lang.String	getFullArticle(int articleID) Get the head and body of the specified article from the current newsgroup.
java.lang.String	getFullArticle(java.lang.String groupName, int articleID) Get the head and body of the specified article from the specified newsgroup.
int	getLastArticleID() Get the article-id for the last article in the current newsgroup.
int	getLastArticleID(java.lang.String groupName) Get the article-id for the last article in the newsgroup.
java.lang.String	getNewsGroupDetails(java.lang.String groupName) Get the details about the specified news group.
java.lang.String	getNewsGroupName() The current newsgroup that is being accessed.
java.lang.String[]	getNewsGroups(boolean returnType) Get a listing of all the news groups from the NNTP server.
java.lang.String[]	getNewsGroups(java.lang.String groupName, boolean wildCard, boolean returnType) Gets news groups matching the String passed in.
int	getNNTPPort() Get the NNTP port that we connect to.
java.lang.String	getNNTPServer() Get the DNS name of the NNTP server.
java.net.Socket	getNNTPSocket() Return a reference to this class.
boolean	moveToLastArticle() Move to the previous news article.
boolean	moveToNextArticle() Move to the next news article.
boolean	postMessage(java.lang.String message) Post a message to the current newsgroup.
boolean	postMessage(java.lang.String groupName, java.lang.String message) Post a message to the specified newsgroup.
private java.lang.String	processTextResponse() Process the response from the NNTP server.
boolean	putNNTPCommand(java.lang.String command, boolean checkResponse) Send the specified command to the NNTP server.
void	setErrorStream(java.io.PrintStream err) Set the PrintStream object that is used to display error messages.
boolean	setNewsGroup(java.lang.String groupName) Set the current news group.

Methods inherited from class java.net.Socket

bind, connect, connect, getChannel, getInetAddress, getInputStream, getKeepAlive, getLocalAddress, getLocalPort, getLocalSocketAddress, getOOBInline, getOutputStream, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoLinger, getSoTimeout, getTcpNoDelay, getTrafficClass, isBound, isClosed, isConnected, isInputShutdown, isOutputShutdown, sendUrgentData, setKeepAlive, setOOBInline, setPerformancePreferences, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSocketImplFactory, setSoLinger, setSoTimeout, setTcpNoDelay, setTrafficClass, shutdownInput, shutdownOutput, toString

Methods inherited from class java.lang.Object

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

Field Detail

CHECK_COMMAND_RESPONSE

public static final boolean CHECK_COMMAND_RESPONSE

Constant that indicates that the putNNTPCommand method should check the first line of the server response for a success message (message begins with a '2').

See Also:

Constant Field Values

NO_CHECK_COMMAND_RESPONSE

public static final boolean NO_CHECK_COMMAND_RESPONSE

Constant that indicates that the putNNTPCommand method should not check the server response.

See Also:

Constant Field Values

USE_WILD_CARDS

public static final boolean USE_WILD_CARDS

Constant that indicates that user requested use of wild cards while listing news groups using the getNewsGroups method.

See Also:

Constant Field Values

NO_WILD_CARDS

public static final boolean NO_WILD_CARDS

Constant that indicates that no wild cards are to be used while listing news groups using the getNewsGroups method.

See Also:

Constant Field Values

RETURN_GROUP_DETAILS

public static final boolean RETURN_GROUP_DETAILS

Constant that indicates that the full response from the NNTP server should be returned by the getNewsGroups( boolean ) and getNewsGroups( String, boolean, boolean ) method's.

See Also:

Constant Field Values

RETURN_GROUP_NAMES

public static final boolean RETURN_GROUP_NAMES

Constant that indicates that only the news group names should be returned by the getNewsGroups( boolean ) and getNewsGroups( String, boolean, boolean ) method's.

See Also:

Constant Field Values

COMMAND_TERMINATOR

public static final java.lang.String COMMAND_TERMINATOR

The command termination character(s) to be sent to the NNTP server after each command.

See Also:

Constant Field Values

nntpServer

private java.lang.String nntpServer

The NNTP host to connect to.

nntpPort

private int nntpPort

The NNTP port to connect to.

reader

private java.io.BufferedReader reader

The BufferedReader object that reads the responses from the NNTP server.

writer

private java.io.BufferedWriter writer

The BufferedWriter object that sends the commands to the NNTP server.

errorStream

private java.io.PrintStream errorStream

The PrintStream object that is used to display errors. By default, it is assigned to System.err. You can use setErrorStream to specify any other PrintStream object to write to.

responseLine

private java.lang.String responseLine

A String object that stores the current line of response read from the NNTP server.

newsGroupName

private java.lang.String newsGroupName

Store the current newsgroup being accessed.

currentArticleID

private int currentArticleID

Store the current news article being accessed.

Constructor Detail

NNTPSocket

private NNTPSocket()

Default Constructor. Does nothing. Class cannot be instantiated without specifying the NNTP server.

NNTPSocket

public NNTPSocket(java.lang.String server)
           throws java.net.UnknownHostException,
                  java.io.IOException

Open a Socket connection to the specified NNTP server on the default NNTP port 119.

This constructor invokes the NNTPSocket( String, int, PrintStream ) constructor with the default NNTP server port, and System.err as the error stream.

Throws:

java.net.UnknownHostException

java.io.IOException

NNTPSocket

public NNTPSocket(java.lang.String server,
                  int port)
           throws java.net.UnknownHostException,
                  java.io.IOException

Open a Socket connection to the specified NNTP server on the specified NNTP port.

This constructor invokes the NNTPSocket( String, int, PrintStream ) constructor with System.err as the error stream.

Throws:

java.net.UnknownHostException

java.io.IOException

NNTPSocket

public NNTPSocket(java.lang.String server,
                  int port,
                  java.io.PrintStream err)
           throws java.net.UnknownHostException,
                  java.io.IOException

Open a Socket connection to the specified NNTP server on the specified port. The class members writer and reader are bound to the OutputStream and the InputStream respectively of the Socket. The errorStream is bound to the specified PrintStream object.

Throws:

java.net.UnknownHostException

java.io.IOException

Method Detail

close

public void close()
           throws java.io.IOException

Close the connection to the NNTP server. This method over-rides the close() method in the parent Socket class, and closes the connection as defined in the NNTP protocol.

The NNTP server is sent the command quit, which closes the connection to the NNTP server.

Overrides:

close in class java.net.Socket

Throws:

java.io.IOException

getNewsGroups

public java.lang.String[] getNewsGroups(boolean returnType)

Get a listing of all the news groups from the NNTP server.

The output from sending the NNTP server a list command is parsed, and the names of the news groups are passed back as a String Array.

The NNTP server is sent the command list, which returns the list of groups one per line with space separated values in the following order:

1. group - The newsgroup name.
2. first - The first article number.
3. last - The last article number.
4. p - Indicates whether you can post to the newsgroup (y) or not (n).

Parameters:

returnType - - Indicates whether all details about the available newsgroups (RETURN_GROUP_DETAILS) or only the group names (RETURN_GROUP_NAMES).

Returns:

String[] - An array of String objects, each containing the name of the news group.

getNewsGroups

public java.lang.String[] getNewsGroups(java.lang.String groupName,
                                        boolean wildCard,
                                        boolean returnType)

Gets news groups matching the String passed in.

When invoked with USE_WILD_CARDS, this class sends the command list active *<*name>*, and the command list active <name> when invoked with NO_WILD_CARDS.

Parameters:

groupName - - The news group name to look for

wildCard - - Indicates whether to use wild cards when searching for groupName. Use USE_WILD_CARDS if you wish to use wild cards, and NO_WILD_CARDS if you do not.

returnType - - Indicates whether all details about the available newsgroups (RETURN_GROUP_DETAILS) or only the group names

Returns:

String[] - An array of String objects, each containing the name of the news group.

getNewsGroupDetails

public java.lang.String getNewsGroupDetails(java.lang.String groupName)

Get the details about the specified news group. The response from the NNTP server if returned if there were no errors, or a null reference if there were errors.

Send the NNTP command group <groupName> to select the desired newsgroup. The NNTP response is presented as space separated values (passed back in return value) in the following format:

211 n f l s group selected
or
411
where the response values indicate the following:

Response Text	Response Meaning
211	Specified newsgroup selected.
n	Estimated number of articles in newsgroup.
f	First article number.
l	Last article number.
s	Name of selected newsgroup.
411	Specified newsgroup does not exist.

Parameters:

groupName - - The newsgroup to access

Returns:

String - The response from the NNTP server. A null String will be returned if we got a 411 response.

getFirstArticleID

public int getFirstArticleID(java.lang.String groupName)

Get the article-id for the first article in the newsgroup.

Processes the results from the getNewsGroupDetails method, and returns the article-id.

Parameters:

groupName - - The newsgroup to access.

Returns:

int - The article-id of the first article in group. If a null results was obtained from getNewsGroupDetails, then a value of -1 is returned.

getFirstArticleID

public int getFirstArticleID()

Get the article-id for the first article in the current newsgroup.

Processes the results from the getNewsGroupDetails method, and returns the article-id.

Returns:

int - The article-id of the first article in group. If a null results was obtained from getNewsGroupDetails, then a value of -1 is returned.

getLastArticleID

public int getLastArticleID(java.lang.String groupName)

Get the article-id for the last article in the newsgroup.

Processes the results from the getNewsGroupDetails method, and returns the article-id.

Parameters:

groupName - - The newsgroup to access.

Returns:

int - The article-id of the last article in group. If a null results was obtained from getNewsGroupDetails, then a value of -1 is returned.

getLastArticleID

public int getLastArticleID()

Get the article-id for the last article in the current newsgroup.

Processes the results from the getNewsGroupDetails method, and returns the article-id.

Returns:

int - The article-id of the last article in group. If a null results was obtained from getNewsGroupDetails, then a value of -1 is returned.

getFullArticle

public java.lang.String getFullArticle(java.lang.String groupName,
                                       int articleID)

Get the head and body of the specified article from the specified newsgroup. The class variable newsGroupName is re-assigned with the new newsgroup name passed in.

The NNTP server is sent the commands group <groupName> and article <articleID> to retrieve the full contents of the specified article.

Parameters:

groupName - - The newsgroup from which to fetch the specified article.

articleID - - The article-id of the desired article.

Returns:

String - The full contents of the requested article.

getFullArticle

public java.lang.String getFullArticle()

Get the head and body of the current article from the current newsgroup. It is assumed that a group has been set. If currentArticleID is -1, then try to get the first article in the group.

The NNTP server is sent the command article <currentArticleID> to retrieve the full contents of the specified article.

Returns:

String - The full contents of the requested article.

getFullArticle

public java.lang.String getFullArticle(int articleID)

Get the head and body of the specified article from the current newsgroup.

The NNTP server is sent the command article <articleID> to retrieve the full contents of the specified article.

Parameters:

articleID - - The article-id of the desired article.

Returns:

String - The full contents of the requested article.

getArticleHead

public java.lang.String getArticleHead(java.lang.String groupName,
                                       int articleID)

Get the head of the specified article from the specified newsgroup. The class variable newsGroupName is re-assigned with the new newsgroup name passed in.

The NNTP server is sent the commands group <groupName> and head <articleID> to retrieve the head of the specified article.

Parameters:

groupName - - The newsgroup from which to fetch the specified article.

articleID - - The article-id of the desired article.

Returns:

String - The head of the requested article.

getArticleHead

public java.lang.String getArticleHead()

Get the head of the current article from the current newsgroup. It is assumed that a group has been set. If currentArticleID is -1, then try to get the first article in the group.

The NNTP server is sent the command head <currentArticleID> to retrieve the head of the current article.

Returns:

String - The head of the requested article.

getArticleHead

public java.lang.String getArticleHead(int articleID)

Get the head of the specified article from the current newsgroup.

The NNTP server is sent the command head <articleID> to retrieve the head of the specified article.

Parameters:

articleID - - The article-id of the desired article.

Returns:

String - The head of the requested article.

getArticleBody

public java.lang.String getArticleBody(java.lang.String groupName,
                                       int articleID)

Get the body of the specified article from the specified newsgroup. The class variable newsGroupName is re-assigned with the new newsgroup name passed in.

The NNTP server is sent the commands group <groupName> and body <articleID> to retrieve the body of the specified article.

Parameters:

groupName - - The newsgroup from which to fetch the specified article.

articleID - - The article-id of the desired article.

Returns:

String - The body of the requested article.

getArticleBody

public java.lang.String getArticleBody()

Get the body of the current article from the current newsgroup. It is assumed that a group has been set. If currentArticleID is -1, then try to get the first article in the group.

The NNTP server is sent the command body <currentArticleID> to retrieve the body of the specified article.

Returns:

String - The body of the requested article.

getArticleBody

public java.lang.String getArticleBody(int articleID)

Get the body of the specified article from the current newsgroup.

The NNTP server is sent the command body <articleID> to retrieve the body of the specified article.

Parameters:

articleID - - The article-id of the desired article.

Returns:

String - The body of the requested article.

moveToLastArticle

public boolean moveToLastArticle()

Move to the previous news article. The previous article is set as the current article.

The NNTP server is sent the command last which causes the session current article pointer to be set to the previous article in the newsgroup. The class variable currentArticleID is also set to point to the previous article.

The NNTP server response to the last command is one of the following:

223 n a article retrieved - request text separately
or
412 no newsgroup selected
or
420 no current article has been selected
or
422 no previous article in this group
where n and a stand for:

1. n - News article ID or number.
2. a - News article unique message-id

Returns:

boolean - Returns true if there were no errors.

moveToNextArticle

public boolean moveToNextArticle()

Move to the next news article. The next article is set as the current article.

The NNTP server is sent the command next which causes the session current article pointer to be set to the next article in the newsgroup. The class variable currentArticleID is also set to point to the next article.

The NNTP server response to the next command is the same as that for the last command.

Returns:

boolean - Returns true if there were no errors.

postMessage

public boolean postMessage(java.lang.String message)
                    throws java.io.IOException

Post a message to the current newsgroup. The message parameter should comply with the format specified in RFC1036, and end with the mandatory period (".") on a new line. This method assumes that you have formatted your message properly.

The NNTP server is sent the message post followed by the contents of the message parameter. The responses specified by RFC977 are:

240 article posted ok
340 send article to be posted. End with .
440 posting not allowed
441 posting failed

Parameters:

message - - The message formatted as per RFC1036 specifications and ended by a period( "." ) on a new line.

Returns:

boolean - Returns true if posting was successful.

Throws:

java.io.IOException

postMessage

public boolean postMessage(java.lang.String groupName,
                           java.lang.String message)
                    throws java.io.IOException

Post a message to the specified newsgroup. This method sets the current newsgroup to the specified newsgroup, and then invokes postMessage( String ) method to post the message specified.

Parameters:

groupName - - The news group to post the message to.

message - - The message formatted as per RFC1036 specifications and ended by a period( "." ) on a new line.

Returns:

boolean - Returns true if posting was successful.

Throws:

java.io.IOException

processTextResponse

private java.lang.String processTextResponse()
                                      throws java.io.IOException

Process the response from the NNTP server. This method is invoked by the getFullArticle( String, int ), getFullArticle( int ), getArticleHead( String, int ), getArticleHead( int ), getArticleHead( String, int ), getArticleHead( int ) methods.

Throws:

java.io.IOException

putNNTPCommand

public boolean putNNTPCommand(java.lang.String command,
                              boolean checkResponse)
                       throws java.io.IOException

Send the specified command to the NNTP server.

Parameters:

command - - The command to send to the NNTP server

checkResponse - - Flag to indicate whether the first line of the response text from NNTP server should be checked for starting with a 2 or not. Use the CHECK_COMMAND_RESPONSE constant to indicate that you wish the checking to be done, or NO_CHECK_COMMAND_RESPONSE constant to indicate that you do not wish the checking to be done.

Returns:

boolean - Returns true if we got a response (the response may not be OK)

Throws:

java.io.IOException

setNewsGroup

public boolean setNewsGroup(java.lang.String groupName)

Set the current news group.

Send the NNTP server a group <groupName> command.

Parameters:

groupName - - The newsgroup to set as the current group

Returns:

boolean - Return true if there were no errors.

getNNTPServer

public final java.lang.String getNNTPServer()

Get the DNS name of the NNTP server.

getNNTPPort

public final int getNNTPPort()

Get the NNTP port that we connect to.

getNNTPSocket

public final java.net.Socket getNNTPSocket()

Return a reference to this class.

getNewsGroupName

public final java.lang.String getNewsGroupName()

The current newsgroup that is being accessed.

getCurrentArticleID

public final int getCurrentArticleID()

The article-id of the current article

setErrorStream

public final void setErrorStream(java.io.PrintStream err)

Set the PrintStream object that is used to display error messages.