Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
   /*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package org.apache.commons.net.nntp;
  
  import java.io.Reader;
  import java.io.Writer;
  import java.util.Vector;
  
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 before doing anything, and finally disconnect() after you're completely finished interacting with the server. Remember that the isAllowedToPost() 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 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() to properly clean up the system resources used by NNTP. Before disconnecting, you may check the last reply code and text with getReplyCode and getReplyString .

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.

  
  
  public class NNTPClient extends NNTP
  {

    
Parse the reply and store the id and number in the pointer.

Parameters:
reply the reply to parse "22n nnn <aaa>"
pointer the pointer to update
Throws:
org.apache.commons.net.MalformedServerReplyException
  
     private void __parseArticlePointer(String replyArticleInfo pointer)
     {
         String tokens[] = reply.split(" ");
         if (tokens.length >= 3) { // OK, we can parset the line
             int i = 1; // skip reply code
             try
             {
                 // Get article number
                 pointer.articleNumber = Long.parseLong(tokens[i++]);
                 // Get article id
                 pointer.articleId = tokens[i++];
                 return// done
             }
             catch (NumberFormatException e)
             {
                 // drop through and raise exception
             }
         }
         throw new MalformedServerReplyException(
             "Could not parse article pointer.\nServer reply: " + reply);
     }
 
     /*
      * 211 n f l s group selected
      *     (n = estimated number of articles in group,
      *     f = first article number in the group,
      *     l = last article number in the group,
      *     s = name of the group.)
      */
 
     private static void __parseGroupReply(String replyNewsgroupInfo info)
     {
         String tokens[] = reply.split(" ");
         if (tokens.length >= 5) {
             int i = 1;  // Skip numeric response value
             try
             {
                 // Get estimated article count
                 info._setArticleCount(Long.parseLong(tokens[i++]));
                 // Get first article number
                 info._setFirstArticle(Long.parseLong(tokens[i++]));
                 // Get last article number
                 info._setLastArticle(Long.parseLong(tokens[i++]));
                 // Get newsgroup name
                 info._setNewsgroup(tokens[i++]);
 
                 info._setPostingPermission(.);
                 return ;
             } catch (NumberFormatException e)
             {
                // drop through to report error
             }
         }
 
         throw new MalformedServerReplyException(
             "Could not parse newsgroup info.\nServer reply: " + reply);
     }
 
 
     // Format: group last first p
     {
         String tokens[] = entry.split(" ");
         if (tokens.length < 4) {
             return null;
         }
         NewsgroupInfo result = new NewsgroupInfo();
 
         int i = 0;
 
         result._setNewsgroup(tokens[i++]);
 
         try
         {
             long lastNum = Long.parseLong(tokens[i++]);
             long firstNum = Long.parseLong(tokens[i++]);
             result._setFirstArticle(firstNum);
             result._setLastArticle(lastNum);
             if ((firstNum == 0) && (lastNum == 0)) {
                 result._setArticleCount(0);
             } else {
                 result._setArticleCount(lastNum - firstNum + 1);
             }
         } catch (NumberFormatException e) {
             return null;
         }
 
         switch (tokens[i++].charAt(0))
         {
         case 'y':
         case 'Y':
             result._setPostingPermission(
                 .);
             break;
         case 'n':
         case 'N':
             result._setPostingPermission(
                 .);
             break;
         case 'm':
         case 'M':
             result._setPostingPermission(
                 .);
             break;
         default:
             result._setPostingPermission(
                 .);
             break;
         }
 
         return result;
     }

    
Parse a response line from retrieveArticleInfo(long,long).

