NNTPClient


1   /*
2    * Copyright 2001-2005 The Apache Software Foundation
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.net.nntp;
17  
18  import java.io.BufferedReader  ;
19  import java.io.IOException  ;
20  import java.io.Reader  ;
21  import java.io.StringWriter  ;
22  import java.io.Writer  ;
23  import java.util.StringTokenizer  ;
24  import java.util.Vector  ;
25  import org.apache.commons.net.io.DotTerminatedMessageReader;
26  import org.apache.commons.net.io.DotTerminatedMessageWriter;
27  import org.apache.commons.net.io.Util;
28  import org.apache.commons.net.MalformedServerReplyException;
29  
30  /***
31   * NNTPClient encapsulates all the functionality necessary to post and
32   * retrieve articles from an NNTP server.  As with all classes derived
33   * from {@link org.apache.commons.net.SocketClient},
34   * you must first connect to the server with
35   * {@link org.apache.commons.net.SocketClient#connect  connect }
36   * before doing anything, and finally
37   * {@link org.apache.commons.net.nntp.NNTP#disconnect  disconnect() }
38   * after you're completely finished interacting with the server.
39   * Remember that the
40   * {@link org.apache.commons.net.nntp.NNTP#isAllowedToPost isAllowedToPost()}
41   *  method is defined in
42   * {@link org.apache.commons.net.nntp.NNTP}.
43   * <p>
44   * You should keep in mind that the NNTP server may choose to prematurely
45   * close a connection if the client has been idle for longer than a
46   * given time period or if the server is being shutdown by the operator or
47   * some other reason.  The NNTP class will detect a
48   * premature NNTP server connection closing when it receives a
49   * {@link org.apache.commons.net.nntp.NNTPReply#SERVICE_DISCONTINUED NNTPReply.SERVICE_DISCONTINUED }
50   *  response to a command.
51   * When that occurs, the NNTP class method encountering that reply will throw
52   * an {@link org.apache.commons.net.nntp.NNTPConnectionClosedException}
53   * .
54   * <code>NNTPConectionClosedException</code>
55   * is a subclass of <code> IOException </code> and therefore need not be
56   * caught separately, but if you are going to catch it separately, its
57   * catch block must appear before the more general <code> IOException </code>
58   * catch block.  When you encounter an
59   * {@link org.apache.commons.net.nntp.NNTPConnectionClosedException}
60   * , you must disconnect the connection with
61   * {@link org.apache.commons.net.nntp.NNTP#disconnect  disconnect() }
62   *  to properly clean up the
63   * system resources used by NNTP.  Before disconnecting, you may check the
64   * last reply code and text with
65   * {@link org.apache.commons.net.nntp.NNTP#getReplyCode  getReplyCode } and
66   * {@link org.apache.commons.net.nntp.NNTP#getReplyString  getReplyString }.
67   * <p>
68   * Rather than list it separately for each method, we mention here that
69   * every method communicating with the server and throwing an IOException
70   * can also throw a
71   * {@link org.apache.commons.net.MalformedServerReplyException}
72   * , which is a subclass
73   * of IOException.  A MalformedServerReplyException will be thrown when
74   * the reply received from the server deviates enough from the protocol
75   * specification that it cannot be interpreted in a useful manner despite
76   * attempts to be as lenient as possible.
77   * <p>
78   * <p>
79   * @author Daniel F. Savarese
80   * @author Rory Winston
81   * @author Ted Wise
82   * @see NNTP
83   * @see NNTPConnectionClosedException
84   * @see org.apache.commons.net.MalformedServerReplyException
85   ***/
86  
87  public class NNTPClient extends NNTP
88  {
89  
90      private void __parseArticlePointer(String   reply, ArticlePointer pointer)
91      throws MalformedServerReplyException
92      {
93          StringTokenizer   tokenizer;
94  
95          // Do loop is a kluge to simulate goto
96          do
97          {
98              tokenizer = new StringTokenizer  (reply);
99  
100             if (tokenizer.countTokens() < 3)
101                 break;
102 
103             // Skip numeric response value
104             tokenizer.nextToken();
105             // Get article number
106             try
107             {
108                 pointer.articleNumber = Integer.parseInt(tokenizer.nextToken());
109             }
110             catch (NumberFormatException   e)
111             {
112                 break;
113             }
114 
115             // Get article id
116             pointer.articleId = tokenizer.nextToken();
117             return ;
118         }
119         while (false);
120 
121         throw new MalformedServerReplyException(
122             "Could not parse article pointer.\nServer reply: " + reply);
123     }
124 
125 
126     private void __parseGroupReply(String   reply, NewsgroupInfo info)
127     throws MalformedServerReplyException
128     {
129         String   count, first, last;
130         StringTokenizer   tokenizer;
131 
132         // Do loop is a kluge to simulate goto
133         do
134         {
135             tokenizer = new StringTokenizer  (reply);
136 
137             if (tokenizer.countTokens() < 5)
138                 break;
139 
140             // Skip numeric response value
141             tokenizer.nextToken();
142             // Get estimated article count
143             count = tokenizer.nextToken();
144             // Get first article number
145             first = tokenizer.nextToken();
146             // Get last article number
147             last = tokenizer.nextToken();
148             // Get newsgroup name
149             info._setNewsgroup(tokenizer.nextToken());
150 
151             try
152             {
153                 info._setArticleCount(Integer.parseInt(count));
154                 info._setFirstArticle(Integer.parseInt(first));
155                 info._setLastArticle(Integer.parseInt(last));
156             }
157             catch (NumberFormatException   e)
158             {
159                 break;
160             }
161 
162             info._setPostingPermission(NewsgroupInfo.UNKNOWN_POSTING_PERMISSION);
163             return ;
164         }
165         while (false);
166 
167         throw new MalformedServerReplyException(
168             "Could not parse newsgroup info.\nServer reply: " + reply);
169     }
170 
171 
172     private NewsgroupInfo __parseNewsgroupListEntry(String   entry)
173     {
174         NewsgroupInfo result;
175         StringTokenizer   tokenizer;
176         int lastNum, firstNum;
177         String   last, first, permission;
178 
179         result = new NewsgroupInfo();
180         tokenizer = new StringTokenizer  (entry);
181 
182         if (tokenizer.countTokens() < 4)
183             return null;
184 
185         result._setNewsgroup(tokenizer.nextToken());
186         last = tokenizer.nextToken();
187         first = tokenizer.nextToken();
188         permission = tokenizer.nextToken();
189 
190         try
191         {
192             lastNum = Integer.parseInt(last);
193             firstNum = Integer.parseInt(first);
194             result._setFirstArticle(firstNum);
195             result._setLastArticle(lastNum);
196 
197         if((firstNum == 0) && (lastNum == 0))
198             result._setArticleCount(0);
199         else
200             result._setArticleCount(lastNum - firstNum + 1);
201         }
202         catch (NumberFormatException   e)
203         {
204             return null;
205         }
206 
207         switch (permission.charAt(0))
208         {
209         case 'y':
210         case 'Y':
211             result._setPostingPermission(
212                 NewsgroupInfo.PERMITTED_POSTING_PERMISSION);
213             break;
214         case 'n':
215         case 'N':
216             result._setPostingPermission(
217                 NewsgroupInfo.PROHIBITED_POSTING_PERMISSION);
218             break;
219         case 'm':
220         case 'M':
221             result._setPostingPermission(
222                 NewsgroupInfo.MODERATED_POSTING_PERMISSION);
223             break;
224         default:
225             result._setPostingPermission(
226                 NewsgroupInfo.UNKNOWN_POSTING_PERMISSION);
227             break;
228         }
229 
230         return result;
231     }
232 
233     private NewsgroupInfo[] __readNewsgroupListing() throws IOException  
234     {
235         int size;
236         String   line;
237         Vector   list;
238         BufferedReader   reader;
239         NewsgroupInfo tmp, info[];
240 
241         reader = new BufferedReader  (new DotTerminatedMessageReader(_reader_));
242         // Start of with a big vector because we may be reading a very large
243         // amount of groups.
244         list = new Vector  (2048);
245 
246         while ((line = reader.readLine()) != null)
247         {
248             tmp = __parseNewsgroupListEntry(line);
249             if (tmp != null)
250                 list.addElement(tmp);
251             else
252                 throw new MalformedServerReplyException(line);
253         }
254 
255         if ((size = list.size()) < 1)
256             return new NewsgroupInfo[0];
257 
258         info = new NewsgroupInfo[size];
259         list.copyInto(info);
260 
261         return info;
262     }
263 
264 
265     private Reader   __retrieve(int command,
266                               String   articleId, ArticlePointer pointer)
267     throws IOException  
268     {
269         Reader   reader;
270 
271         if (articleId != null)
272         {
273             if (!NNTPReply.isPositiveCompletion(sendCommand(command, articleId)))
274                 return null;
275         }
276         else
277         {
278             if (!NNTPReply.isPositiveCompletion(sendCommand(command)))
279                 return null;
280         }
281 
282 
283         if (pointer != null)
284             __parseArticlePointer(getReplyString(), pointer);
285 
286         reader = new DotTerminatedMessageReader(_reader_);
287         return reader;
288     }
289 
290 
291     private Reader   __retrieve(int command,
292                               int articleNumber, ArticlePointer pointer)
293     throws IOException  
294     {
295         Reader   reader;
296 
297         if (!NNTPReply.isPositiveCompletion(sendCommand(command,
298                                             Integer.toString(articleNumber))))
299             return null;
300 
301         if (pointer != null)
302             __parseArticlePointer(getReplyString(), pointer);
303 
304         reader = new DotTerminatedMessageReader(_reader_);
305         return reader;
306     }
307 
308 
309 
310     /***
311      * Retrieves an article from the NNTP server.  The article is referenced
312      * by its unique article identifier (including the enclosing &lt and &gt).
313      * The article number and identifier contained in the server reply
314      * are returned through an ArticlePointer.  The <code> articleId </code>
315      * field of the ArticlePointer cannot always be trusted because some
316      * NNTP servers do not correctly follow the RFC 977 reply format.
317      * <p>
318      * A DotTerminatedMessageReader is returned from which the article can
319      * be read.  If the article does not exist, null is returned.
320      * <p>
321      * You must not issue any commands to the NNTP server (i.e., call any
322      * other methods) until you finish reading the message from the returned
323      * Reader instance.
324      * The NNTP protocol uses the same stream for issuing commands as it does
325      * for returning results.  Therefore the returned Reader actually reads
326      * directly from the NNTP connection.  After the end of message has been
327      * reached, new commands can be executed and their replies read.  If
328      * you do not follow these requirements, your program will not work
329      * properly.
330      * <p>
331      * @param articleId  The unique article identifier of the article to
332      *     retrieve.  If this parameter is null, the currently selected
333      *     article is retrieved.
334      * @param pointer    A parameter through which to return the article's
335      *   number and unique id.  The articleId field cannot always be trusted
336      *   because of server deviations from RFC 977 reply formats.  You may
337      *   set this parameter to null if you do not desire to retrieve the
338      *   returned article information.
339      * @return A DotTerminatedMessageReader instance from which the article
340      *         be read.  null if the article does not exist.
341      * @exception NNTPConnectionClosedException
342      *      If the NNTP server prematurely closes the connection as a result
343      *      of the client being idle or some other reason causing the server
344      *      to send NNTP reply code 400.  This exception may be caught either
345      *      as an IOException or independently as itself.
346      * @exception IOException  If an I/O error occurs while either sending a
347      *      command to the server or receiving a reply from the server.
348      ***/
349     public Reader   retrieveArticle(String   articleId, ArticlePointer pointer)
350     throws IOException  
351     {
352         return __retrieve(NNTPCommand.ARTICLE, articleId, pointer);
353 
354     }
355 
356     /*** Same as <code> retrieveArticle(articleId, null) </code> ***/
357     public Reader   retrieveArticle(String   articleId) throws IOException  
358     {
359         return retrieveArticle(articleId, null);
360     }
361 
362     /*** Same as <code> retrieveArticle(null) </code> ***/
363     public Reader   retrieveArticle() throws IOException  
364     {
365         return retrieveArticle(null);
366     }
367 
368 
369     /***
370      * Retrieves an article from the currently selected newsgroup.  The
371      * article is referenced by its article number.
372      * The article number and identifier contained in the server reply
373      * are returned through an ArticlePointer.  The <code> articleId </code>
374      * field of the ArticlePointer cannot always be trusted because some
375      * NNTP servers do not correctly follow the RFC 977 reply format.
376      * <p>
377      * A DotTerminatedMessageReader is returned from which the article can
378      * be read.  If the article does not exist, null is returned.
379      * <p>
380      * You must not issue any commands to the NNTP server (i.e., call any
381      * other methods) until you finish reading the message from the returned
382      * Reader instance.
383      * The NNTP protocol uses the same stream for issuing commands as it does
384      * for returning results.  Therefore the returned Reader actually reads
385      * directly from the NNTP connection.  After the end of message has been
386      * reached, new commands can be executed and their replies read.  If
387      * you do not follow these requirements, your program will not work
388      * properly.
389      * <p>
390      * @param articleNumber  The number of the the article to
391      *     retrieve.
392      * @param pointer    A parameter through which to return the article's
393      *   number and unique id.  The articleId field cannot always be trusted
394      *   because of server deviations from RFC 977 reply formats.  You may
395      *   set this parameter to null if you do not desire to retrieve the
396      *   returned article information.
397      * @return A DotTerminatedMessageReader instance from which the article
398      *         be read.  null if the article does not exist.
399      * @exception NNTPConnectionClosedException
400      *      If the NNTP server prematurely closes the connection as a result
401      *      of the client being idle or some other reason causing the server
402      *      to send NNTP reply code 400.  This exception may be caught either
403      *      as an IOException or independently as itself.
404      * @exception IOException  If an I/O error occurs while either sending a
405      *      command to the server or receiving a reply from the server.
406      ***/
407     public Reader   retrieveArticle(int articleNumber, ArticlePointer pointer)
408     throws IOException  
409     {
410         return __retrieve(NNTPCommand.ARTICLE, articleNumber, pointer);
411     }
412 
413     /*** Same as <code> retrieveArticle(articleNumber, null) </code> ***/
414     public Reader   retrieveArticle(int articleNumber) throws IOException  
415     {
416         return retrieveArticle(articleNumber, null);
417     }
418 
419 
420 
421     /***
422      * Retrieves an article header from the NNTP server.  The article is
423      * referenced
424      * by its unique article identifier (including the enclosing &lt and &gt).
425      * The article number and identifier contained in the server reply
426      * are returned through an ArticlePointer.  The <code> articleId </code>
427      * field of the ArticlePointer cannot always be trusted because some
428      * NNTP servers do not correctly follow the RFC 977 reply format.
429      * <p>
430      * A DotTerminatedMessageReader is returned from which the article can
431      * be read.  If the article does not exist, null is returned.
432      * <p>
433      * You must not issue any commands to the NNTP server (i.e., call any
434      * other methods) until you finish reading the message from the returned
435      * Reader instance.
436      * The NNTP protocol uses the same stream for issuing commands as it does
437      * for returning results.  Therefore the returned Reader actually reads
438      * directly from the NNTP connection.  After the end of message has been
439      * reached, new commands can be executed and their replies read.  If
440      * you do not follow these requirements, your program will not work
441      * properly.
442      * <p>
443      * @param articleId  The unique article identifier of the article whose
444      *    header is being retrieved.  If this parameter is null, the
445      *    header of the currently selected article is retrieved.
446      * @param pointer    A parameter through which to return the article's
447      *   number and unique id.  The articleId field cannot always be trusted
448      *   because of server deviations from RFC 977 reply formats.  You may
449      *   set this parameter to null if you do not desire to retrieve the
450      *   returned article information.
451      * @return A DotTerminatedMessageReader instance from which the article
452      *         header can be read.  null if the article does not exist.
453      * @exception NNTPConnectionClosedException
454      *      If the NNTP server prematurely closes the connection as a result
455      *      of the client being idle or some other reason causing the server
456      *      to send NNTP reply code 400.  This exception may be caught either
457      *      as an IOException or independently as itself.
458      * @exception IOException  If an I/O error occurs while either sending a
459      *      command to the server or receiving a reply from the server.
460      ***/
461     public Reader   retrieveArticleHeader(String   articleId, ArticlePointer pointer)
462     throws IOException  
463     {
464         return __retrieve(NNTPCommand.HEAD, articleId, pointer);
465 
466     }
467 
468     /*** Same as <code> retrieveArticleHeader(articleId, null) </code> ***/
469     public Reader   retrieveArticleHeader(String   articleId) throws IOException  
470     {
471         return retrieveArticleHeader(articleId, null);
472     }
473 
474     /*** Same as <code> retrieveArticleHeader(null) </code> ***/
475     public Reader   retrieveArticleHeader() throws IOException  
476     {
477         return retrieveArticleHeader(null);
478     }
479 
480 
481     /***
482      * Retrieves an article header from the currently selected newsgroup.  The
483      * article is referenced by its article number.
484      * The article number and identifier contained in the server reply
485      * are returned through an ArticlePointer.  The <code> articleId </code>
486      * field of the ArticlePointer cannot always be trusted because some
487      * NNTP servers do not correctly follow the RFC 977 reply format.
488      * <p>
489      * A DotTerminatedMessageReader is returned from which the article can
490      * be read.  If the article does not exist, null is returned.
491      * <p>
492      * You must not issue any commands to the NNTP server (i.e., call any
493      * other methods) until you finish reading the message from the returned
494      * Reader instance.
495      * The NNTP protocol uses the same stream for issuing commands as it does
496      * for returning results.  Therefore the returned Reader actually reads
497      * directly from the NNTP connection.  After the end of message has been
498      * reached, new commands can be executed and their replies read.  If
499      * you do not follow these requirements, your program will not work
500      * properly.
501      * <p>
502      * @param articleNumber  The number of the the article whose header is
503      *     being retrieved.
504      * @param pointer    A parameter through which to return the article's
505      *   number and unique id.  The articleId field cannot always be trusted
506      *   because of server deviations from RFC 977 reply formats.  You may
507      *   set this parameter to null if you do not desire to retrieve the
508      *   returned article information.
509      * @return A DotTerminatedMessageReader instance from which the article
510      *         header can be read.  null if the article does not exist.
511      * @exception NNTPConnectionClosedException
512      *      If the NNTP server prematurely closes the connection as a result
513      *      of the client being idle or some other reason causing the server
514      *      to send NNTP reply code 400.  This exception may be caught either
515      *      as an IOException or independently as itself.
516      * @exception IOException  If an I/O error occurs while either sending a
517      *      command to the server or receiving a reply from the server.
518      ***/
519     public Reader   retrieveArticleHeader(int articleNumber,
520                                         ArticlePointer pointer)
521     throws IOException  
522     {
523         return __retrieve(NNTPCommand.HEAD, articleNumber, pointer);
524     }
525 
526 
527     /*** Same as <code> retrieveArticleHeader(articleNumber, null) </code> ***/
528     public Reader   retrieveArticleHeader(int articleNumber) throws IOException  
529     {
530         return retrieveArticleHeader(articleNumber, null);
531     }
532 
533 
534 
535     /***
536      * Retrieves an article body from the NNTP server.  The article is
537      * referenced
538      * by its unique article identifier (including the enclosing &lt and &gt).
539      * The article number and identifier contained in the server reply
540      * are returned through an ArticlePointer.  The <code> articleId </code>
541      * field of the ArticlePointer cannot always be trusted because some
542      * NNTP servers do not correctly follow the RFC 977 reply format.
543      * <p>
544      * A DotTerminatedMessageReader is returned from which the article can
545      * be read.  If the article does not exist, null is returned.
546      * <p>
547      * You must not issue any commands to the NNTP server (i.e., call any
548      * other methods) until you finish reading the message from the returned
549      * Reader instance.
550      * The NNTP protocol uses the same stream for issuing commands as it does
551      * for returning results.  Therefore the returned Reader actually reads
552      * directly from the NNTP connection.  After the end of message has been
553      * reached, new commands can be executed and their replies read.  If
554      * you do not follow these requirements, your program will not work
555      * properly.
556      * <p>
557      * @param articleId  The unique article identifier of the article whose
558      *    body is being retrieved.  If this parameter is null, the
559      *    body of the currently selected article is retrieved.
560      * @param pointer    A parameter through which to return the article's
561      *   number and unique id.  The articleId field cannot always be trusted
562      *   because of server deviations from RFC 977 reply formats.  You may
563      *   set this parameter to null if you do not desire to retrieve the
564      *   returned article information.
565      * @return A DotTerminatedMessageReader instance from which the article
566      *         body can be read.  null if the article does not exist.
567      * @exception NNTPConnectionClosedException
568      *      If the NNTP server prematurely closes the connection as a result
569      *      of the client being idle or some other reason causing the server
570      *      to send NNTP reply code 400.  This exception may be caught either
571      *      as an IOException or independently as itself.
572      * @exception IOException  If an I/O error occurs while either sending a
573      *      command to the server or receiving a reply from the server.
574      ***/
575     public Reader   retrieveArticleBody(String   articleId, ArticlePointer pointer)
576     throws IOException  
577     {
578         return __retrieve(NNTPCommand.BODY, articleId, pointer);
579 
580     }
581 
582     /*** Same as <code> retrieveArticleBody(articleId, null) </code> ***/
583     public Reader   retrieveArticleBody(String   articleId) throws IOException  
584     {
585         return retrieveArticleBody(articleId, null);
586     }
587 
588     /*** Same as <code> retrieveArticleBody(null) </code> ***/
589     public Reader   retrieveArticleBody() throws IOException  
590     {
591         return retrieveArticleBody(null);
592     }
593 
594 
595     /***
596      * Retrieves an article body from the currently selected newsgroup.  The
597      * article is referenced by its article number.
598      * The article number and identifier contained in the server reply
599      * are returned through an ArticlePointer.  The <code> articleId </code>
600      * field of the ArticlePointer cannot always be trusted because some
601      * NNTP servers do not correctly follow the RFC 977 reply format.
602      * <p>
603      * A DotTerminatedMessageReader is returned from which the article can
604      * be read.  If the article does not exist, null is returned.
605      * <p>
606      * You must not issue any commands to the NNTP server (i.e., call any
607      * other methods) until you finish reading the message from the returned
608      * Reader instance.
609      * The NNTP protocol uses the same stream for issuing commands as it does
610      * for returning results.  Therefore the returned Reader actually reads
611      * directly from the NNTP connection.  After the end of message has been
612      * reached, new commands can be executed and their replies read.  If
613      * you do not follow these requirements, your program will not work
614      * properly.
615      * <p>
616      * @param articleNumber  The number of the the article whose body is
617      *     being retrieved.
618      * @param pointer    A parameter through which to return the article's
619      *   number and unique id.  The articleId field cannot always be trusted
620      *   because of server deviations from RFC 977 reply formats.  You may
621      *   set this parameter to null if you do not desire to retrieve the
622      *   returned article information.
623      * @return A DotTerminatedMessageReader instance from which the article
624      *         body can be read.  null if the article does not exist.
625      * @exception NNTPConnectionClosedException
626      *      If the NNTP server prematurely closes the connection as a result
627      *      of the client being idle or some other reason causing the server
628      *      to send NNTP reply code 400.  This exception may be caught either
629      *      as an IOException or independently as itself.
630      * @exception IOException  If an I/O error occurs while either sending a
631      *      command to the server or receiving a reply from the server.
632      ***/
633     public Reader   retrieveArticleBody(int articleNumber,
634                                       ArticlePointer pointer)
635     throws IOException  
636     {
637         return __retrieve(NNTPCommand.BODY, articleNumber, pointer);
638     }
639 
640 
641     /*** Same as <code> retrieveArticleBody(articleNumber, null) </code> ***/
642     public Reader   retrieveArticleBody(int articleNumber) throws IOException  
643     {
644         return retrieveArticleBody(articleNumber, null);
645     }
646 
647 
648     /***
649      * Select the specified newsgroup to be the target of for future article
650      * retrieval and posting operations.  Also return the newsgroup
651      * information contained in the server reply through the info parameter.
652      * <p>
653      * @param newsgroup  The newsgroup to select.
654      * @param info  A parameter through which the newsgroup information of
655      *      the selected newsgroup contained in the server reply is returned.
656      *      Set this to null if you do not desire this information.
657      * @return True if the newsgroup exists and was selected, false otherwise.
658      * @exception NNTPConnectionClosedException
659      *      If the NNTP server prematurely closes the connection as a result
660      *      of the client being idle or some other reason causing the server
661      *      to send NNTP reply code 400.  This exception may be caught either
662      *      as an IOException or independently as itself.
663      * @exception IOException  If an I/O error occurs while either sending a
664      *      command to the server or receiving a reply from the server.
665      ***/
666     public boolean selectNewsgroup(String   newsgroup, NewsgroupInfo info)
667     throws IOException  
668     {
669         if (!NNTPReply.isPositiveCompletion(group(newsgroup)))
670             return false;
671 
672         if (info != null)
673             __parseGroupReply(getReplyString(), info);
674 
675         return true;
676     }
677 
678     /*** Same as <code> selectNewsgroup(newsgroup, null) </code> ***/
679     public boolean selectNewsgroup(String   newsgroup) throws IOException  
680     {
681         return selectNewsgroup(newsgroup, null);
682     }
683 
684     /***
685      * List the command help from the server.
686      * <p>
687      * @return The sever help information.
688      * @exception NNTPConnectionClosedException
689      *      If the NNTP server prematurely closes the connection as a result
690      *      of the client being idle or some other reason causing the server
691      *      to send NNTP reply code 400.  This exception may be caught either
692      *      as an IOException or independently as itself.
693      * @exception IOException  If an I/O error occurs while either sending a
694      *      command to the server or receiving a reply from the server.
695      ***/
696     public String   listHelp() throws IOException  
697     {
698         StringWriter   help;
699         Reader   reader;
700 
701         if (!NNTPReply.isInformational(help()))
702             return null;
703 
704         help = new StringWriter  ();
705         reader = new DotTerminatedMessageReader(_reader_);
706         Util.copyReader(reader, help);
707         reader.close();
708         help.close();
709         return help.toString();
710     }
711 
712 
713     /***
714      * Select an article by its unique identifier (including enclosing
715      * &lt and &gt) and return its article number and id through the
716      * pointer parameter.  This is achieved through the STAT command.
717      * According to RFC 977, this will NOT set the current article pointer
718      * on the server.  To do that, you must reference the article by its
719      * number.
720      * <p>
721      * @param articleId  The unique article identifier of the article that
722      *    is being selectedd.  If this parameter is null, the
723      *    body of the current article is selected
724      * @param pointer    A parameter through which to return the article's
725      *   number and unique id.  The articleId field cannot always be trusted
726      *   because of server deviations from RFC 977 reply formats.  You may
727      *   set this parameter to null if you do not desire to retrieve the
728      *   returned article information.
729      * @return True if successful, false if not.
730      * @exception NNTPConnectionClosedException
731      *      If the NNTP server prematurely closes the connection as a result
732      *      of the client being idle or some other reason causing the server
733      *      to send NNTP reply code 400.  This exception may be caught either
734      *      as an IOException or independently as itself.
735      * @exception IOException  If an I/O error occurs while either sending a
736      *      command to the server or receiving a reply from the server.
737      ***/
738     public boolean selectArticle(String   articleId, ArticlePointer pointer)
739     throws IOException  
740     {
741         if (articleId != null)
742         {
743             if (!NNTPReply.isPositiveCompletion(stat(articleId)))
744                 return false;
745         }
746         else
747         {
748             if (!NNTPReply.isPositiveCompletion(stat()))
749                 return false;
750         }
751 
752         if (pointer != null)
753             __parseArticlePointer(getReplyString(), pointer);
754 
755         return true;
756     }
757 
758     /**** Same as <code> selectArticle(articleId, null) </code> ***/
759     public boolean selectArticle(String   articleId) throws IOException  
760     {
761         return selectArticle(articleId, null);
762     }
763 
764     /****
765      * Same as <code> selectArticle(null, articleId) </code>.  Useful
766      * for retrieving the current article number.
767      ***/
768     public boolean selectArticle(ArticlePointer pointer) throws IOException  
769     {
770         return selectArticle(null, pointer);
771     }
772 
773 
774     /***
775      * Select an article in the currently selected newsgroup by its number.
776      * and return its article number and id through the
777      * pointer parameter.  This is achieved through the STAT command.
778      * According to RFC 977, this WILL set the current article pointer
779      * on the server.  Use this command to select an article before retrieving
780      * it, or to obtain an article's unique identifier given its number.
781      * <p>
782      * @param articleNumber The number of the article to select from the
783      *       currently selected newsgroup.
784      * @param pointer    A parameter through which to return the article's
785      *   number and unique id.  Although the articleId field cannot always
786      *   be trusted because of server deviations from RFC 977 reply formats,
787      *   we haven't found a server that misformats this information in response
788      *   to this particular command.  You may set this parameter to null if
789      *   you do not desire to retrieve the returned article information.
790      * @return True if successful, false if not.
791      * @exception NNTPConnectionClosedException
792      *      If the NNTP server prematurely closes the connection as a result
793      *      of the client being idle or some other reason causing the server
794      *      to send NNTP reply code 400.  This exception may be caught either
795      *      as an IOException or independently as itself.
796      * @exception IOException  If an I/O error occurs while either sending a
797      *      command to the server or receiving a reply from the server.
798      ***/
799     public boolean selectArticle(int articleNumber, ArticlePointer pointer)
800     throws IOException  
801     {
802         if (!NNTPReply.isPositiveCompletion(stat(articleNumber)))
803             return false;
804 
805         if (pointer != null)
806             __parseArticlePointer(getReplyString(), pointer);
807 
808         return true;
809     }
810 
811 
812     /*** Same as <code> selectArticle(articleNumber, null) </code> ***/
813     public boolean selectArticle(int articleNumber) throws IOException  
814     {
815         return selectArticle(articleNumber, null);
816     }
817 
818 
819     /***
820      * Select the article preceeding the currently selected article in the
821      * currently selected newsgroup and return its number and unique id
822      * through the pointer parameter.  Because of deviating server
823      * implementations, the articleId information cannot be trusted.  To
824      * obtain the article identifier, issue a
825      * <code> selectArticle(pointer.articleNumber, pointer) </code> immediately
826      * afterward.
827      * <p>
828      * @param pointer    A parameter through which to return the article's
829      *   number and unique id.  The articleId field cannot always be trusted
830      *   because of server deviations from RFC 977 reply formats.  You may
831      *   set this parameter to null if you do not desire to retrieve the
832      *   returned article information.
833      * @return True if successful, false if not (e.g., there is no previous
834      *     article).
835      * @exception NNTPConnectionClosedException
836      *      If the NNTP server prematurely closes the connection as a result
837      *      of the client being idle or some other reason causing the server
838      *      to send NNTP reply code 400.  This exception may be caught either
839      *      as an IOException or independently as itself.
840      * @exception IOException  If an I/O error occurs while either sending a
841      *      command to the server or receiving a reply from the server.
842      ***/
843     public boolean selectPreviousArticle(ArticlePointer pointer)
844     throws IOException  
845     {
846         if (!NNTPReply.isPositiveCompletion(last()))
847             return false;
848 
849         if (pointer != null)
850             __parseArticlePointer(getReplyString(), pointer);
851 
852         return true;
853     }
854 
855     /*** Same as <code> selectPreviousArticle(null) </code> ***/
856     public boolean selectPreviousArticle() throws IOException  
857     {
858         return selectPreviousArticle(null);
859     }
860 
861 
862     /***
863      * Select the article following the currently selected article in the
864      * currently selected newsgroup and return its number and unique id
865      * through the pointer parameter.  Because of deviating server
866      * implementations, the articleId information cannot be trusted.  To
867      * obtain the article identifier, issue a
868      * <code> selectArticle(pointer.articleNumber, pointer) </code> immediately
869      * afterward.
870      * <p>
871      * @param pointer    A parameter through which to return the article's
872      *   number and unique id.  The articleId field cannot always be trusted
873      *   because of server deviations from RFC 977 reply formats.  You may
874      *   set this parameter to null if you do not desire to retrieve the
875      *   returned article information.
876      * @return True if successful, false if not (e.g., there is no following
877      *         article).
878      * @exception NNTPConnectionClosedException
879      *      If the NNTP server prematurely closes the connection as a result
880      *      of the client being idle or some other reason causing the server
881      *      to send NNTP reply code 400.  This exception may be caught either
882      *      as an IOException or independently as itself.
883      * @exception IOException  If an I/O error occurs while either sending a
884      *      command to the server or receiving a reply from the server.
885      ***/
886     public boolean selectNextArticle(ArticlePointer pointer) throws IOException  
887