NNTPClient.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.apache.commons.net.nntp;

  20. import java.io.BufferedReader;
  21. import java.io.IOException;
  22. import java.io.Reader;
  23. import java.io.StringWriter;
  24. import java.io.Writer;
  25. import java.util.ArrayList;
  26. import java.util.Vector;

  28. import org.apache.commons.net.MalformedServerReplyException;
  29. import org.apache.commons.net.io.DotTerminatedMessageReader;
  30. import org.apache.commons.net.io.DotTerminatedMessageWriter;
  31. import org.apache.commons.net.io.Util;
  32. import org.apache.commons.net.util.NetConstants;

  34. /**
  35.  * NNTPClient encapsulates all the functionality necessary to post and retrieve articles from an NNTP server. As with all classes derived from
  36.  * {@link org.apache.commons.net.SocketClient}, you must first connect to the server with {@link org.apache.commons.net.SocketClient#connect connect } before
  37.  * doing anything, and finally {@link org.apache.commons.net.nntp.NNTP#disconnect disconnect() } after you're completely finished interacting with the server.
  38.  * Remember that the {@link org.apache.commons.net.nntp.NNTP#isAllowedToPost isAllowedToPost()} method is defined in {@link org.apache.commons.net.nntp.NNTP}.
  39.  * <p>
  40.  * 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
  41.  * 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
  42.  * a {@link org.apache.commons.net.nntp.NNTPReply#SERVICE_DISCONTINUED NNTPReply.SERVICE_DISCONTINUED } response to a command. When that occurs, the NNTP class
  43.  * method encountering that reply will throw an {@link org.apache.commons.net.nntp.NNTPConnectionClosedException} . <code>NNTPConectionClosedException</code> is
  44.  * a subclass of <code>IOException</code> and therefore need not be caught separately, but if you are going to catch it separately, its catch block must
  45.  * appear before the more general <code>IOException</code> catch block. When you encounter an
  46.  * {@link org.apache.commons.net.nntp.NNTPConnectionClosedException} , you must disconnect the connection with
  47.  * {@link org.apache.commons.net.nntp.NNTP#disconnect disconnect() } to properly clean up the system resources used by NNTP. Before disconnecting, you may check
  48.  * the last reply code and text with {@link org.apache.commons.net.nntp.NNTP#getReplyCode getReplyCode } and
  49.  * {@link org.apache.commons.net.nntp.NNTP#getReplyString getReplyString }.
  50.  * </p>
  51.  * <p>
  52.  * 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
  53.  * {@link org.apache.commons.net.MalformedServerReplyException} , which is a subclass of IOException. A MalformedServerReplyException will be thrown when the
  54.  * 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
  55.  * lenient as possible.
  56.  * </p>
  57.  *
  58.  * @see NNTP
  59.  * @see NNTPConnectionClosedException
  60.  * @see org.apache.commons.net.MalformedServerReplyException
  61.  */

  63. public class NNTPClient extends NNTP {

  65.     private static final NewsgroupInfo[] EMPTY_NEWSGROUP_INFO_ARRAY = {};

  67.     /**
  68.      * Parse a response line from {@link #retrieveArticleInfo(long, long)}.
  69.      *
  70.      * @param line a response line
  71.      * @return the parsed {@link Article}, if unparseable then isDummy() will be true, and the subject will contain the raw info.
  72.      * @since 3.0
  73.      */
  74.     static Article parseArticleEntry(final String line) {
  75.         // Extract the article information
  76.         // Mandatory format (from NNTP RFC 2980) is :
  77.         // articleNumber\tSubject\tAuthor\tDate\tID\tReference(s)\tByte Count\tLine Count

  79.         final Article article = new Article();
  80.         article.setSubject(line); // in case parsing fails
  81.         final String[] parts = line.split("\t");
  82.         if (parts.length > 6) {
  83.             int i = 0;
  84.             try {
  85.                 article.setArticleNumber(Long.parseLong(parts[i++]));
  86.                 article.setSubject(parts[i++]);
  87.                 article.setFrom(parts[i++]);
  88.                 article.setDate(parts[i++]);
  89.                 article.setArticleId(parts[i++]);
  90.                 article.addReference(parts[i++]);
  91.             } catch (final NumberFormatException e) {
  92.                 // ignored, already handled
  93.             }
  94.         }
  95.         return article;
  96.     }

  98.     /*
  99.      * 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 =
  100.      * name of the group.)
  101.      */

  103.     private static void parseGroupReply(final String reply, final NewsgroupInfo info) throws MalformedServerReplyException {
  104.         final String[] tokens = reply.split(" ");
  105.         if (tokens.length >= 5) {
  106.             int i = 1; // Skip numeric response value
  107.             try {
  108.                 // Get estimated article count
  109.                 info.setArticleCount(Long.parseLong(tokens[i++]));
  110.                 // Get first article number
  111.                 info.setFirstArticle(Long.parseLong(tokens[i++]));
  112.                 // Get last article number
  113.                 info.setLastArticle(Long.parseLong(tokens[i++]));
  114.                 // Get newsgroup name
  115.                 info.setNewsgroup(tokens[i++]);

  117.                 info.setPostingPermission(NewsgroupInfo.UNKNOWN_POSTING_PERMISSION);
  118.                 return;
  119.             } catch (final NumberFormatException e) {
  120.                 // drop through to report error
  121.             }
  122.         }

  124.         throw new MalformedServerReplyException("Could not parse newsgroup info.\nServer reply: " + reply);
  125.     }

  127.     // Format: group last first p
  128.     static NewsgroupInfo parseNewsgroupListEntry(final String entry) {
  129.         final String[] tokens = entry.split(" ");
  130.         if (tokens.length < 4) {
  131.             return null;
  132.         }
  133.         final NewsgroupInfo result = new NewsgroupInfo();

  135.         int i = 0;

  137.         result.setNewsgroup(tokens[i++]);

  139.         try {
  140.             final long lastNum = Long.parseLong(tokens[i++]);
  141.             final long firstNum = Long.parseLong(tokens[i++]);
  142.             result.setFirstArticle(firstNum);
  143.             result.setLastArticle(lastNum);
  144.             if (firstNum == 0 && lastNum == 0) {
  145.                 result.setArticleCount(0);
  146.             } else {
  147.                 result.setArticleCount(lastNum - firstNum + 1);
  148.             }
  149.         } catch (final NumberFormatException e) {
  150.             return null;
  151.         }

  153.         switch (tokens[i++].charAt(0)) {
  154.         case 'y':
  155.         case 'Y':
  156.             result.setPostingPermission(NewsgroupInfo.PERMITTED_POSTING_PERMISSION);
  157.             break;
  158.         case 'n':
  159.         case 'N':
  160.             result.setPostingPermission(NewsgroupInfo.PROHIBITED_POSTING_PERMISSION);
  161.             break;
  162.         case 'm':
  163.         case 'M':
  164.             result.setPostingPermission(NewsgroupInfo.MODERATED_POSTING_PERMISSION);
  165.             break;
  166.         default:
  167.             result.setPostingPermission(NewsgroupInfo.UNKNOWN_POSTING_PERMISSION);
  168.             break;
  169.         }

  171.         return result;
  172.     }

  174.     @SuppressWarnings("deprecation")
  175.     private void ai2ap(final ArticleInfo ai, final ArticlePointer ap) {
  176.         if (ap != null) { // ai cannot be null
  177.             ap.articleId = ai.articleId;
  178.             ap.articleNumber = (int) ai.articleNumber;
  179.         }
  180.     }

  182.     private ArticleInfo ap2ai(@SuppressWarnings("deprecation") final ArticlePointer ap) {
  183.         if (ap == null) {
  184.             return null;
  185.         }
  186.         return new ArticleInfo();
  187.     }

  189.     /**
  190.      * 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
  191.      * server.
  192.      *
  193.      * @param user a valid user name
  194.      * @param password the corresponding password
  195.      * @return True for successful login, false for a failure
  196.      * @throws IOException on error
  197.      */
  198.     public boolean authenticate(final String user, final String password) throws IOException {
  199.         int replyCode = authinfoUser(user);

  201.         if (replyCode == NNTPReply.MORE_AUTH_INFO_REQUIRED) {
  202.             replyCode = authinfoPass(password);

  204.             if (replyCode == NNTPReply.AUTHENTICATION_ACCEPTED) {
  205.                 this._isAllowedToPost = true;
  206.                 return true;
  207.             }
  208.         }
  209.         return false;
  210.     }

  212.     /**
  213.      * There are a few NNTPClient methods that do not complete the entire sequence of NNTP commands to complete a transaction. These commands require some
  214.      * action by the programmer after the reception of a positive preliminary command. After the programmer's code completes its actions, it must call this
  215.      * method to receive the completion reply from the server and verify the success of the entire transaction.
  216.      * <p>
  217.      * For example
  218.      * </p>
  219.      * <pre>
  220.      * writer = client.postArticle();
  221.      * if (writer == null) // failure
  222.      *     return false;
  223.      * header = new SimpleNNTPHeader("foobar@foo.com", "Just testing");
  224.      * header.addNewsgroup("alt.test");
  225.      * writer.write(header.toString());
  226.      * writer.write("This is just a test");
  227.      * writer.close();
  228.      * if (!client.completePendingCommand()) // failure
  229.      *     return false;
  230.      * </pre>
  231.      *
  232.      * @return True if successfully completed, false if not.
  233.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  234.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  235.      *                                       independently as itself.
  236.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  237.      */
  238.     public boolean completePendingCommand() throws IOException {
  239.         return NNTPReply.isPositiveCompletion(getReply());
  240.     }

  242.     public Writer forwardArticle(final String articleId) throws IOException {
  243.         if (!NNTPReply.isPositiveIntermediate(ihave(articleId))) {
  244.             return null;
  245.         }

  247.         return new DotTerminatedMessageWriter(_writer_);
  248.     }

  250.     /**
  251.      * Return article headers for all articles between lowArticleNumber and highArticleNumber, inclusively, using the XOVER command.
  252.      *
  253.      * @param lowArticleNumber  low
  254.      * @param highArticleNumber high
  255.      * @return an Iterable of Articles
  256.      * @throws IOException if the command failed
  257.      * @since 3.0
  258.      */
  259.     public Iterable<Article> iterateArticleInfo(final long lowArticleNumber, final long highArticleNumber) throws IOException {
  260.         final BufferedReader info = retrieveArticleInfo(lowArticleNumber, highArticleNumber);
  261.         if (info == null) {
  262.             throw new IOException("XOVER command failed: " + getReplyString());
  263.         }
  264.         // N.B. info is already DotTerminated, so don't rewrap
  265.         return new ArticleIterator(new ReplyIterator(info, false));
  266.     }

  268.     /**
  269.      * List all new articles added to the NNTP server since a particular date subject to the conditions of the specified query. If no new news is found,
  270.      * 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.
  271.      * Each String which is returned is a unique message identifier including the enclosing &lt; and &gt;.
  272.      *
  273.      * @param query The query restricting how to search for new news. You must add at least one newsgroup to the query.
  274.      * @return 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,
  275.      *         no strings will be returned.
  276.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  277.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  278.      *                                       independently as itself.
  279.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  280.      * @since 3.0
  281.      */
  282.     public Iterable<String> iterateNewNews(final NewGroupsOrNewsQuery query) throws IOException {
  283.         if (NNTPReply.isPositiveCompletion(newnews(query.getNewsgroups(), query.getDate(), query.getTime(), query.isGMT(), query.getDistributions()))) {
  284.             return new ReplyIterator(_reader_);
  285.         }
  286.         throw new IOException("NEWNEWS command failed: " + getReplyString());
  287.     }

  289.     /**
  290.      * 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
  291.      * added, no entries will be returned. This uses the "NEWGROUPS" command.
  292.      *
  293.      * @param query The query restricting how to search for new newsgroups.
  294.      * @return An iterable of Strings containing the raw information for each new newsgroup added to the NNTP server. If no newsgroups were added, no entries
  295.      *         will be returned.
  296.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  297.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  298.      *                                       independently as itself.
  299.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  300.      * @since 3.0
  301.      */
  302.     public Iterable<String> iterateNewNewsgroupListing(final NewGroupsOrNewsQuery query) throws IOException {
  303.         if (NNTPReply.isPositiveCompletion(newgroups(query.getDate(), query.getTime(), query.isGMT(), query.getDistributions()))) {
  304.             return new ReplyIterator(_reader_);
  305.         }
  306.         throw new IOException("NEWGROUPS command failed: " + getReplyString());
  307.     }

  309.     /**
  310.      * 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
  311.      * added, no entries will be returned. This uses the "NEWGROUPS" command.
  312.      *
  313.      * @param query The query restricting how to search for new newsgroups.
  314.      * @return An iterable of NewsgroupInfo instances containing the information for each new newsgroup added to the NNTP server. If no newsgroups were added,
  315.      *         no entries will be returned.
  316.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  317.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  318.      *                                       independently as itself.
  319.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  320.      * @since 3.0
  321.      */
  322.     public Iterable<NewsgroupInfo> iterateNewNewsgroups(final NewGroupsOrNewsQuery query) throws IOException {
  323.         return new NewsgroupIterator(iterateNewNewsgroupListing(query));
  324.     }

  326.     /**
  327.      * List all newsgroups served by the NNTP server. If no newsgroups are served, no entries will be returned. The method uses the "LIST" command.
  328.      *
  329.      * @return An iterable of NewsgroupInfo instances containing the information for each newsgroup served by the NNTP server. If no newsgroups are served, no
  330.      *         entries will be returned.
  331.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  332.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  333.      *                                       independently as itself.
  334.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  335.      * @since 3.0
  336.      */
  337.     public Iterable<String> iterateNewsgroupListing() throws IOException {
  338.         if (NNTPReply.isPositiveCompletion(list())) {
  339.             return new ReplyIterator(_reader_);
  340.         }
  341.         throw new IOException("LIST command failed: " + getReplyString());
  342.     }

  344.     /**
  345.      * List the newsgroups that match a given pattern. Uses the "LIST ACTIVE" command.
  346.      *
  347.      * @param wildmat a pseudo-regex pattern (cf. RFC 2980)
  348.      * @return An iterable of Strings containing the raw information for each newsgroup served by the NNTP server corresponding to the supplied pattern. If no
  349.      *         such newsgroups are served, no entries will be returned.
  350.      * @throws IOException on error
  351.      * @since 3.0
  352.      */
  353.     public Iterable<String> iterateNewsgroupListing(final String wildmat) throws IOException {
  354.         if (NNTPReply.isPositiveCompletion(listActive(wildmat))) {
  355.             return new ReplyIterator(_reader_);
  356.         }
  357.         throw new IOException("LIST ACTIVE " + wildmat + " command failed: " + getReplyString());
  358.     }

  360.     /**
  361.      * List all newsgroups served by the NNTP server. If no newsgroups are served, no entries will be returned. The method uses the "LIST" command.
  362.      *
  363.      * @return An iterable of Strings containing the raw information for each newsgroup served by the NNTP server. If no newsgroups are served, no entries will
  364.      *         be returned.
  365.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  366.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  367.      *                                       independently as itself.
  368.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  369.      * @since 3.0
  370.      */
  371.     public Iterable<NewsgroupInfo> iterateNewsgroups() throws IOException {
  372.         return new NewsgroupIterator(iterateNewsgroupListing());
  373.     }

  375.     /**
  376.      * List the newsgroups that match a given pattern. Uses the "LIST ACTIVE" command.
  377.      *
  378.      * @param wildmat a pseudo-regex pattern (cf. RFC 2980)
  379.      * @return An iterable NewsgroupInfo instances containing the information for each newsgroup served by the NNTP server corresponding to the supplied
  380.      *         pattern. If no such newsgroups are served, no entries will be returned.
  381.      * @throws IOException on error
  382.      * @since 3.0
  383.      */
  384.     public Iterable<NewsgroupInfo> iterateNewsgroups(final String wildmat) throws IOException {
  385.         return new NewsgroupIterator(iterateNewsgroupListing(wildmat));
  386.     }

  388.     /**
  389.      * List the command help from the server.
  390.      *
  391.      * @return The sever help information.
  392.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  393.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  394.      *                                       independently as itself.
  395.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  396.      */
  397.     public String listHelp() throws IOException {
  398.         if (!NNTPReply.isInformational(help())) {
  399.             return null;
  400.         }

  402.         try (final StringWriter help = new StringWriter(); final BufferedReader reader = new DotTerminatedMessageReader(_reader_)) {
  403.             Util.copyReader(reader, help);
  404.             return help.toString();
  405.         }
  406.     }

  408.     /**
  409.      * List all new articles added to the NNTP server since a particular date subject to the conditions of the specified query. If no new news is found, a
  410.      * 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
  411.      * fail. Each String in the returned array is a unique message identifier including the enclosing &lt; and &gt;. This uses the "NEWNEWS" command.
  412.      *
  413.      * @param query The query restricting how to search for new news. You must add at least one newsgroup to the query.
  414.      * @return 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
  415.      *         zero length array will be returned. If the command fails, null will be returned.
  416.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  417.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  418.      *                                       independently as itself.
  419.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  420.      *
  421.      * @see #iterateNewNews(NewGroupsOrNewsQuery)
  422.      */
  423.     public String[] listNewNews(final NewGroupsOrNewsQuery query) throws IOException {
  424.         if (!NNTPReply.isPositiveCompletion(newnews(query.getNewsgroups(), query.getDate(), query.getTime(), query.isGMT(), query.getDistributions()))) {
  425.             return null;
  426.         }

  428.         final Vector<String> list = new Vector<>();
  429.         try (final BufferedReader reader = new DotTerminatedMessageReader(_reader_)) {

  431.             String line;
  432.             while ((line = reader.readLine()) != null) {
  433.                 list.addElement(line);
  434.             }
  435.         }

  437.         final int size = list.size();
  438.         if (size < 1) {
  439.             return NetConstants.EMPTY_STRING_ARRAY;
  440.         }

  442.         final String[] result = new String[size];
  443.         list.copyInto(result);

  445.         return result;
  446.     }

  448.     /**
  449.      * 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
  450.      * added, a zero length array will be returned. If the command fails, null will be returned. This uses the "NEWGROUPS" command.
  451.      *
  452.      * @param query The query restricting how to search for new newsgroups.
  453.      * @return An array of NewsgroupInfo instances containing the information for each new newsgroup added to the NNTP server. If no newsgroups were added, a
  454.      *         zero length array will be returned. If the command fails, null will be returned.
  455.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  456.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  457.      *                                       independently as itself.
  458.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  459.      * @see #iterateNewNewsgroups(NewGroupsOrNewsQuery)
  460.      * @see #iterateNewNewsgroupListing(NewGroupsOrNewsQuery)
  461.      */
  462.     public NewsgroupInfo[] listNewNewsgroups(final NewGroupsOrNewsQuery query) throws IOException {
  463.         if (!NNTPReply.isPositiveCompletion(newgroups(query.getDate(), query.getTime(), query.isGMT(), query.getDistributions()))) {
  464.             return null;
  465.         }

  467.         return readNewsgroupListing();
  468.     }

  470.     /**
  471.      * 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
  472.      * returned. The method uses the "LIST" command.
  473.      *
  474.      * @return An array of NewsgroupInfo instances containing the information for each newsgroup served by the NNTP server. If no newsgroups are served, a zero
  475.      *         length array will be returned. If the command fails, null will be returned.
  476.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  477.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  478.      *                                       independently as itself.
  479.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  480.      * @see #iterateNewsgroupListing()
  481.      * @see #iterateNewsgroups()
  482.      */
  483.     public NewsgroupInfo[] listNewsgroups() throws IOException {
  484.         if (!NNTPReply.isPositiveCompletion(list())) {
  485.             return null;
  486.         }

  488.         return readNewsgroupListing();
  489.     }

  491.     /**
  492.      * List the newsgroups that match a given pattern. Uses the "LIST ACTIVE" command.
  493.      *
  494.      * @param wildmat a pseudo-regex pattern (cf. RFC 2980)
  495.      * @return An array of NewsgroupInfo instances containing the information for each newsgroup served by the NNTP server corresponding to the supplied
  496.      *         pattern. If no such newsgroups are served, a zero length array will be returned. If the command fails, null will be returned.
  497.      * @throws IOException on error
  498.      * @see #iterateNewsgroupListing(String)
  499.      * @see #iterateNewsgroups(String)
  500.      */
  501.     public NewsgroupInfo[] listNewsgroups(final String wildmat) throws IOException {
  502.         if (!NNTPReply.isPositiveCompletion(listActive(wildmat))) {
  503.             return null;
  504.         }
  505.         return readNewsgroupListing();
  506.     }

  508.     /**
  509.      * Send a "LIST OVERVIEW.FMT" command to the server.
  510.      *
  511.      * @return the contents of the Overview format, of {@code null} if the command failed
  512.      * @throws IOException on error
  513.      */
  514.     public String[] listOverviewFmt() throws IOException {
  515.         if (!NNTPReply.isPositiveCompletion(sendCommand("LIST", "OVERVIEW.FMT"))) {
  516.             return null;
  517.         }

  519.         try (final BufferedReader reader = new DotTerminatedMessageReader(_reader_)) {
  520.             String line;
  521.             final ArrayList<String> list = new ArrayList<>();
  522.             while ((line = reader.readLine()) != null) {
  523.                 list.add(line);
  524.             }
  525.             return list.toArray(NetConstants.EMPTY_STRING_ARRAY);
  526.         }
  527.     }

  529.     /**
  530.      * 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
  531.      * connection.
  532.      *
  533.      * @return True if successfully completed, false if not.
  534.      * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  535.      */
  536.     public boolean logout() throws IOException {
  537.         return NNTPReply.isPositiveCompletion(quit());
  538.     }

  540.     /**
  541.      * Parse the reply and store the id and number in the pointer.
  542.      *
  543.      * @param reply   the reply to parse "22n nnn <aaa>"
  544.      * @param pointer the pointer to update
  545.      *
  546.      * @throws MalformedServerReplyException if response could not be parsed
  547.      */
  548.     private void parseArticlePointer(final String reply, final ArticleInfo pointer) throws MalformedServerReplyException {
  549.         final String[] tokens = reply.split(" ");
  550.         if (tokens.length >= 3) { // OK, we can parset the line
  551.             int i = 1; // skip reply code
  552.             try {
  553.                 // Get article number
  554.                 pointer.articleNumber = Long.parseLong(tokens[i++]);
  555.                 // Get article id
  556.                 pointer.articleId = tokens[i++];
  557.                 return; // done
  558.             } catch (final NumberFormatException e) {
  559.                 // drop through and raise exception
  560.             }
  561.         }
  562.         throw new MalformedServerReplyException("Could not parse article pointer.\nServer reply: " + reply);
  563.     }

  565.     /**
  566.      * Post an article to the NNTP server. This method returns a DotTerminatedMessageWriter instance to which the article can be written. Null is returned if
  567.      * the posting attempt fails. You should check {@link NNTP#isAllowedToPost isAllowedToPost() } before trying to post. However, a posting attempt can fail
  568.      * due to malformed headers.
  569.      * <p>
  570.      * 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.
  571.      * The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore, the returned Writer actually writes directly to
  572.      * 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
  573.      * properly.
  574.      * </p>
  575.      * <p>
  576.      * Different NNTP servers will require different header formats, but you can use the provided {@link org.apache.commons.net.nntp.SimpleNNTPHeader} class to
  577.      * construct the bare minimum acceptable header for most newsreaders. To construct more complicated headers you should refer to RFC 822. When the Java Mail
  578.      * API is finalized, you will be able to use it to compose fully compliant Internet text messages. The DotTerminatedMessageWriter takes care of doubling
  579.      * 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.
  580.      * </p>
  581.      * <p>
  582.      * Upon closing the returned Writer, you need to call {@link #completePendingCommand completePendingCommand() } to finalize the posting and verify its
  583.      * success or failure from the server reply.
  584.      * </p>
  585.      *
  586.      * @return A DotTerminatedMessageWriter to which the article (including header) can be written. Returns null if the command fails.
  587.      * @throws IOException If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  588.      */

  590.     public Writer postArticle() throws IOException {
  591.         if (!NNTPReply.isPositiveIntermediate(post())) {
  592.             return null;
  593.         }

  595.         return new DotTerminatedMessageWriter(_writer_);
  596.     }

  598.     private NewsgroupInfo[] readNewsgroupListing() throws IOException {

  600.         // Start of with a big vector because we may be reading a very large
  601.         // amount of groups.
  602.         final Vector<NewsgroupInfo> list = new Vector<>(2048);

  604.         String line;
  605.         try (final BufferedReader reader = new DotTerminatedMessageReader(_reader_)) {
  606.             while ((line = reader.readLine()) != null) {
  607.                 final NewsgroupInfo tmp = parseNewsgroupListEntry(line);
  608.                 if (tmp == null) {
  609.                     throw new MalformedServerReplyException(line);
  610.                 }
  611.                 list.addElement(tmp);
  612.             }
  613.         }
  614.         final int size;
  615.         if ((size = list.size()) < 1) {
  616.             return EMPTY_NEWSGROUP_INFO_ARRAY;
  617.         }

  619.         final NewsgroupInfo[] info = new NewsgroupInfo[size];
  620.         list.copyInto(info);

  622.         return info;
  623.     }

  625.     private BufferedReader retrieve(final int command, final long articleNumber, final ArticleInfo pointer) throws IOException {
  626.         if (!NNTPReply.isPositiveCompletion(sendCommand(command, Long.toString(articleNumber)))) {
  627.             return null;
  628.         }

  630.         if (pointer != null) {
  631.             parseArticlePointer(getReplyString(), pointer);
  632.         }

  634.         return new DotTerminatedMessageReader(_reader_);
  635.     }

  637.     private BufferedReader retrieve(final int command, final String articleId, final ArticleInfo pointer) throws IOException {
  638.         if (articleId != null) {
  639.             if (!NNTPReply.isPositiveCompletion(sendCommand(command, articleId))) {
  640.                 return null;
  641.             }
  642.         } else if (!NNTPReply.isPositiveCompletion(sendCommand(command))) {
  643.             return null;
  644.         }

  646.         if (pointer != null) {
  647.             parseArticlePointer(getReplyString(), pointer);
  648.         }

  650.         return new DotTerminatedMessageReader(_reader_);
  651.     }

  653.     /**
  654.      * Same as <code>retrieveArticle((String) null)</code> Note: the return can be cast to a {@link BufferedReader}
  655.      *
  656.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  657.      * @throws IOException if an IO error occurs
  658.      */
  659.     public Reader retrieveArticle() throws IOException {
  660.         return retrieveArticle((String) null);
  661.     }

  663.     /**
  664.      * @param articleNumber The number of the article to retrieve
  665.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  666.      * @throws IOException on error
  667.      * @deprecated 3.0 use {@link #retrieveArticle(long)} instead
  668.      */
  669.     @Deprecated
  670.     public Reader retrieveArticle(final int articleNumber) throws IOException {
  671.         return retrieveArticle((long) articleNumber);
  672.     }

  674.     /**
  675.      * @param articleNumber The number of the article to retrieve.
  676.      * @param pointer       A parameter through which to return the article's number and unique id
  677.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  678.      * @throws IOException on error
  679.      * @deprecated 3.0 use {@link #retrieveArticle(long, ArticleInfo)} instead
  680.      */
  681.     @Deprecated
  682.     public Reader retrieveArticle(final int articleNumber, final ArticlePointer pointer) throws IOException {
  683.         final ArticleInfo ai = ap2ai(pointer);
  684.         final Reader rdr = retrieveArticle(articleNumber, ai);
  685.         ai2ap(ai, pointer);
  686.         return rdr;
  687.     }

  689.     /**
  690.      * Same as <code>retrieveArticle(articleNumber, null)</code>
  691.      *
  692.      * @param articleNumber the article number to fetch
  693.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  694.      * @throws IOException if an IO error occurs
  695.      */
  696.     public BufferedReader retrieveArticle(final long articleNumber) throws IOException {
  697.         return retrieveArticle(articleNumber, null);
  698.     }

  700.     /**
  701.      * Retrieves an article from the currently selected newsgroup. The article is referenced by its article number. The article number and identifier contained
  702.      * in the server reply are returned through an ArticleInfo. The <code>articleId</code> field of the ArticleInfo cannot always be trusted because some NNTP
  703.      * servers do not correctly follow the RFC 977 reply format.
  704.      * <p>
  705.      * A DotTerminatedMessageReader is returned from which the article can be read. If the article does not exist, null is returned.
  706.      * </p>
  707.      * <p>
  708.      * 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
  709.      * instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore, the returned BufferedReader actually
  710.      * 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
  711.      * follow these requirements, your program will not work properly.
  712.      * </p>
  713.      *
  714.      * @param articleNumber The number of the article to retrieve.
  715.      * @param pointer       A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of
  716.      *                      server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned
  717.      *                      article information.
  718.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  719.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  720.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  721.      *                                       independently as itself.
  722.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  723.      */
  724.     public BufferedReader retrieveArticle(final long articleNumber, final ArticleInfo pointer) throws IOException {
  725.         return retrieve(NNTPCommand.ARTICLE, articleNumber, pointer);
  726.     }

  728.     /**
  729.      * Same as <code>retrieveArticle(articleId, (ArticleInfo) null)</code> Note: the return can be cast to a {@link BufferedReader}
  730.      *
  731.      * @param articleId the article id to retrieve
  732.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  733.      * @throws IOException if an IO error occurs
  734.      */
  735.     public Reader retrieveArticle(final String articleId) throws IOException {
  736.         return retrieveArticle(articleId, (ArticleInfo) null);
  737.     }

  739.     /**
  740.      * Retrieves an article from the NNTP server. The article is referenced by its unique article identifier (including the enclosing &lt; and &gt;). The
  741.      * article number and identifier contained in the server reply are returned through an ArticleInfo. The <code>articleId</code> field of the ArticleInfo
  742.      * cannot always be trusted because some NNTP servers do not correctly follow the RFC 977 reply format.
  743.      * <p>
  744.      * A DotTerminatedMessageReader is returned from which the article can be read. If the article does not exist, null is returned.
  745.      * </p>
  746.      * <p>
  747.      * 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
  748.      * instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore, the returned BufferedReader actually
  749.      * 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
  750.      * follow these requirements, your program will not work properly.
  751.      * </p>
  752.      *
  753.      * @param articleId The unique article identifier of the article to retrieve. If this parameter is null, the currently selected article is retrieved.
  754.      * @param pointer   A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server
  755.      *                  deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article
  756.      *                  information.
  757.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  758.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  759.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  760.      *                                       independently as itself.
  761.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  762.      */
  763.     public BufferedReader retrieveArticle(final String articleId, final ArticleInfo pointer) throws IOException {
  764.         return retrieve(NNTPCommand.ARTICLE, articleId, pointer);

  766.     }

  768.     /**
  769.      * @param articleId The unique article identifier of the article to retrieve
  770.      * @param pointer   A parameter through which to return the article's number and unique id
  771.      * @deprecated 3.0 use {@link #retrieveArticle(String, ArticleInfo)} instead
  772.      * @return A DotTerminatedMessageReader instance from which the article can be read. null if the article does not exist.
  773.      * @throws IOException on error
  774.      */
  775.     @Deprecated
  776.     public Reader retrieveArticle(final String articleId, final ArticlePointer pointer) throws IOException {
  777.         final ArticleInfo ai = ap2ai(pointer);
  778.         final Reader rdr = retrieveArticle(articleId, ai);
  779.         ai2ap(ai, pointer);
  780.         return rdr;
  781.     }

  783.     /**
  784.      * Same as <code>retrieveArticleBody(null)</code> Note: the return can be cast to a {@link BufferedReader}
  785.      *
  786.      * @return A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
  787.      * @throws IOException if an error occurs
  788.      */
  789.     public Reader retrieveArticleBody() throws IOException {
  790.         return retrieveArticleBody(null);
  791.     }

  793.     /**
  794.      * @param a tba
  795.      * @return tba
  796.      * @throws IOException tba
  797.      * @deprecated 3.0 use {@link #retrieveArticleBody(long)} instead
  798.      */
  799.     @Deprecated
  800.     public Reader retrieveArticleBody(final int a) throws IOException {
  801.         return retrieveArticleBody((long) a);
  802.     }

  804.     /**
  805.      * @param a  tba
  806.      * @param ap tba
  807.      * @return tba
  808.      * @throws IOException tba
  809.      * @deprecated 3.0 use {@link #retrieveArticleBody(long, ArticleInfo)} instead
  810.      */
  811.     @Deprecated
  812.     public Reader retrieveArticleBody(final int a, final ArticlePointer ap) throws IOException {
  813.         final ArticleInfo ai = ap2ai(ap);
  814.         final Reader rdr = retrieveArticleBody(a, ai);
  815.         ai2ap(ai, ap);
  816.         return rdr;
  817.     }

  819.     /**
  820.      * Same as <code>retrieveArticleBody(articleNumber, null)</code>
  821.      *
  822.      * @param articleNumber the article number
  823.      * @return the reader
  824.      * @throws IOException if an error occurs
  825.      */
  826.     public BufferedReader retrieveArticleBody(final long articleNumber) throws IOException {
  827.         return retrieveArticleBody(articleNumber, null);
  828.     }

  830.     /**
  831.      * Retrieves an article body from the currently selected newsgroup. The article is referenced by its article number. The article number and identifier
  832.      * contained in the server reply are returned through an ArticleInfo. The <code>articleId</code> field of the ArticleInfo cannot always be trusted because
  833.      * some NNTP servers do not correctly follow the RFC 977 reply format.
  834.      * <p>
  835.      * A DotTerminatedMessageReader is returned from which the article can be read. If the article does not exist, null is returned.
  836.      * </p>
  837.      * <p>
  838.      * 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
  839.      * instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore, the returned BufferedReader actually
  840.      * 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
  841.      * follow these requirements, your program will not work properly.
  842.      * </p>
  843.      *
  844.      * @param articleNumber The number of the article whose body is being retrieved.
  845.      * @param pointer       A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of
  846.      *                      server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned
  847.      *                      article information.
  848.      * @return A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
  849.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  850.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  851.      *                                       independently as itself.
  852.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  853.      */
  854.     public BufferedReader retrieveArticleBody(final long articleNumber, final ArticleInfo pointer) throws IOException {
  855.         return retrieve(NNTPCommand.BODY, articleNumber, pointer);
  856.     }

  858.     /**
  859.      * Same as <code>retrieveArticleBody(articleId, (ArticleInfo) null)</code> Note: the return can be cast to a {@link BufferedReader}
  860.      *
  861.      * @param articleId the article id
  862.      * @return A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
  863.      * @throws IOException if an error occurs
  864.      */
  865.     public Reader retrieveArticleBody(final String articleId) throws IOException {
  866.         return retrieveArticleBody(articleId, (ArticleInfo) null);
  867.     }

  869.     /**
  870.      * Retrieves an article body from the NNTP server. The article is referenced by its unique article identifier (including the enclosing &lt; and &gt;). The
  871.      * article number and identifier contained in the server reply are returned through an ArticleInfo. The <code>articleId</code> field of the ArticleInfo
  872.      * cannot always be trusted because some NNTP servers do not correctly follow the RFC 977 reply format.
  873.      * <p>
  874.      * A DotTerminatedMessageReader is returned from which the article can be read. If the article does not exist, null is returned.
  875.      * </p>
  876.      * <p>
  877.      * 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
  878.      * instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore, the returned BufferedReader actually
  879.      * 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
  880.      * follow these requirements, your program will not work properly.
  881.      * </p>
  882.      *
  883.      * @param articleId The unique article identifier of the article whose body is being retrieved. If this parameter is null, the body of the currently
  884.      *                  selected article is retrieved.
  885.      * @param pointer   A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server
  886.      *                  deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article
  887.      *                  information.
  888.      * @return A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
  889.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  890.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  891.      *                                       independently as itself.
  892.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  893.      */
  894.     public BufferedReader retrieveArticleBody(final String articleId, final ArticleInfo pointer) throws IOException {
  895.         return retrieve(NNTPCommand.BODY, articleId, pointer);

  897.     }

  899.     /**
  900.      * @param articleId The unique article identifier of the article to retrieve
  901.      * @param pointer   A parameter through which to return the article's number and unique id
  902.      * @return A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
  903.      * @throws IOException on error
  904.      * @deprecated 3.0 use {@link #retrieveArticleBody(String, ArticleInfo)} instead
  905.      */
  906.     @Deprecated
  907.     public Reader retrieveArticleBody(final String articleId, final ArticlePointer pointer) throws IOException {
  908.         final ArticleInfo ai = ap2ai(pointer);
  909.         final Reader rdr = retrieveArticleBody(articleId, ai);
  910.         ai2ap(ai, pointer);
  911.         return rdr;
  912.     }

  914.     /**
  915.      * Same as <code>retrieveArticleHeader((String) null)</code> Note: the return can be cast to a {@link BufferedReader}
  916.      *
  917.      * @return the reader
  918.      * @throws IOException if an error occurs
  919.      */
  920.     public Reader retrieveArticleHeader() throws IOException {
  921.         return retrieveArticleHeader((String) null);
  922.     }

  924.     /**
  925.      * @param a tba
  926.      * @return tba
  927.      * @throws IOException tba
  928.      * @deprecated 3.0 use {@link #retrieveArticleHeader(long)} instead
  929.      */
  930.     @Deprecated
  931.     public Reader retrieveArticleHeader(final int a) throws IOException {
  932.         return retrieveArticleHeader((long) a);
  933.     }

  935.     /**
  936.      * @param a  tba
  937.      * @param ap tba
  938.      * @return tba
  939.      * @throws IOException tba
  940.      * @deprecated 3.0 use {@link #retrieveArticleHeader(long, ArticleInfo)} instead
  941.      */
  942.     @Deprecated
  943.     public Reader retrieveArticleHeader(final int a, final ArticlePointer ap) throws IOException {
  944.         final ArticleInfo ai = ap2ai(ap);
  945.         final Reader rdr = retrieveArticleHeader(a, ai);
  946.         ai2ap(ai, ap);
  947.         return rdr;
  948.     }

  950.     /**
  951.      * Same as <code>retrieveArticleHeader(articleNumber, null)</code>
  952.      *
  953.      * @param articleNumber the article number
  954.      * @return the reader
  955.      * @throws IOException if an error occurs
  956.      */
  957.     public BufferedReader retrieveArticleHeader(final long articleNumber) throws IOException {
  958.         return retrieveArticleHeader(articleNumber, null);
  959.     }

  961.     /**
  962.      * Retrieves an article header from the currently selected newsgroup. The article is referenced by its article number. The article number and identifier
  963.      * contained in the server reply are returned through an ArticleInfo. The <code>articleId</code> field of the ArticleInfo cannot always be trusted because
  964.      * some NNTP servers do not correctly follow the RFC 977 reply format.
  965.      * <p>
  966.      * A DotTerminatedMessageReader is returned from which the article can be read. If the article does not exist, null is returned.
  967.      * </p>
  968.      * <p>
  969.      * 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
  970.      * instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore, the returned BufferedReader actually
  971.      * 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
  972.      * follow these requirements, your program will not work properly.
  973.      * </p>
  974.      *
  975.      * @param articleNumber The number of the article whose header is being retrieved.
  976.      * @param pointer       A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of
  977.      *                      server deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned
  978.      *                      article information.
  979.      * @return A DotTerminatedMessageReader instance from which the article header can be read. null if the article does not exist.
  980.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  981.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  982.      *                                       independently as itself.
  983.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  984.      */
  985.     public BufferedReader retrieveArticleHeader(final long articleNumber, final ArticleInfo pointer) throws IOException {
  986.         return retrieve(NNTPCommand.HEAD, articleNumber, pointer);
  987.     }

  989.     /**
  990.      * Same as <code>retrieveArticleHeader(articleId, (ArticleInfo) null)</code> Note: the return can be cast to a {@link BufferedReader}
  991.      *
  992.      * @param articleId the article id to fetch
  993.      * @return the reader
  994.      * @throws IOException if an error occurs
  995.      */
  996.     public Reader retrieveArticleHeader(final String articleId) throws IOException {
  997.         return retrieveArticleHeader(articleId, (ArticleInfo) null);
  998.     }

  1000.     /**
  1001.      * Retrieves an article header from the NNTP server. The article is referenced by its unique article identifier (including the enclosing &lt; and &gt;). The
  1002.      * article number and identifier contained in the server reply are returned through an ArticleInfo. The <code>articleId</code> field of the ArticleInfo
  1003.      * cannot always be trusted because some NNTP servers do not correctly follow the RFC 977 reply format.
  1004.      * <p>
  1005.      * A DotTerminatedMessageReader is returned from which the article can be read. If the article does not exist, null is returned.
  1006.      * </p>
  1007.      * <p>
  1008.      * 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
  1009.      * instance. The NNTP protocol uses the same stream for issuing commands as it does for returning results. Therefore, the returned BufferedReader actually
  1010.      * 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
  1011.      * follow these requirements, your program will not work properly.
  1012.      * </p>
  1013.      *
  1014.      * @param articleId The unique article identifier of the article whose header is being retrieved. If this parameter is null, the header of the currently
  1015.      *                  selected article is retrieved.
  1016.      * @param pointer   A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server
  1017.      *                  deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article
  1018.      *                  information.
  1019.      * @return A DotTerminatedMessageReader instance from which the article header can be read. null if the article does not exist.
  1020.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  1021.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  1022.      *                                       independently as itself.
  1023.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  1024.      */
  1025.     public BufferedReader retrieveArticleHeader(final String articleId, final ArticleInfo pointer) throws IOException {
  1026.         return retrieve(NNTPCommand.HEAD, articleId, pointer);

  1028.     }

  1030.     /**
  1031.      * @param articleId The unique article identifier of the article to retrieve
  1032.      * @param pointer   A parameter through which to return the article's number and unique id
  1033.      * @return A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
  1034.      * @throws IOException on error
  1035.      * @deprecated 3.0 use {@link #retrieveArticleHeader(String, ArticleInfo)} instead
  1036.      */
  1037.     @Deprecated
  1038.     public Reader retrieveArticleHeader(final String articleId, final ArticlePointer pointer) throws IOException {
  1039.         final ArticleInfo ai = ap2ai(pointer);
  1040.         final Reader rdr = retrieveArticleHeader(articleId, ai);
  1041.         ai2ap(ai, pointer);
  1042.         return rdr;
  1043.     }

  1045.     /**
  1046.      * @param lowArticleNumber to fetch
  1047.      * @return a DotTerminatedReader if successful, null otherwise
  1048.      * @throws IOException tba
  1049.      * @deprecated 3.0 use {@link #retrieveArticleInfo(long)} instead
  1050.      */
  1051.     @Deprecated
  1052.     public Reader retrieveArticleInfo(final int lowArticleNumber) throws IOException {
  1053.         return retrieveArticleInfo((long) lowArticleNumber);
  1054.     }

  1056.     /**
  1057.      * @param lowArticleNumber  to fetch
  1058.      * @param highArticleNumber to fetch
  1059.      * @return a DotTerminatedReader if successful, null otherwise
  1060.      * @throws IOException on error
  1061.      * @deprecated 3.0 use {@link #retrieveArticleInfo(long, long)} instead
  1062.      */
  1063.     @Deprecated
  1064.     public Reader retrieveArticleInfo(final int lowArticleNumber, final int highArticleNumber) throws IOException {
  1065.         return retrieveArticleInfo((long) lowArticleNumber, (long) highArticleNumber);
  1066.     }

  1068.     /**
  1069.      * Return article headers for a specified post.
  1070.      *
  1071.      * @param articleNumber the article to retrieve headers for
  1072.      * @return a DotTerminatedReader if successful, null otherwise
  1073.      * @throws IOException on error
  1074.      */
  1075.     public BufferedReader retrieveArticleInfo(final long articleNumber) throws IOException {
  1076.         return retrieveArticleInfo(Long.toString(articleNumber));
  1077.     }

  1079.     /**
  1080.      * Return article headers for all articles between lowArticleNumber and highArticleNumber, inclusively. Uses the XOVER command.
  1081.      *
  1082.      * @param lowArticleNumber  low number
  1083.      * @param highArticleNumber high number
  1084.      * @return a DotTerminatedReader if successful, null otherwise
  1085.      * @throws IOException on error
  1086.      */
  1087.     public BufferedReader retrieveArticleInfo(final long lowArticleNumber, final long highArticleNumber) throws IOException {
  1088.         return retrieveArticleInfo(lowArticleNumber + "-" + highArticleNumber);
  1089.     }

  1091.     /**
  1092.      * Private implementation of XOVER functionality.
  1093.      *
  1094.      * See {@link NNTP#xover} for legal agument formats. Alternatively, read RFC 2980 :-)
  1095.      *
  1096.      * @param articleRange
  1097.      * @return Returns a DotTerminatedMessageReader if successful, null otherwise
  1098.      * @throws IOException
  1099.      */
  1100.     private BufferedReader retrieveArticleInfo(final String articleRange) throws IOException {
  1101.         if (!NNTPReply.isPositiveCompletion(xover(articleRange))) {
  1102.             return null;
  1103.         }

  1105.         return new DotTerminatedMessageReader(_reader_);
  1106.     }

  1108.     /**
  1109.      * @param a tba
  1110.      * @param b tba
  1111.      * @return tba
  1112.      * @throws IOException tba
  1113.      * @deprecated 3.0 use {@link #retrieveHeader(String, long)} instead
  1114.      */
  1115.     @Deprecated
  1116.     public Reader retrieveHeader(final String a, final int b) throws IOException {
  1117.         return retrieveHeader(a, (long) b);
  1118.     }

  1120.     /**
  1121.      * @param header            the header
  1122.      * @param lowArticleNumber  to fetch
  1123.      * @param highArticleNumber to fetch
  1124.      * @return a DotTerminatedReader if successful, null otherwise
  1125.      * @throws IOException on error
  1126.      * @deprecated 3.0 use {@link #retrieveHeader(String, long, long)} instead
  1127.      */
  1128.     @Deprecated
  1129.     public Reader retrieveHeader(final String header, final int lowArticleNumber, final int highArticleNumber) throws IOException {
  1130.         return retrieveHeader(header, (long) lowArticleNumber, (long) highArticleNumber);
  1131.     }

  1133.     /**
  1134.      * Return an article header for a specified post.
  1135.      *
  1136.      * @param header        the header to retrieve
  1137.      * @param articleNumber the article to retrieve the header for
  1138.      * @return a DotTerminatedReader if successful, null otherwise
  1139.      * @throws IOException on error
  1140.      */
  1141.     public BufferedReader retrieveHeader(final String header, final long articleNumber) throws IOException {
  1142.         return retrieveHeader(header, Long.toString(articleNumber));
  1143.     }

  1145.     /**
  1146.      * Return an article header for all articles between lowArticleNumber and highArticleNumber, inclusively.
  1147.      *
  1148.      * @param header            the header
  1149.      * @param lowArticleNumber  to fetch
  1150.      * @param highArticleNumber to fetch
  1151.      * @return a DotTerminatedReader if successful, null otherwise
  1152.      * @throws IOException on error
  1153.      */
  1154.     public BufferedReader retrieveHeader(final String header, final long lowArticleNumber, final long highArticleNumber) throws IOException {
  1155.         return retrieveHeader(header, lowArticleNumber + "-" + highArticleNumber);
  1156.     }

  1158.     /**
  1159.      * Private implementation of XHDR functionality.
  1160.      * <p>
  1161.      * See {@link NNTP#xhdr} for legal argument formats. Alternatively, read RFC 1036.
  1162.      * </p>
  1163.      *
  1164.      * @param header
  1165.      * @param articleRange
  1166.      * @return Returns a {@link DotTerminatedMessageReader} if successful, {@code null} otherwise
  1167.      * @throws IOException
  1168.      */
  1169.     private BufferedReader retrieveHeader(final String header, final String articleRange) throws IOException {
  1170.         if (!NNTPReply.isPositiveCompletion(xhdr(header, articleRange))) {
  1171.             return null;
  1172.         }

  1174.         return new DotTerminatedMessageReader(_reader_);
  1175.     }

  1177.     /**
  1178.      * Same as <code>selectArticle((String) null, articleId)</code>. Useful for retrieving the current article number.
  1179.      *
  1180.      * @param pointer to the article
  1181.      * @return true if OK
  1182.      * @throws IOException on error
  1183.      */
  1184.     public boolean selectArticle(final ArticleInfo pointer) throws IOException {
  1185.         return selectArticle(null, pointer);
  1186.     }

  1188.     /**
  1189.      * @param pointer A parameter through which to return the article's number and unique id
  1190.      * @return True if successful, false if not.
  1191.      * @throws IOException on error
  1192.      * @deprecated 3.0 use {@link #selectArticle(ArticleInfo)} instead
  1193.      */
  1194.     @Deprecated
  1195.     public boolean selectArticle(final ArticlePointer pointer) throws IOException {
  1196.         final ArticleInfo ai = ap2ai(pointer);
  1197.         final boolean b = selectArticle(ai);
  1198.         ai2ap(ai, pointer);
  1199.         return b;

  1201.     }

  1203.     /**
  1204.      * @param a tba
  1205.      * @return tba
  1206.      * @throws IOException tba
  1207.      * @deprecated 3.0 use {@link #selectArticle(long)} instead
  1208.      */
  1209.     @Deprecated
  1210.     public boolean selectArticle(final int a) throws IOException {
  1211.         return selectArticle((long) a);
  1212.     }

  1214.     /**
  1215.      * @param a  tba
  1216.      * @param ap tba
  1217.      * @return tba
  1218.      * @throws IOException tba
  1219.      * @deprecated 3.0 use {@link #selectArticle(long, ArticleInfo)} instead
  1220.      */
  1221.     @Deprecated
  1222.     public boolean selectArticle(final int a, final ArticlePointer ap) throws IOException {
  1223.         final ArticleInfo ai = ap2ai(ap);
  1224.         final boolean b = selectArticle(a, ai);
  1225.         ai2ap(ai, ap);
  1226.         return b;
  1227.     }

  1229.     /**
  1230.      * Same as <code>selectArticle(articleNumber, null)</code>
  1231.      *
  1232.      * @param articleNumber the numger
  1233.      * @return true if successful
  1234.      * @throws IOException on error
  1235.      */
  1236.     public boolean selectArticle(final long articleNumber) throws IOException {
  1237.         return selectArticle(articleNumber, null);
  1238.     }

  1240.     /**
  1241.      * 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
  1242.      * 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
  1243.      * retrieving it, or to obtain an article's unique identifier given its number.
  1244.      *
  1245.      * @param articleNumber The number of the article to select from the currently selected newsgroup.
  1246.      * @param pointer       A parameter through which to return the article's number and unique id. Although the articleId field cannot always be trusted
  1247.      *                      because of server deviations from RFC 977 reply formats, we haven't found a server that misformats this information in response to
  1248.      *                      this particular command. You may set this parameter to null if you do not desire to retrieve the returned article information.
  1249.      * @return True if successful, false if not.
  1250.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  1251.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  1252.      *                                       independently as itself.
  1253.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  1254.      */
  1255.     public boolean selectArticle(final long articleNumber, final ArticleInfo pointer) throws IOException {
  1256.         if (!NNTPReply.isPositiveCompletion(stat(articleNumber))) {
  1257.             return false;
  1258.         }

  1260.         if (pointer != null) {
  1261.             parseArticlePointer(getReplyString(), pointer);
  1262.         }

  1264.         return true;
  1265.     }

  1267.     /**
  1268.      * Same as <code>selectArticle(articleId, (ArticleInfo) null)</code>
  1269.      *
  1270.      * @param articleId the article's Id
  1271.      * @return true if successful
  1272.      * @throws IOException on error
  1273.      */
  1274.     public boolean selectArticle(final String articleId) throws IOException {
  1275.         return selectArticle(articleId, (ArticleInfo) null);
  1276.     }

  1278.     /**
  1279.      * Select an article by its unique identifier (including enclosing &lt; and &gt;) and return its article number and id through the pointer parameter. This
  1280.      * 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
  1281.      * the article by its number.
  1282.      *
  1283.      * @param articleId The unique article identifier of the article that is being selectedd. If this parameter is null, the body of the current article is
  1284.      *                  selected
  1285.      * @param pointer   A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server
  1286.      *                  deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article
  1287.      *                  information.
  1288.      * @return True if successful, false if not.
  1289.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  1290.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  1291.      *                                       independently as itself.
  1292.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  1293.      */
  1294.     public boolean selectArticle(final String articleId, final ArticleInfo pointer) throws IOException {
  1295.         if (articleId != null) {
  1296.             if (!NNTPReply.isPositiveCompletion(stat(articleId))) {
  1297.                 return false;
  1298.             }
  1299.         } else if (!NNTPReply.isPositiveCompletion(stat())) {
  1300.             return false;
  1301.         }

  1303.         if (pointer != null) {
  1304.             parseArticlePointer(getReplyString(), pointer);
  1305.         }

  1307.         return true;
  1308.     }

  1310.     /**
  1311.      * @param articleId The unique article identifier of the article to retrieve
  1312.      * @param pointer   A parameter through which to return the article's number and unique id
  1313.      * @return A DotTerminatedMessageReader instance from which the article body can be read. null if the article does not exist.
  1314.      * @throws IOException on error
  1315.      * @deprecated 3.0 use {@link #selectArticle(String, ArticleInfo)} instead
  1316.      */
  1317.     @Deprecated
  1318.     public boolean selectArticle(final String articleId, final ArticlePointer pointer) throws IOException {
  1319.         final ArticleInfo ai = ap2ai(pointer);
  1320.         final boolean b = selectArticle(articleId, ai);
  1321.         ai2ap(ai, pointer);
  1322.         return b;

  1324.     }

  1326.     /**
  1327.      * Same as <code>selectNewsgroup(newsgroup, null)</code>
  1328.      *
  1329.      * @param newsgroup the newsgroup name
  1330.      * @return true if newsgroup exist and was selected
  1331.      * @throws IOException if an error occurs
  1332.      */
  1333.     public boolean selectNewsgroup(final String newsgroup) throws IOException {
  1334.         return selectNewsgroup(newsgroup, null);
  1335.     }

  1337.     /**
  1338.      * Select the specified newsgroup to be the target of for future article retrieval and posting operations. Also return the newsgroup information contained
  1339.      * in the server reply through the info parameter.
  1340.      *
  1341.      * @param newsgroup The newsgroup to select.
  1342.      * @param info      A parameter through which the newsgroup information of the selected newsgroup contained in the server reply is returned. Set this to
  1343.      *                  null if you do not desire this information.
  1344.      * @return True if the newsgroup exists and was selected, false otherwise.
  1345.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  1346.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  1347.      *                                       independently as itself.
  1348.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  1349.      */
  1350.     public boolean selectNewsgroup(final String newsgroup, final NewsgroupInfo info) throws IOException {
  1351.         if (!NNTPReply.isPositiveCompletion(group(newsgroup))) {
  1352.             return false;
  1353.         }

  1355.         if (info != null) {
  1356.             parseGroupReply(getReplyString(), info);
  1357.         }

  1359.         return true;
  1360.     }

  1362.     /**
  1363.      * Same as <code>selectNextArticle((ArticleInfo) null)</code>
  1364.      *
  1365.      * @return true if successful
  1366.      * @throws IOException on error
  1367.      */
  1368.     public boolean selectNextArticle() throws IOException {
  1369.         return selectNextArticle((ArticleInfo) null);
  1370.     }

  1372.     /**
  1373.      * Select the article following the currently selected article in the currently selected newsgroup and return its number and unique id through the pointer
  1374.      * parameter. Because of deviating server implementations, the articleId information cannot be trusted. To obtain the article identifier, issue a
  1375.      * <code>selectArticle(pointer.articleNumber, pointer)</code> immediately afterward.
  1376.      *
  1377.      * @param pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server
  1378.      *                deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article
  1379.      *                information.
  1380.      * @return True if successful, false if not (e.g., there is no following article).
  1381.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  1382.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  1383.      *                                       independently as itself.
  1384.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  1385.      */
  1386.     public boolean selectNextArticle(final ArticleInfo pointer) throws IOException {
  1387.         if (!NNTPReply.isPositiveCompletion(next())) {
  1388.             return false;
  1389.         }

  1391.         if (pointer != null) {
  1392.             parseArticlePointer(getReplyString(), pointer);
  1393.         }

  1395.         return true;
  1396.     }

  1398.     /**
  1399.      * @param pointer A parameter through which to return the article's number and unique id
  1400.      * @return True if successful, false if not.
  1401.      * @throws IOException on error
  1402.      * @deprecated 3.0 use {@link #selectNextArticle(ArticleInfo)} instead
  1403.      */
  1404.     @Deprecated
  1405.     public boolean selectNextArticle(final ArticlePointer pointer) throws IOException {
  1406.         final ArticleInfo ai = ap2ai(pointer);
  1407.         final boolean b = selectNextArticle(ai);
  1408.         ai2ap(ai, pointer);
  1409.         return b;

  1411.     }

  1413.     /**
  1414.      * Same as <code>selectPreviousArticle((ArticleInfo) null)</code>
  1415.      *
  1416.      * @return true if successful
  1417.      * @throws IOException on error
  1418.      */
  1419.     public boolean selectPreviousArticle() throws IOException {
  1420.         return selectPreviousArticle((ArticleInfo) null);
  1421.     }

  1423.     // Helper methods

  1425.     /**
  1426.      * Select the article preceding the currently selected article in the currently selected newsgroup and return its number and unique id through the pointer
  1427.      * parameter. Because of deviating server implementations, the articleId information cannot be trusted. To obtain the article identifier, issue a
  1428.      * <code>selectArticle(pointer.articleNumber, pointer)</code> immediately afterward.
  1429.      *
  1430.      * @param pointer A parameter through which to return the article's number and unique id. The articleId field cannot always be trusted because of server
  1431.      *                deviations from RFC 977 reply formats. You may set this parameter to null if you do not desire to retrieve the returned article
  1432.      *                information.
  1433.      * @return True if successful, false if not (e.g., there is no previous article).
  1434.      * @throws NNTPConnectionClosedException If the NNTP server prematurely closes the connection as a result of the client being idle or some other reason
  1435.      *                                       causing the server to send NNTP reply code 400. This exception may be caught either as an IOException or
  1436.      *                                       independently as itself.
  1437.      * @throws IOException                   If an I/O error occurs while either sending a command to the server or receiving a reply from the server.
  1438.      */
  1439.     public boolean selectPreviousArticle(final ArticleInfo pointer) throws IOException {
  1440.         if (!NNTPReply.isPositiveCompletion(last())) {
  1441.             return false;
  1442.         }

  1444.         if (pointer != null) {
  1445.             parseArticlePointer(getReplyString(), pointer);
  1446.         }

  1448.         return true;
  1449.     }

  1451.     /**
  1452.      * @param pointer A parameter through which to return the article's number and unique id
  1453.      * @return True if successful, false if not.
  1454.      * @throws IOException on error
  1455.      * @deprecated 3.0 use {@link #selectPreviousArticle(ArticleInfo)} instead
  1456.      */
  1457.     @Deprecated
  1458.     public boolean selectPreviousArticle(final ArticlePointer pointer) throws IOException {
  1459.         final ArticleInfo ai = ap2ai(pointer);
  1460.         final boolean b = selectPreviousArticle(ai);
  1461.         ai2ap(ai, pointer);
  1462.         return b;
  1463.     }
  1464. }
Created with JaCoCo 0.8.12.202403310830