Parameters:
line a response line
Returns:
the parsed Article, if unparseable then isDummy() will be true, and the subject will contain the raw info.
Since:
3.0
 
     static Article __parseArticleEntry(String line) {
         // Extract the article information
         // Mandatory format (from NNTP RFC 2980) is :
         // articleNumber\tSubject\tAuthor\tDate\tID\tReference(s)\tByte Count\tLine Count
 
         Article article = new Article();
         article.setSubject(line); // in case parsing fails
         String parts[] = line.split("\t");
         if (parts.length > 6) {
             int i = 0;
             try {
                 article.setArticleNumber(Long.parseLong(parts[i++]));
                 article.setSubject(parts[i++]);
                 article.setFrom(parts[i++]);
                 article.setDate(parts[i++]);
                 article.setArticleId(parts[i++]);
                 article.addReference(parts[i++]);
             } catch (NumberFormatException e) {
                 // ignored, already handled
             }
         }
         return article;
     }
 
     private NewsgroupInfo[] __readNewsgroupListing() throws IOException
     {
 
         BufferedReader reader = new DotTerminatedMessageReader();
         // Start of with a big vector because we may be reading a very large
         // amount of groups.
         Vector<NewsgroupInfolist = new Vector<NewsgroupInfo>(2048);
 
         String line;
         try {
             while ((line = reader.readLine()) != null) {
                 NewsgroupInfo tmp = __parseNewsgroupListEntry(line);
                 if (tmp != null) {
                     list.addElement(tmp);
                 } else {
                     throw new MalformedServerReplyException(line);
                 }
             }
         } finally {
             reader.close();
         }
         int size;
         if ((size = list.size()) < 1) {
             return new NewsgroupInfo[0];
         }
 
         NewsgroupInfo[] info = new NewsgroupInfo[size];
         list.copyInto(info);
 
         return info;
     }
 
 
     private BufferedReader __retrieve(int command,
                               String articleIdArticleInfo pointer)
     throws IOException
     {
         if (articleId != null)
         {
             if (!NNTPReply.isPositiveCompletion(sendCommand(commandarticleId))) {
                 return null;
             }
         }
         else
         {
             if (!NNTPReply.isPositiveCompletion(sendCommand(command))) {
                 return null;
             }
         }
 
 
         if (pointer != null) {
             __parseArticlePointer(getReplyString(), pointer);
         }
 
         return new DotTerminatedMessageReader();
     }
 
 
     private BufferedReader __retrieve(int command,
                               long articleNumberArticleInfo pointer)
     throws IOException
     {
         if (!NNTPReply.isPositiveCompletion(sendCommand(command,
                                             Long.toString(articleNumber)))) {
             return null;
         }
 
         if (pointer != null) {
             __parseArticlePointer(getReplyString(), pointer);
         }
 
         return new DotTerminatedMessageReader();
     }



    
Retrieves an article from the NNTP server. The article is referenced by its unique article identifier (including the enclosing &lt and &gt). The article number and identifier contained in the server reply are returned through an ArticleInfo. The articleId field of the ArticleInfo 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 BufferedReader instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader 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.

Parameters:
articleId The unique article identifier of the article to retrieve. If this parameter is null, the currently selected article is retrieved.
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
A DotTerminatedMessageReader instance from which the article be read. null if the article does not exist.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public BufferedReader retrieveArticle(String articleIdArticleInfo pointer)
     throws IOException
     {
         return __retrieve(.articleIdpointer);
 
     }

    
Same as retrieveArticle(articleId, (ArticleInfo) null) Note: the return can be cast to a java.io.BufferedReader
 
     public Reader retrieveArticle(String articleIdthrows IOException
     {
         return retrieveArticle(articleId, (ArticleInfonull);
     }

    
Same as retrieveArticle((String) null) Note: the return can be cast to a java.io.BufferedReader
 
     public Reader retrieveArticle() throws IOException
     {
         return retrieveArticle((Stringnull);
     }


    
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 ArticleInfo. The articleId field of the ArticleInfo 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 BufferedReader instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader 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.

Parameters:
articleNumber The number of the the article to retrieve.
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
A DotTerminatedMessageReader instance from which the article be read. null if the article does not exist.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public BufferedReader retrieveArticle(long articleNumberArticleInfo pointer)
     throws IOException
     {
         return __retrieve(.articleNumberpointer);
     }

    
Same as retrieveArticle(articleNumber, null) *
 
     public BufferedReader retrieveArticle(long articleNumberthrows IOException
     {
         return retrieveArticle(articleNumbernull);
     }



    
Retrieves an article header from the NNTP server. The article is referenced by its unique article identifier (including the enclosing &lt and &gt). The article number and identifier contained in the server reply are returned through an ArticleInfo. The articleId field of the ArticleInfo 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 BufferedReader instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader 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.

Parameters:
articleId The unique article identifier of the article whose header is being retrieved. If this parameter is null, the header of the currently selected article is retrieved.
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
A DotTerminatedMessageReader instance from which the article header can be read. null if the article does not exist.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public BufferedReader retrieveArticleHeader(String articleIdArticleInfo pointer)
     throws IOException
     {
         return __retrieve(.articleIdpointer);
 
     }

    
Same as retrieveArticleHeader(articleId, (ArticleInfo) null) Note: the return can be cast to a java.io.BufferedReader
 
     public Reader retrieveArticleHeader(String articleIdthrows IOException
     {
         return retrieveArticleHeader(articleId, (ArticleInfonull);
     }

    
Same as retrieveArticleHeader((String) null) Note: the return can be cast to a java.io.BufferedReader
 
     public Reader retrieveArticleHeader() throws IOException
     {
         return retrieveArticleHeader((Stringnull);
     }


    
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 ArticleInfo. The articleId field of the ArticleInfo 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 BufferedReader instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader 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.

Parameters:
articleNumber The number of the the article whose header is being retrieved.
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
A DotTerminatedMessageReader instance from which the article header can be read. null if the article does not exist.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public BufferedReader retrieveArticleHeader(long articleNumber,
                                         ArticleInfo pointer)
     throws IOException
     {
         return __retrieve(.articleNumberpointer);
     }


    
Same as retrieveArticleHeader(articleNumber, null) *
 
     public BufferedReader retrieveArticleHeader(long articleNumberthrows IOException
     {
         return retrieveArticleHeader(articleNumbernull);
     }



    
Retrieves an article body from the NNTP server. The article is referenced by its unique article identifier (including the enclosing &lt and &gt). The article number and identifier contained in the server reply are returned through an ArticleInfo. The articleId field of the ArticleInfo 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 BufferedReader instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader 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.

Parameters:
articleId The unique article identifier of the article whose body is being retrieved. If this parameter is null, the body of the currently selected article is retrieved.
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public BufferedReader retrieveArticleBody(String articleIdArticleInfo pointer)
     throws IOException
     {
         return __retrieve(.articleIdpointer);
 
     }

    
Same as retrieveArticleBody(articleId, (ArticleInfo) null) Note: the return can be cast to a java.io.BufferedReader
 
     public Reader retrieveArticleBody(String articleIdthrows IOException
     {
         return retrieveArticleBody(articleId, (ArticleInfonull);
     }

    
Same as retrieveArticleBody(null) Note: the return can be cast to a java.io.BufferedReader
 
     public Reader retrieveArticleBody() throws IOException
     {
         return retrieveArticleBody(null);
     }


    
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 ArticleInfo. The articleId field of the ArticleInfo 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 BufferedReader instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore the returned BufferedReader 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.

Parameters:
articleNumber The number of the the article whose body is being retrieved.
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public BufferedReader retrieveArticleBody(long articleNumber,
                                       ArticleInfo pointer)
     throws IOException
     {
         return __retrieve(.articleNumberpointer);
     }


    
Same as retrieveArticleBody(articleNumber, null) *
 
     public BufferedReader retrieveArticleBody(long articleNumberthrows IOException
     {
         return retrieveArticleBody(articleNumbernull);
     }


    
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.

Parameters:
newsgroup The newsgroup to select.
info A parameter through which the newsgroup information of the selected newsgroup contained in the server reply is returned. Set this to null if you do not desire this information.
Returns:
True if the newsgroup exists and was selected, false otherwise.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public boolean selectNewsgroup(String newsgroupNewsgroupInfo info)
     throws IOException
     {
         if (!NNTPReply.isPositiveCompletion(group(newsgroup))) {
             return false;
         }
 
         if (info != null) {
             __parseGroupReply(getReplyString(), info);
         }
 
         return true;
     }

    
Same as selectNewsgroup(newsgroup, null) *
 
     public boolean selectNewsgroup(String newsgroupthrows IOException
     {
         return selectNewsgroup(newsgroupnull);
     }

    
List the command help from the server.

Returns:
The sever help information.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public String listHelp() throws IOException
     {
         if (!NNTPReply.isInformational(help())) {
             return null;
         }
 
         StringWriter help = new StringWriter();
         BufferedReader reader = new DotTerminatedMessageReader();
         Util.copyReader(readerhelp);
         reader.close();
         help.close();
         return help.toString();
     }

    
Send a "LIST OVERVIEW.FMT" command to the server.

Returns:
the contents of the Overview format, of null if the command failed
Throws:
java.io.IOException
 
     public String[] listOverviewFmt() throws IOException
     {
         if (!NNTPReply.isPositiveCompletion(sendCommand("LIST""OVERVIEW.FMT"))){
             return null;
         }
 
         BufferedReader reader = new DotTerminatedMessageReader();
         String line;
         ArrayList<Stringlist = new ArrayList<String>();
         while((line=reader.readLine()) != null) {
             list.add(line);
         }
         reader.close();
         return list.toArray(new String[list.size()]);
     }

    
Select an article by its unique identifier (including enclosing &lt and &gt) 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.

Parameters:
articleId The unique article identifier of the article that is being selectedd. If this parameter is null, the body of the current article is selected
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
True if successful, false if not.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public boolean selectArticle(String articleIdArticleInfo pointer)
     throws IOException
     {
         if (articleId != null) {
             if (!NNTPReply.isPositiveCompletion(stat(articleId))) {
                 return false;
             }
         } else {
             if (!NNTPReply.isPositiveCompletion(stat())) {
                 return false;
             }
         }
 
         if (pointer != null) {
             __parseArticlePointer(getReplyString(), pointer);
         }
 
         return true;
     }

    
Same as selectArticle(articleId, (ArticleInfo) null) *
 
     public boolean selectArticle(String articleIdthrows IOException
     {
         return selectArticle(articleId, (ArticleInfonull);
     }

    
Same as selectArticle((String) null, articleId) . Useful for retrieving the current article number.
 
     public boolean selectArticle(ArticleInfo pointerthrows IOException
     {
         return selectArticle(nullpointer);
     }


    
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.

Parameters:
articleNumber The number of the article to select from the currently selected newsgroup.
pointer A parameter through which to return the article's number and unique id. Although the articleId field cannot always be trusted because of server deviations from RFC 977 reply formats, we haven't found a server that misformats this information in response to this particular command. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
True if successful, false if not.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public boolean selectArticle(long articleNumberArticleInfo pointer)
     throws IOException
     {
         if (!NNTPReply.isPositiveCompletion(stat(articleNumber))) {
             return false;
         }
 
         if (pointer != null) {
             __parseArticlePointer(getReplyString(), pointer);
         }
 
         return true;
     }


    
Same as selectArticle(articleNumber, null) *
 
     public boolean selectArticle(long articleNumberthrows IOException
     {
         return selectArticle(articleNumbernull);
     }


    
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.

Parameters:
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
True if successful, false if not (e.g., there is no previous article).
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public boolean selectPreviousArticle(ArticleInfo pointer)
     throws IOException
     {
         if (!NNTPReply.isPositiveCompletion(last())) {
             return false;
         }
 
         if (pointer != null) {
             __parseArticlePointer(getReplyString(), pointer);
         }
 
         return true;
     }

    
Same as selectPreviousArticle((ArticleInfo) null) *
 
     public boolean selectPreviousArticle() throws IOException
     {
         return selectPreviousArticle((ArticleInfonull);
     }


    
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.

Parameters:
pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article information.
Returns:
True if successful, false if not (e.g., there is no following article).
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
 
     public boolean selectNextArticle(ArticleInfo pointerthrows IOException
     {
         if (!NNTPReply.isPositiveCompletion(next())) {
             return false;
         }
 
         if (pointer != null) {
             __parseArticlePointer(getReplyString(), pointer);
         }
 
         return true;
     }


    
Same as selectNextArticle((ArticleInfo) null) *
 
     public boolean selectNextArticle() throws IOException
     {
         return selectNextArticle((ArticleInfonull);
     }


    
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. The method uses the "LIST" command.

Returns:
An array of NewsgroupInfo instances containing the information for each newsgroup 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.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
See also:
iterateNewsgroupListing()
iterateNewsgroups()
 
     public NewsgroupInfo[] listNewsgroups() throws IOException
     {
         if (!NNTPReply.isPositiveCompletion(list())) {
             return null;
         }
 
         return __readNewsgroupListing();
     }

    
List all newsgroups served by the NNTP server. If no newsgroups are served, no entries will be returned. The method uses the "LIST" command.

Returns:
An iterable of NewsgroupInfo instances containing the information for each newsgroup served by the NNTP server. If no newsgroups are served, no entries will be returned.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.0
    public Iterable<StringiterateNewsgroupListing() throws IOException {
        if (NNTPReply.isPositiveCompletion(list())) {
            return new ReplyIterator();
        }
        throw new IOException("LIST command failed: "+getReplyString());
    }

    
List all newsgroups served by the NNTP server. If no newsgroups are served, no entries will be returned. The method uses the "LIST" command.

Returns:
An iterable of Strings containing the raw information for each newsgroup served by the NNTP server. If no newsgroups are served, no entries will be returned.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.0
        return new NewsgroupIterator(iterateNewsgroupListing());
    }

    
List the newsgroups that match a given pattern. Uses the "LIST ACTIVE" command.

Parameters:
wildmat a pseudo-regex pattern (cf. RFC 2980)
Returns:
An array of NewsgroupInfo instances containing the information for each newsgroup served by the NNTP server corresponding to the supplied pattern. If no such newsgroups are served, a zero length array will be returned. If the command fails, null will be returned.
Throws:
java.io.IOException
See also:
iterateNewsgroupListing(java.lang.String)
iterateNewsgroups(java.lang.String)
    public NewsgroupInfo[] listNewsgroups(String wildmatthrows IOException
    {
        if(!NNTPReply.isPositiveCompletion(listActive(wildmat))) {
            return null;
        }
        return __readNewsgroupListing();
    }


    
List the newsgroups that match a given pattern. Uses the "LIST ACTIVE" command.

Parameters:
wildmat a pseudo-regex pattern (cf. RFC 2980)
Returns:
An iterable of Strings containing the raw information for each newsgroup served by the NNTP server corresponding to the supplied pattern. If no such newsgroups are served, no entries will be returned.
Throws:
java.io.IOException
Since:
3.0
    public Iterable<StringiterateNewsgroupListing(String wildmatthrows IOException {
        if(NNTPReply.isPositiveCompletion(listActive(wildmat))) {
            return new ReplyIterator();
        }
        throw new IOException("LIST ACTIVE "+wildmat+" command failed: "+getReplyString());
    }

    
List the newsgroups that match a given pattern. Uses the "LIST ACTIVE" command.

Parameters:
wildmat a pseudo-regex pattern (cf. RFC 2980)
Returns:
An iterable NewsgroupInfo instances containing the information for each newsgroup served by the NNTP server corresponding to the supplied pattern. If no such newsgroups are served, no entries will be returned.
Throws:
java.io.IOException
Since:
3.0
    public Iterable<NewsgroupInfoiterateNewsgroups(String wildmatthrows IOException {
        return new NewsgroupIterator(iterateNewsgroupListing(wildmat));
    }

    
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. This uses the "NEWGROUPS" command.

Parameters:
query The query restricting how to search for new newsgroups.
Returns:
An array of NewsgroupInfo instances containing the information for each new newsgroup added to the NNTP server. If no newsgroups were added, a zero length array will be returned. If the command fails, null will be returned.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
See also:
iterateNewNewsgroups(org.apache.commons.net.nntp.NewGroupsOrNewsQuery)
iterateNewNewsgroupListing(org.apache.commons.net.nntp.NewGroupsOrNewsQuery)
    throws IOException
    {
        if (!NNTPReply.isPositiveCompletion(newgroups(
                                                query.getDate(), query.getTime(),
                                                query.isGMT(), query.getDistributions())))
        {
            return null;
        }
        return __readNewsgroupListing();
    }

    
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, no entries will be returned. This uses the "NEWGROUPS" command.

Parameters:
query The query restricting how to search for new newsgroups.
Returns:
An iterable of Strings containing the raw information for each new newsgroup added to the NNTP server. If no newsgroups were added, no entries will be returned.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.0
        if (NNTPReply.isPositiveCompletion(newgroups(
                query.getDate(), query.getTime(),
                query.isGMT(), query.getDistributions()))) {
            return new ReplyIterator();
        }
        throw new IOException("NEWGROUPS command failed: "+getReplyString());
    }

    
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, no entries will be returned. This uses the "NEWGROUPS" command.

Parameters:
query The query restricting how to search for new newsgroups.
Returns:
An iterable of NewsgroupInfo instances containing the information for each new newsgroup added to the NNTP server. If no newsgroups were added, no entries will be returned.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.0
        return new NewsgroupIterator(iterateNewNewsgroupListing(query));
    }

    
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 &lt and &gt. This uses the "NEWNEWS" command.

Parameters:
query The query restricting how to search for new news. You must add at least one newsgroup to the query.
Returns:
An array of String instances containing the unique message identifiers for each new article added to the NNTP server. If no new news is found, a zero length array will be returned. If the command fails, null will be returned.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
See also:
iterateNewNews(org.apache.commons.net.nntp.NewGroupsOrNewsQuery)
    public String[] listNewNews(NewGroupsOrNewsQuery query)
    throws IOException
    {
        if (!NNTPReply.isPositiveCompletion(
                newnews(query.getNewsgroups(), query.getDate(), query.getTime(),
                        query.isGMT(), query.getDistributions()))) {
            return null;
        }
        Vector<Stringlist = new Vector<String>();
        BufferedReader reader = new DotTerminatedMessageReader();
        String line;
        try {
            while ((line = reader.readLine()) != null) {
                list.addElement(line);
            }
        } finally {
            reader.close();
        }
        int size = list.size();
        if (size < 1) {
            return new String[0];
        }
        String[] result = new String[size];
        list.copyInto(result);
        return result;
    }

    
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, no entries will be returned. This uses the "NEWNEWS" command. You must add at least one newsgroup to the query, else the command will fail. Each String which is returned is a unique message identifier including the enclosing &lt and &gt.

Parameters:
query The query restricting how to search for new news. You must add at least one newsgroup to the query.
Returns:
An iterator of String instances containing the unique message identifiers for each new article added to the NNTP server. If no new news is found, no strings will be returned.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
Since:
3.0
    public Iterable<StringiterateNewNews(NewGroupsOrNewsQuery querythrows IOException {
        if (NNTPReply.isPositiveCompletion(newnews(
                query.getNewsgroups(), query.getDate(), query.getTime(),
                query.isGMT(), query.getDistributions()))) {
            return new ReplyIterator();
        }
        throw new IOException("NEWNEWS command failed: "+getReplyString());
    }

    
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;
 

Returns:
True if successfully completed, false if not.
Throws:
NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or independently as itself.
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
    public boolean completePendingCommand() throws IOException
    {
        return NNTPReply.isPositiveCompletion(getReply());
    }

    
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() 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() to finalize the posting and verify its success or failure from the server reply.

Returns:
A DotTerminatedMessageWriter to which the article (including header) can be written. Returns null if the command fails.
Throws:
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
    public Writer postArticle() throws IOException
    {
        if (!NNTPReply.isPositiveIntermediate(post())) {
            return null;
        }
        return new DotTerminatedMessageWriter();
    }
    public Writer forwardArticle(String articleIdthrows IOException
    {
        if (!NNTPReply.isPositiveIntermediate(ihave(articleId))) {
            return null;
        }
        return new DotTerminatedMessageWriter();
    }


    
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.

Returns:
True if successfully completed, false if not.
Throws:
java.io.IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
    public boolean logout() throws IOException
    {
        return NNTPReply.isPositiveCompletion(quit());
    }


    
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.

Parameters:
username a valid username
password the corresponding password
Returns:
True for successful login, false for a failure
Throws:
java.io.IOException
    public boolean authenticate(String usernameString password)
        throws IOException
    {
        int replyCode = authinfoUser(username);
        if (replyCode == .)
            {
                replyCode = authinfoPass(password);
                if (replyCode == .)
                    {
                         = true;
                        return true;
                    }
            }
        return false;
    }

    
Private implementation of XOVER functionality. See NNTP.xover(java.lang.String) for legal agument formats. Alternatively, read RFC 2980 :-)

Parameters:
articleRange
Returns:
Returns a DotTerminatedMessageReader if successful, null otherwise
Throws:
java.io.IOException
    private BufferedReader __retrieveArticleInfo(String articleRange)
        throws IOException
    {
        if (!NNTPReply.isPositiveCompletion(xover(articleRange))) {
            return null;
        }
        return new DotTerminatedMessageReader();
    }

    
Return article headers for a specified post.

Parameters:
articleNumber the article to retrieve headers for
Returns:
a DotTerminatedReader if successful, null otherwise
Throws:
java.io.IOException
    public BufferedReader retrieveArticleInfo(long articleNumberthrows IOException
    {
        return __retrieveArticleInfo(Long.toString(articleNumber));
    }

    
Return article headers for all articles between lowArticleNumber and highArticleNumber, inclusively. Uses the XOVER command.

Parameters:
lowArticleNumber
highArticleNumber
Returns:
a DotTerminatedReader if successful, null otherwise
Throws:
java.io.IOException
    public BufferedReader retrieveArticleInfo(long lowArticleNumber,
            long highArticleNumber)
        throws IOException
    {
        return
            __retrieveArticleInfo(lowArticleNumber + "-" +
                                             highArticleNumber);
    }

    
Return article headers for all articles between lowArticleNumber and highArticleNumber, inclusively, using the XOVER command.

Parameters:
lowArticleNumber
highArticleNumber
Returns:
an Iterable of Articles
Throws:
java.io.IOException if the command failed
Since:
3.0
    public Iterable<ArticleiterateArticleInfo(long lowArticleNumberlong highArticleNumber)
        throws IOException
    {
        BufferedReader info = retrieveArticleInfo(lowArticleNumber,highArticleNumber);
        if (info == null) {
            throw new IOException("XOVER command failed: "+getReplyString());
        }
        // N.B. info is already DotTerminated, so don't rewrap
        return new ArticleIterator(new ReplyIterator(infofalse));
    }

    
Private implementation of XHDR functionality. See NNTP.xhdr(java.lang.String,java.lang.String) for legal agument formats. Alternatively, read RFC 1036.

Parameters:
header
articleRange
Returns:
Returns a DotTerminatedMessageReader if successful, null otherwise
Throws:
java.io.IOException
    private BufferedReader __retrieveHeader(String headerString articleRange)
        throws IOException
    {
        if (!NNTPReply.isPositiveCompletion(xhdr(headerarticleRange))) {
            return null;
        }
        return new DotTerminatedMessageReader();
    }

    
Return an article header for a specified post.

Parameters:
header the header to retrieve
articleNumber the article to retrieve the header for
Returns:
a DotTerminatedReader if successful, null otherwise
Throws:
java.io.IOException
    public BufferedReader retrieveHeader(String headerlong articleNumber)
        throws IOException
    {
        return __retrieveHeader(header, Long.toString(articleNumber));
    }

    
Return an article header for all articles between lowArticleNumber and highArticleNumber, inclusively.

Parameters:
header
lowArticleNumber
highArticleNumber
Returns:
a DotTerminatedReader if successful, null otherwise
Throws:
java.io.IOException
    public BufferedReader retrieveHeader(String headerlong lowArticleNumber,
                                 long highArticleNumber)
        throws IOException
    {
        return
            __retrieveHeader(header,lowArticleNumber + "-" + highArticleNumber);
    }
    // DEPRECATED METHODS - for API compatibility only - DO NOT USE
    // ============================================================



    

Deprecated:
3.0 use retrieveHeader(java.lang.String,long,long) instead
    public Reader retrieveHeader(String sint lint h)
        throws IOException
    {
        return retrieveHeader(s, (longl, (longh);
    }

    

Deprecated:
3.0 use retrieveArticleInfo(long,long) instead
    public Reader retrieveArticleInfo(int aint bthrows IOException {
        return retrieveArticleInfo((longa, (longb);
    }

    

Deprecated:
3.0 use retrieveHeader(java.lang.String,long) instead
    public Reader retrieveHeader(String aint bthrows IOException {
        return retrieveHeader(a, (longb);
    }

    
    public boolean selectArticle(int aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        boolean b = selectArticle(aai);
        __ai2ap(aiap);
        return b;
    }

    

Deprecated:
3.0 use retrieveArticleInfo(long) instead
    public Reader retrieveArticleInfo(int athrows IOException {
        return retrieveArticleInfo((longa);
    }

    

Deprecated:
3.0 use selectArticle(long) instead
    public boolean selectArticle(int athrows IOException {
        return selectArticle((longa);
    }

    

Deprecated:
3.0 use retrieveArticleHeader(long) instead
    public Reader retrieveArticleHeader(int athrows IOException {
        return retrieveArticleHeader((longa);
    }

    
    public Reader retrieveArticleHeader(int aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        Reader rdr = retrieveArticleHeader(aai);
        __ai2ap(aiap);
        return rdr;
    }

    

Deprecated:
3.0 use retrieveArticleBody(long) instead
    public Reader retrieveArticleBody(int athrows IOException {
        return retrieveArticleBody((longa);
    }

    
    public Reader retrieveArticle(int aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        Reader rdr = retrieveArticle(aai);
        __ai2ap(aiap);
        return rdr;
    }

    

Deprecated:
3.0 use retrieveArticle(long) instead
    public Reader retrieveArticle(int athrows IOException {
        return retrieveArticle((longa);
    }

    
    public Reader retrieveArticleBody(int aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        Reader rdr = retrieveArticleBody(aai);
        __ai2ap(aiap);
        return rdr;
    }

    
    public Reader retrieveArticle(String aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        Reader rdr = retrieveArticle(aai);
        __ai2ap(aiap);
        return rdr;
    }

    
    public Reader retrieveArticleBody(String aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        Reader rdr = retrieveArticleBody(aai);
        __ai2ap(aiap);
        return rdr;
    }

    
    public Reader retrieveArticleHeader(String aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        Reader rdr = retrieveArticleHeader(aai);
        __ai2ap(aiap);
        return rdr;
    }

    
    public boolean selectArticle(String aArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        boolean b = selectArticle(aai);
        __ai2ap(aiap);
        return b;
    }

    
    public boolean selectArticle(ArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        boolean b = selectArticle(ai);
        __ai2ap(aiap);
        return b;
    }

    
    public boolean selectNextArticle(ArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        boolean b = selectNextArticle(ai);
        __ai2ap(aiap);
        return b;
    }

    
    public boolean selectPreviousArticle(ArticlePointer apthrows IOException {
        ArticleInfo ai =  __ap2ai(ap);
        boolean b = selectPreviousArticle(ai);
        __ai2ap(aiap);
        return b;
    }
   // Helper methods
    private ArticleInfo __ap2ai(@SuppressWarnings("deprecation"ArticlePointer ap) {
        if (ap == null) {
            return null;
        }
        ArticleInfo ai = new ArticleInfo();
        return ai;
    }
    @SuppressWarnings("deprecation")
    private void __ai2ap(ArticleInfo aiArticlePointer ap){
        if (ap != null) { // ai cannot be null
            ap.articleId = ai.articleId;
            ap.articleNumber = (intai.articleNumber;
        }
    }
/* Emacs configuration
 * Local variables:        **
 * mode:             java  **
 * c-basic-offset:   4     **
 * indent-tabs-mode: nil   **
 * End:                    **
 */