Coverage report

  %line %branch
org.apache.commons.net.nntp.NNTP
0% 
0% 

 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.BufferedWriter;
 20  
 import java.io.IOException;
 21  
 import java.io.InputStreamReader;
 22  
 import java.io.OutputStreamWriter;
 23  
 import org.apache.commons.net.MalformedServerReplyException;
 24  
 import org.apache.commons.net.ProtocolCommandSupport;
 25  
 import org.apache.commons.net.ProtocolCommandListener;
 26  
 import org.apache.commons.net.SocketClient;
 27  
 
 28  
 /***
 29  
  * The NNTP class is not meant to be used by itself and is provided
 30  
  * only so that you may easily implement your own NNTP client if
 31  
  * you so desire.  If you have no need to perform your own implementation,
 32  
  * you should use {@link org.apache.commons.net.nntp.NNTPClient}.
 33  
  * The NNTP class is made public to provide access to various NNTP constants
 34  
  * and to make it easier for adventurous programmers (or those with special
 35  
  * needs) to interact with the NNTP protocol and implement their own clients.
 36  
  * A set of methods with names corresponding to the NNTP command names are
 37  
  * provided to facilitate this interaction.
 38  
  * <p>
 39  
  * You should keep in mind that the NNTP server may choose to prematurely
 40  
  * close a connection if the client has been idle for longer than a
 41  
  * given time period or if the server is being shutdown by the operator or
 42  
  * some other reason.  The NNTP class will detect a
 43  
  * premature NNTP server connection closing when it receives a
 44  
  * {@link org.apache.commons.net.nntp.NNTPReply#SERVICE_DISCONTINUED NNTPReply.SERVICE_DISCONTINUED }
 45  
  *  response to a command.
 46  
  * When that occurs, the NNTP class method encountering that reply will throw
 47  
  * an {@link org.apache.commons.net.nntp.NNTPConnectionClosedException}
 48  
  * .
 49  
  * <code>NNTPConectionClosedException</code>
 50  
  * is a subclass of <code> IOException </code> and therefore need not be
 51  
  * caught separately, but if you are going to catch it separately, its
 52  
  * catch block must appear before the more general <code> IOException </code>
 53  
  * catch block.  When you encounter an
 54  
  * {@link org.apache.commons.net.nntp.NNTPConnectionClosedException}
 55  
  * , you must disconnect the connection with
 56  
  * {@link #disconnect  disconnect() } to properly clean up the
 57  
  * system resources used by NNTP.  Before disconnecting, you may check the
 58  
  * last reply code and text with
 59  
  * {@link #getReplyCode  getReplyCode } and
 60  
  * {@link #getReplyString  getReplyString }.
 61  
  * <p>
 62  
  * Rather than list it separately for each method, we mention here that
 63  
  * every method communicating with the server and throwing an IOException
 64  
  * can also throw a
 65  
  * {@link org.apache.commons.net.MalformedServerReplyException}
 66  
  * , which is a subclass
 67  
  * of IOException.  A MalformedServerReplyException will be thrown when
 68  
  * the reply received from the server deviates enough from the protocol
 69  
  * specification that it cannot be interpreted in a useful manner despite
 70  
  * attempts to be as lenient as possible.
 71  
  * <p>
 72  
  * <p>
 73  
  * @author Daniel F. Savarese
 74  
  * @author Rory Winston
 75  
  * @author Ted Wise
 76  
  * @see NNTPClient
 77  
  * @see NNTPConnectionClosedException
 78  
  * @see org.apache.commons.net.MalformedServerReplyException
 79  
  ***/
 80  
 
 81  
 public class NNTP extends SocketClient
 82  
 {
 83  
     /*** The default NNTP port.  Its value is 119 according to RFC 977. ***/
 84  
     public static final int DEFAULT_PORT = 119;
 85  
 
 86  
     // We have to ensure that the protocol communication is in ASCII
 87  
     // but we use ISO-8859-1 just in case 8-bit characters cross
 88  
     // the wire.
 89  
     private static final String __DEFAULT_ENCODING = "ISO-8859-1";
 90  
 
 91  
     private StringBuffer __commandBuffer;
 92  
 
 93  
     boolean _isAllowedToPost;
 94  
     int _replyCode;
 95  
     String _replyString;
 96  
 
 97  
     /**
 98  
      * Wraps {@link SocketClient#_input_}
 99  
      * to communicate with server.  Initialized by {@link #_connectAction_}.
 100  
      * All server reads should be done through this variable.
 101  
      */
 102  
     protected BufferedReader _reader_;
 103  
 
 104  
     /**
 105  
      * Wraps {@link SocketClient#_output_}
 106  
      * to communicate with server.  Initialized by {@link #_connectAction_}.
 107  
      * All server reads should be done through this variable.
 108  
      */
 109  
     protected BufferedWriter _writer_;
 110  
 
 111  
     /***
 112  
      * A ProtocolCommandSupport object used to manage the registering of
 113  
      * ProtocolCommandListeners and te firing of ProtocolCommandEvents.
 114  
      ***/
 115  
     protected ProtocolCommandSupport _commandSupport_;
 116  
 
 117  
     /***
 118  
      * The default NNTP constructor.  Sets the default port to
 119  
      * <code>DEFAULT_PORT</code> and initializes internal data structures
 120  
      * for saving NNTP reply information.
 121  
      ***/
 122  
     public NNTP()
 123  0
     {
 124  0
         setDefaultPort(DEFAULT_PORT);
 125  0
         __commandBuffer = new StringBuffer();
 126  0
         _replyString = null;
 127  0
         _reader_ = null;
 128  0
         _writer_ = null;
 129  0
         _isAllowedToPost = false;
 130  0
         _commandSupport_ = new ProtocolCommandSupport(this);
 131  0
     }
 132  
 
 133  
     private void __getReply() throws IOException
 134  
     {
 135  0
         _replyString = _reader_.readLine();
 136  
 
 137  0
         if (_replyString == null)
 138  0
             throw new NNTPConnectionClosedException(
 139  
                 "Connection closed without indication.");
 140  
 
 141  
         // In case we run into an anomaly we don't want fatal index exceptions
 142  
         // to be thrown.
 143  0
         if (_replyString.length() < 3)
 144  0
             throw new MalformedServerReplyException(
 145  
                 "Truncated server reply: " + _replyString);
 146  
         try
 147  
         {
 148  0
             _replyCode = Integer.parseInt(_replyString.substring(0, 3));
 149  
         }
 150  0
         catch (NumberFormatException e)
 151  
         {
 152  0
             throw new MalformedServerReplyException(
 153  
                 "Could not parse response code.\nServer Reply: " + _replyString);
 154  0
         }
 155  
 
 156  0
         if (_commandSupport_.getListenerCount() > 0)
 157  0
             _commandSupport_.fireReplyReceived(_replyCode, _replyString +
 158  
                                                SocketClient.NETASCII_EOL);
 159  
 
 160  0
         if (_replyCode == NNTPReply.SERVICE_DISCONTINUED)
 161  0
             throw new NNTPConnectionClosedException(
 162  
                 "NNTP response 400 received.  Server closed connection.");
 163  0
     }
 164  
 
 165  
     /***
 166  
      * Initiates control connections and gets initial reply, determining
 167  
      * if the client is allowed to post to the server.  Initializes
 168  
      * {@link #_reader_} and {@link #_writer_} to wrap
 169  
      * {@link SocketClient#_input_} and {@link SocketClient#_output_}.
 170  
      ***/
 171  
     protected void _connectAction_() throws IOException
 172  
     {
 173  0
         super._connectAction_();
 174  0
         _reader_ =
 175  
             new BufferedReader(class="keyword">new InputStreamReader(_input_,
 176  
                                                      __DEFAULT_ENCODING));
 177  0
         _writer_ =
 178  
             new BufferedWriter(class="keyword">new OutputStreamWriter(_output_,
 179  
                                                       __DEFAULT_ENCODING));
 180  0
         __getReply();
 181  
 
 182  0
         _isAllowedToPost = (_replyCode == NNTPReply.SERVER_READY_POSTING_ALLOWED);
 183  0
     }
 184  
 
 185  
     /***
 186  
      * Adds a ProtocolCommandListener.  Delegates this task to
 187  
      * {@link #_commandSupport_  _commandSupport_ }.
 188  
      * <p>
 189  
      * @param listener  The ProtocolCommandListener to add.
 190  
      ***/
 191  
     public void addProtocolCommandListener(ProtocolCommandListener listener)
 192  
     {
 193  0
         _commandSupport_.addProtocolCommandListener(listener);
 194  0
     }
 195  
 
 196  
     /***
 197  
      * Removes a ProtocolCommandListener.  Delegates this task to
 198  
      * {@link #_commandSupport_  _commandSupport_ }.
 199  
      * <p>
 200  
      * @param listener  The ProtocolCommandListener to remove.
 201  
      ***/
 202  
     public void removeProtocolCommandListener(ProtocolCommandListener listener)
 203  
     {
 204  0
         _commandSupport_.removeProtocolCommandListener(listener);
 205  0
     }
 206  
 
 207  
     /***
 208  
      * Closes the connection to the NNTP server and sets to null
 209  
      * some internal data so that the memory may be reclaimed by the
 210  
      * garbage collector.  The reply text and code information from the
 211  
      * last command is voided so that the memory it used may be reclaimed.
 212  
      * <p>
 213  
      * @exception IOException If an error occurs while disconnecting.
 214  
      ***/
 215  
     public void disconnect() throws IOException
 216  
     {
 217  0
         super.disconnect();
 218  0
         _reader_ = null;
 219  0
         _writer_ = null;
 220  0
         _replyString = null;
 221  0
         _isAllowedToPost = false;
 222  0
     }
 223  
 
 224  
 
 225  
     /***
 226  
      * Indicates whether or not the client is allowed to post articles to
 227  
      * the server it is currently connected to.
 228  
      * <p>
 229  
      * @return True if the client can post articles to the server, false
 230  
      *         otherwise.
 231  
      ***/
 232  
     public boolean isAllowedToPost()
 233  
     {
 234  0
         return _isAllowedToPost;
 235  
     }
 236  
 
 237  
 
 238  
     /***
 239  
      * Sends an NNTP command to the server, waits for a reply and returns the
 240  
      * numerical response code.  After invocation, for more detailed
 241  
      * information, the actual reply text can be accessed by calling
 242  
      * {@link #getReplyString  getReplyString }.
 243  
      * <p>
 244  
      * @param command  The text representation of the  NNTP command to send.
 245  
      * @param args The arguments to the NNTP command.  If this parameter is
 246  
      *             set to null, then the command is sent with no argument.
 247  
      * @return The integer value of the NNTP reply code returned by the server
 248  
      *         in response to the command.
 249  
      * @exception NNTPConnectionClosedException
 250  
      *      If the NNTP server prematurely closes the connection as a result
 251  
      *      of the client being idle or some other reason causing the server
 252  
      *      to send NNTP reply code 400.  This exception may be caught either
 253  
      *      as an IOException or independently as itself.
 254  
      * @exception IOException  If an I/O error occurs while either sending the
 255  
      *      command or receiving the server reply.
 256  
      ***/
 257  
     public int sendCommand(String command, String args) throws IOException
 258  
     {
 259  
         String message;
 260  
 
 261  0
         __commandBuffer.setLength(0);
 262  0
         __commandBuffer.append(command);
 263  
 
 264  0
         if (args != null)
 265  
         {
 266  0
             __commandBuffer.append(' ');
 267  0
             __commandBuffer.append(args);
 268  
         }
 269  0
         __commandBuffer.append(SocketClient.NETASCII_EOL);
 270  
 
 271  0
         _writer_.write(message = __commandBuffer.toString());
 272  0
         _writer_.flush();
 273  
 
 274  0
         if (_commandSupport_.getListenerCount() > 0)
 275  0
             _commandSupport_.fireCommandSent(command, message);
 276  
 
 277  0
         __getReply();
 278  0
         return _replyCode;
 279  
     }
 280  
 
 281  
 
 282  
     /***
 283  
      * Sends an NNTP command to the server, waits for a reply and returns the
 284  
      * numerical response code.  After invocation, for more detailed
 285  
      * information, the actual reply text can be accessed by calling
 286  
      * {@link #getReplyString  getReplyString }.
 287  
      * <p>
 288  
      * @param command  The NNTPCommand constant corresponding to the NNTP command
 289  
      *                 to send.
 290  
      * @param args The arguments to the NNTP command.  If this parameter is
 291  
      *             set to null, then the command is sent with no argument.
 292  
      * @return The integer value of the NNTP reply code returned by the server
 293  
      *         in response to the command.
 294  
      *         in response to the command.
 295  
      * @exception NNTPConnectionClosedException
 296  
      *      If the NNTP server prematurely closes the connection as a result
 297  
      *      of the client being idle or some other reason causing the server
 298  
      *      to send NNTP reply code 400.  This exception may be caught either
 299  
      *      as an IOException or independently as itself.
 300  
      * @exception IOException  If an I/O error occurs while either sending the
 301  
      *      command or receiving the server reply.
 302  
      ***/
 303  
     public int sendCommand(class="keyword">int command, String args) throws IOException
 304  
     {
 305  0
         return sendCommand(NNTPCommand._commands[command], args);
 306  
     }
 307  
 
 308  
 
 309  
     /***
 310  
      * Sends an NNTP command with no arguments to the server, waits for a
 311  
      * reply and returns the numerical response code.  After invocation, for
 312  
      * more detailed information, the actual reply text can be accessed by
 313  
      * calling {@link #getReplyString  getReplyString }.
 314  
      * <p>
 315  
      * @param command  The text representation of the  NNTP command to send.
 316  
      * @return The integer value of the NNTP reply code returned by the server
 317  
      *         in response to the command.
 318  
      *         in response to the command.
 319  
      * @exception NNTPConnectionClosedException
 320  
      *      If the NNTP server prematurely closes the connection as a result
 321  
      *      of the client being idle or some other reason causing the server
 322  
      *      to send NNTP reply code 400.  This exception may be caught either
 323  
      *      as an IOException or independently as itself.
 324  
      * @exception IOException  If an I/O error occurs while either sending the
 325  
      *      command or receiving the server reply.
 326  
      ***/
 327  
     public int sendCommand(String command) throws IOException
 328  
     {
 329  0
         return sendCommand(command, null);
 330  
     }
 331  
 
 332  
 
 333  
     /***
 334  
      * Sends an NNTP command with no arguments to the server, waits for a
 335  
      * reply and returns the numerical response code.  After invocation, for
 336  
      * more detailed information, the actual reply text can be accessed by
 337  
      * calling {@link #getReplyString  getReplyString }.
 338  
      * <p>
 339  
      * @param command  The NNTPCommand constant corresponding to the NNTP command
 340  
      *                 to send.
 341  
      * @return The integer value of the NNTP reply code returned by the server
 342  
      *         in response to the command.
 343  
      *         in response to the command.
 344  
      * @exception NNTPConnectionClosedException
 345  
      *      If the NNTP server prematurely closes the connection as a result
 346  
      *      of the client being idle or some other reason causing the server
 347  
      *      to send NNTP reply code 400.  This exception may be caught either
 348  
      *      as an IOException or independently as itself.
 349  
      * @exception IOException  If an I/O error occurs while either sending the
 350  
      *      command or receiving the server reply.
 351  
      ***/
 352  
     public int sendCommand(class="keyword">int command) throws IOException
 353  
     {
 354  0
         return sendCommand(command, null);
 355  
     }
 356  
 
 357  
 
 358  
     /***
 359  
      * Returns the integer value of the reply code of the last NNTP reply.
 360  
      * You will usually only use this method after you connect to the
 361  
      * NNTP server to check that the connection was successful since
 362  
      * <code> connect </code> is of type void.
 363  
      * <p>
 364  
      * @return The integer value of the reply code of the last NNTP reply.
 365  
      ***/
 366  
     public int getReplyCode()
 367  
     {
 368  0
         return _replyCode;
 369  
     }
 370  
 
 371  
     /***
 372  
      * Fetches a reply from the NNTP server and returns the integer reply
 373  
      * code.  After calling this method, the actual reply text can be accessed
 374  
      * from {@link #getReplyString  getReplyString }.  Only use this
 375  
      * method if you are implementing your own NNTP client or if you need to
 376  
      * fetch a secondary response from the NNTP server.
 377  
      * <p>
 378  
      * @return The integer value of the reply code of the fetched NNTP reply.
 379  
      *         in response to the command.
 380  
      * @exception NNTPConnectionClosedException
 381  
      *      If the NNTP server prematurely closes the connection as a result
 382  
      *      of the client being idle or some other reason causing the server
 383  
      *      to send NNTP reply code 400.  This exception may be caught either
 384  
      *      as an IOException or independently as itself.
 385  
      * @exception IOException  If an I/O error occurs while
 386  
      *      receiving the server reply.
 387  
      ***/
 388  
     public int getReply() throws IOException
 389  
     {
 390  0
         __getReply();
 391  0
         return _replyCode;
 392  
     }
 393  
 
 394  
 
 395  
     /***
 396  
      * Returns the entire text of the last NNTP server response exactly
 397  
      * as it was received, not including the end of line marker.
 398  
      * <p>
 399  
      * @return The entire text from the last NNTP response as a String.
 400  
      ***/
 401  
     public String getReplyString()
 402  
     {
 403  0
         return _replyString;
 404  
     }
 405  
 
 406  
 
 407  
     /***
 408  
      * A convenience method to send the NNTP ARTICLE command to the server,
 409  
      * receive the initial reply, and return the reply code.
 410  
      * <p>
 411  
      * @param messageId  The message identifier of the requested article,
 412  
      *                   including the encapsulating &lt and &gt characters.
 413  
      * @return The reply code received from the server.
 414  
      * @exception NNTPConnectionClosedException
 415  
      *      If the NNTP server prematurely closes the connection as a result
 416  
      *      of the client being idle or some other reason causing the server
 417  
      *      to send NNTP reply code 400.  This exception may be caught either
 418  
      *      as an IOException or independently as itself.
 419  
      * @exception IOException  If an I/O error occurs while either sending the
 420  
      *      command or receiving the server reply.
 421  
      ***/
 422  
     public int article(String messageId) throws IOException
 423  
     {
 424  0
         return sendCommand(NNTPCommand.ARTICLE, messageId);
 425  
     }
 426  
 
 427  
     /***
 428  
      * A convenience method to send the NNTP ARTICLE command to the server,
 429  
      * receive the initial reply, and return the reply code.
 430  
      * <p>
 431  
      * @param articleNumber The number of the article to request from the
 432  
      *                      currently selected newsgroup.
 433  
      * @return The reply code received from the server.
 434  
      * @exception NNTPConnectionClosedException
 435  
      *      If the NNTP server prematurely closes the connection as a result
 436  
      *      of the client being idle or some other reason causing the server
 437  
      *      to send NNTP reply code 400.  This exception may be caught either
 438  
      *      as an IOException or independently as itself.
 439  
      * @exception IOException  If an I/O error occurs while either sending the
 440  
      *      command or receiving the server reply.
 441  
      ***/
 442  
     public int article(class="keyword">int articleNumber) throws IOException
 443  
     {
 444  0
         return sendCommand(NNTPCommand.ARTICLE, Integer.toString(articleNumber));
 445  
     }
 446  
 
 447  
     /***
 448  
      * A convenience method to send the NNTP ARTICLE command to the server,
 449  
      * receive the initial reply, and return the reply code.
 450  
      * <p>
 451  
      * @return The reply code received from the server.
 452  
      * @exception NNTPConnectionClosedException
 453  
      *      If the NNTP server prematurely closes the connection as a result
 454  
      *      of the client being idle or some other reason causing the server
 455  
      *      to send NNTP reply code 400.  This exception may be caught either
 456  
      *      as an IOException or independently as itself.
 457  
      * @exception IOException  If an I/O error occurs while either sending the
 458  
      *      command or receiving the server reply.
 459  
      ***/
 460  
     public int article() throws IOException
 461  
     {
 462  0
         return sendCommand(NNTPCommand.ARTICLE);
 463  
     }
 464  
 
 465  
 
 466  
 
 467  
     /***
 468  
      * A convenience method to send the NNTP BODY command to the server,
 469  
      * receive the initial reply, and return the reply code.
 470  
      * <p>
 471  
      * @param messageId  The message identifier of the requested article,
 472  
      *                   including the encapsulating &lt and &gt characters.
 473  
      * @return The reply code received from the server.
 474  
      * @exception NNTPConnectionClosedException
 475  
      *      If the NNTP server prematurely closes the connection as a result
 476  
      *      of the client being idle or some other reason causing the server
 477  
      *      to send NNTP reply code 400.  This exception may be caught either
 478  
      *      as an IOException or independently as itself.
 479  
      * @exception IOException  If an I/O error occurs while either sending the
 480  
      *      command or receiving the server reply.
 481  
      ***/
 482  
     public int body(String messageId) throws IOException
 483  
     {
 484  0
         return sendCommand(NNTPCommand.BODY, messageId);
 485  
     }
 486  
 
 487  
     /***
 488  
      * A convenience method to send the NNTP BODY command to the server,
 489  
      * receive the initial reply, and return the reply code.
 490  
      * <p>
 491  
      * @param articleNumber The number of the article to request from the
 492  
      *                      currently selected newsgroup.
 493  
      * @return The reply code received from the server.
 494  
      * @exception NNTPConnectionClosedException
 495  
      *      If the NNTP server prematurely closes the connection as a result
 496  
      *      of the client being idle or some other reason causing the server
 497  
      *      to send NNTP reply code 400.  This exception may be caught either
 498  
      *      as an IOException or independently as itself.
 499  
      * @exception IOException  If an I/O error occurs while either sending the
 500  
      *      command or receiving the server reply.
 501  
      ***/
 502  
     public int body(class="keyword">int articleNumber) throws IOException
 503  
     {
 504  0
         return sendCommand(NNTPCommand.BODY, Integer.toString(articleNumber));
 505  
     }
 506  
 
 507  
     /***
 508  
      * A convenience method to send the NNTP BODY command to the server,
 509  
      * receive the initial reply, and return the reply code.
 510  
      * <p>
 511  
      * @return The reply code received from the server.
 512  
      * @exception NNTPConnectionClosedException
 513  
      *      If the NNTP server prematurely closes the connection as a result
 514  
      *      of the client being idle or some other reason causing the server
 515  
      *      to send NNTP reply code 400.  This exception may be caught either
 516  
      *      as an IOException or independently as itself.
 517  
      * @exception IOException  If an I/O error occurs while either sending the
 518  
      *      command or receiving the server reply.
 519  
      ***/
 520  
     public int body() throws IOException
 521  
     {
 522  0
         return sendCommand(NNTPCommand.BODY);
 523  
     }
 524  
 
 525  
 
 526  
 
 527  
     /***
 528  
      * A convenience method to send the NNTP HEAD command to the server,
 529  
      * receive the initial reply, and return the reply code.
 530  
      * <p>
 531  
      * @param messageId  The message identifier of the requested article,
 532  
      *                   including the encapsulating &lt and &gt characters.
 533  
      * @return The reply code received from the server.
 534  
      * @exception NNTPConnectionClosedException
 535  
      *      If the NNTP server prematurely closes the connection as a result
 536  
      *      of the client being idle or some other reason causing the server
 537  
      *      to send NNTP reply code 400.  This exception may be caught either
 538  
      *      as an IOException or independently as itself.
 539  
      * @exception IOException  If an I/O error occurs while either sending the
 540  
      *      command or receiving the server reply.
 541  
      ***/
 542  
     public int head(String messageId) throws IOException
 543  
     {
 544  0
         return sendCommand(NNTPCommand.HEAD, messageId);
 545  
     }
 546  
 
 547  
     /***
 548  
      * A convenience method to send the NNTP HEAD command to the server,
 549  
      * receive the initial reply, and return the reply code.
 550  
      * <p>
 551  
      * @param articleNumber The number of the article to request from the
 552  
      *                      currently selected newsgroup.
 553  
      * @return The reply code received from the server.
 554  
      * @exception NNTPConnectionClosedException
 555  
      *      If the NNTP server prematurely closes the connection as a result
 556  
      *      of the client being idle or some other reason causing the server
 557  
      *      to send NNTP reply code 400.  This exception may be caught either
 558  
      *      as an IOException or independently as itself.
 559  
      * @exception IOException  If an I/O error occurs while either sending the
 560  
      *      command or receiving the server reply.
 561  
      ***/
 562  
     public int head(class="keyword">int articleNumber) throws IOException
 563  
     {
 564  0
         return sendCommand(NNTPCommand.HEAD, Integer.toString(articleNumber));
 565  
     }
 566  
 
 567  
     /***
 568  
      * A convenience method to send the NNTP HEAD command to the server,
 569  
      * receive the initial reply, and return the reply code.
 570  
      * <p>
 571  
      * @return The reply code received from the server.
 572  
      * @exception NNTPConnectionClosedException
 573  
      *      If the NNTP server prematurely closes the connection as a result
 574  
      *      of the client being idle or some other reason causing the server
 575  
      *      to send NNTP reply code 400.  This exception may be caught either
 576  
      *      as an IOException or independently as itself.
 577  
      * @exception IOException  If an I/O error occurs while either sending the
 578  
      *      command or receiving the server reply.
 579  
      ***/
 580  
     public int head() throws IOException
 581  
     {
 582  0
         return sendCommand(NNTPCommand.HEAD);
 583  
     }
 584  
 
 585  
 
 586  
 
 587  
     /***
 588  
      * A convenience method to send the NNTP STAT command to the server,
 589  
      * receive the initial reply, and return the reply code.
 590  
      * <p>
 591  
      * @param messageId  The message identifier of the requested article,
 592  
      *                   including the encapsulating &lt and &gt characters.
 593  
      * @return The reply code received from the server.
 594  
      * @exception NNTPConnectionClosedException
 595  
      *      If the NNTP server prematurely closes the connection as a result
 596  
      *      of the client being idle or some other reason causing the server
 597  
      *      to send NNTP reply code 400.  This exception may be caught either
 598  
      *      as an IOException or independently as itself.
 599  
      * @exception IOException  If an I/O error occurs while either sending the
 600  
      *      command or receiving the server reply.
 601  
      ***/
 602  
     public int stat(String messageId) throws IOException
 603  
     {
 604  0
         return sendCommand(NNTPCommand.STAT, messageId);
 605  
     }
 606  
 
 607  
     /***
 608  
      * A convenience method to send the NNTP STAT command to the server,
 609  
      * receive the initial reply, and return the reply code.
 610  
      * <p>
 611  
      * @param articleNumber The number of the article to request from the
 612  
      *                      currently selected newsgroup.
 613  
      * @return The reply code received from the server.
 614  
      * @exception NNTPConnectionClosedException
 615  
      *      If the NNTP server prematurely closes the connection as a result
 616  
      *      of the client being idle or some other reason causing the server
 617  
      *      to send NNTP reply code 400.  This exception may be caught either
 618  
      *      as an IOException or independently as itself.
 619  
      * @exception IOException  If an I/O error occurs while either sending the
 620  
      *      command or receiving the server reply.
 621  
      ***/
 622  
     public int stat(class="keyword">int articleNumber) throws IOException
 623  
     {
 624  0
         return sendCommand(NNTPCommand.STAT, Integer.toString(articleNumber));
 625  
     }
 626  
 
 627  
     /***
 628  
      * A convenience method to send the NNTP STAT command to the server,
 629  
      * receive the initial reply, and return the reply code.
 630  
      * <p>
 631  
      * @return The reply code received from the server.
 632  
      * @exception NNTPConnectionClosedException
 633  
      *      If the NNTP server prematurely closes the connection as a result
 634  
      *      of the client being idle or some other reason causing the server
 635  
      *      to send NNTP reply code 400.  This exception may be caught either
 636  
      *      as an IOException or independently as itself.
 637  
      * @exception IOException  If an I/O error occurs while either sending the
 638  
      *      command or receiving the server reply.
 639  
      ***/
 640  
     public int stat() throws IOException
 641  
     {
 642  0
         return sendCommand(NNTPCommand.STAT);
 643  
     }
 644  
 
 645  
 
 646  
     /***
 647  
      * A convenience method to send the NNTP GROUP command to the server,
 648  
      * receive the reply, and return the reply code.
 649  
      * <p>
 650  
      * @param newsgroup  The name of the newsgroup to select.
 651  
      * @return The reply code received from the server.
 652  
      * @exception NNTPConnectionClosedException
 653  
      *      If the NNTP server prematurely closes the connection as a result
 654  
      *      of the client being idle or some other reason causing the server
 655  
      *      to send NNTP reply code 400.  This exception may be caught either
 656  
      *      as an IOException or independently as itself.
 657  
      * @exception IOException  If an I/O error occurs while either sending the
 658  
      *      command or receiving the server reply.
 659  
      ***/
 660  
     public int group(String newsgroup) throws IOException
 661  
     {
 662  0
         return sendCommand(NNTPCommand.GROUP, newsgroup);
 663  
     }
 664  
 
 665  
 
 666  
     /***
 667  
      * A convenience method to send the NNTP HELP command to the server,
 668  
      * receive the reply, and return the reply code.
 669  
      * <p>
 670  
      * @return The reply code received from the server.
 671  
      * @exception NNTPConnectionClosedException
 672  
      *      If the NNTP server prematurely closes the connection as a result
 673  
      *      of the client being idle or some other reason causing the server
 674  
      *      to send NNTP reply code 400.  This exception may be caught either
 675  
      *      as an IOException or independently as itself.
 676  
      * @exception IOException  If an I/O error occurs while either sending the
 677  
      *      command or receiving the server reply.
 678  
      ***/
 679  
     public int help() throws IOException
 680  
     {
 681  0
         return sendCommand(NNTPCommand.HELP);
 682  
     }
 683  
 
 684  
 
 685  
     /***
 686  
      * A convenience method to send the NNTP IHAVE command to the server,
 687  
      * receive the reply, and return the reply code.
 688  
      * <p>
 689  
      * @param messageId  The article identifier,
 690  
      *                   including the encapsulating &lt and &gt characters.
 691  
      * @return The reply code received from the server.
 692  
      * @exception NNTPConnectionClosedException
 693  
      *      If the NNTP server prematurely closes the connection as a result
 694  
      *      of the client being idle or some other reason causing the server
 695  
      *      to send NNTP reply code 400.  This exception may be caught either
 696  
      *      as an IOException or independently as itself.
 697  
      * @exception IOException  If an I/O error occurs while either sending the
 698  
      *      command or receiving the server reply.
 699  
      ***/
 700  
     public int ihave(String messageId) throws IOException
 701  
     {
 702  0
         return sendCommand(NNTPCommand.IHAVE, messageId);
 703  
     }
 704  
 
 705  
 
 706  
     /***
 707  
      * A convenience method to send the NNTP LAST command to the server,
 708  
      * receive the reply, and return the reply code.
 709  
      * <p>
 710  
      * @return The reply code received from the server.
 711  
      * @exception NNTPConnectionClosedException
 712  
      *      If the NNTP server prematurely closes the connection as a result
 713  
      *      of the client being idle or some other reason causing the server
 714  
      *      to send NNTP reply code 400.  This exception may be caught either
 715  
      *      as an IOException or independently as itself.
 716  
      * @exception IOException  If an I/O error occurs while either sending the
 717  
      *      command or receiving the server reply.
 718  
      ***/
 719  
     public int last() throws IOException
 720  
     {
 721  0
         return sendCommand(NNTPCommand.LAST);
 722  
     }
 723  
 
 724  
 
 725  
 
 726  
     /***
 727  
      * A convenience method to send the NNTP LIST command to the server,
 728  
      * receive the reply, and return the reply code.
 729  
      * <p>
 730  
      * @return The reply code received from the server.
 731  
      * @exception NNTPConnectionClosedException
 732  
      *      If the NNTP server prematurely closes the connection as a result
 733  
      *      of the client being idle or some other reason causing the server
 734  
      *      to send NNTP reply code 400.  This exception may be caught either
 735  
      *      as an IOException or independently as itself.
 736  
      * @exception IOException  If an I/O error occurs while either sending the
 737  
      *      command or receiving the server reply.
 738  
      ***/
 739  
     public int list() throws IOException
 740  
     {
 741  0
         return sendCommand(NNTPCommand.LIST);
 742  
     }
 743  
 
 744  
 
 745  
 
 746  
     /***
 747  
      * A convenience method to send the NNTP NEXT command to the server,
 748  
      * receive the reply, and return the reply code.
 749  
      * <p>
 750  
      * @return The reply code received from the server.
 751  
      * @exception NNTPConnectionClosedException
 752  
      *      If the NNTP server prematurely closes the connection as a result
 753  
      *      of the client being idle or some other reason causing the server
 754  
      *      to send NNTP reply code 400.  This exception may be caught either
 755  
      *      as an IOException or independently as itself.
 756  
      * @exception IOException  If an I/O error occurs while either sending the
 757  
      *      command or receiving the server reply.
 758  
      ***/
 759  
     public int next() throws IOException
 760  
     {
 761  0
         return sendCommand(NNTPCommand.NEXT);
 762  
     }
 763  
 
 764  
 
 765  
     /***
 766  
      * A convenience method to send the NNTP NEWGROUPS command to the server,
 767  
      * receive the reply, and return the reply code.
 768  
      * <p>
 769  
      * @param date The date after which to check for new groups.
 770  
      *             Date format is YYMMDD
 771  
      * @param time The time after which to check for new groups.
 772  
      *             Time format is HHMMSS using a 24-hour clock.
 773  
      * @param GMT  True if the time is in GMT, false if local server time.
 774  
      * @param distributions  Comma-separated distribution list to check for
 775  
      *            new groups. Set to null if no distributions.
 776  
      * @return The reply code received from the server.
 777  
      * @exception NNTPConnectionClosedException
 778  
      *      If the NNTP server prematurely closes the connection as a result
 779  
      *      of the client being idle or some other reason causing the server
 780  
      *      to send NNTP reply code 400.  This exception may be caught either
 781  
      *      as an IOException or independently as itself.
 782  
      * @exception IOException  If an I/O error occurs while either sending the
 783  
      *      command or receiving the server reply.
 784  
      ***/
 785  
     public int newgroups(String date, String time, boolean GMT,
 786  
                          String distributions) throws IOException
 787  
     {
 788  0
         StringBuffer buffer = new StringBuffer();
 789  
 
 790  0
         buffer.append(date);
 791  0
         buffer.append(' ');
 792  0
         buffer.append(time);
 793  
 
 794  0
         if (GMT)
 795  
         {
 796  0
             buffer.append(' ');
 797  0
             buffer.append("GMT");
 798  
         }
 799  
 
 800  0
         if (distributions != null)
 801  
         {
 802  0
             buffer.append(" <");
 803  0
             buffer.append(distributions);
 804  0
             buffer.append('>');
 805  
         }
 806  
 
 807  0
         return sendCommand(NNTPCommand.NEWGROUPS, buffer.toString());
 808  
     }
 809  
 
 810  
 
 811  
     /***
 812  
      * A convenience method to send the NNTP NEWGROUPS command to the server,
 813  
      * receive the reply, and return the reply code.
 814  
      * <p>
 815  
      * @param newsgroups A comma-separated list of newsgroups to check for new
 816  
      *             news.
 817  
      * @param date The date after which to check for new news.
 818  
      *             Date format is YYMMDD
 819  
      * @param time The time after which to check for new news.
 820  
      *             Time format is HHMMSS using a 24-hour clock.
 821  
      * @param GMT  True if the time is in GMT, false if local server time.
 822  
      * @param distributions  Comma-separated distribution list to check for
 823  
      *            new news. Set to null if no distributions.
 824  
      * @return The reply code received from the server.
 825  
      * @exception NNTPConnectionClosedException
 826  
      *      If the NNTP server prematurely closes the connection as a result
 827  
      *      of the client being idle or some other reason causing the server
 828  
      *      to send NNTP reply code 400.  This exception may be caught either
 829  
      *      as an IOException or independently as itself.
 830  
      * @exception IOException  If an I/O error occurs while either sending the
 831  
      *      command or receiving the server reply.
 832  
      ***/
 833  
     public int newnews(String newsgroups, String date, String time, boolean GMT,
 834  
                        String distributions) throws IOException
 835  
     {
 836  0
         StringBuffer buffer = new StringBuffer();
 837  
 
 838  0
         buffer.append(newsgroups);
 839  0
         buffer.append(' ');
 840  0
         buffer.append(date);
 841  0
         buffer.append(' ');
 842  0
         buffer.append(time);
 843  
 
 844  0
         if (GMT)
 845  
         {
 846  0
             buffer.append(' ');
 847  0
             buffer.append("GMT");
 848  
         }
 849  
 
 850  0
         if (distributions != null)
 851  
         {
 852  0
             buffer.append(" <");
 853  0
             buffer.append(distributions);
 854  0
             buffer.append('>');
 855  
         }
 856  
 
 857  0
         return sendCommand(NNTPCommand.NEWNEWS, buffer.toString());
 858  
     }
 859  
 
 860  
 
 861  
 
 862  
     /***
 863  
      * A convenience method to send the NNTP POST command to the server,
 864  
      * receive the reply, and return the reply code.
 865  
      * <p>
 866  
      * @return The reply code received from the server.
 867  
      * @exception NNTPConnectionClosedException
 868  
      *      If the NNTP server prematurely closes the connection as a result
 869  
      *      of the client being idle or some other reason causing the server
 870  
      *      to send NNTP reply code 400.  This exception may be caught either
 871  
      *      as an IOException or independently as itself.
 872  
      * @exception IOException  If an I/O error occurs while either sending the
 873  
      *      command or receiving the server reply.
 874  
      ***/
 875  
     public int post() throws IOException
 876  
     {
 877  0
         return sendCommand(NNTPCommand.POST);
 878  
     }
 879  
 
 880  
 
 881  
 
 882  
     /***
 883  
      * A convenience method to send the NNTP QUIT command to the server,
 884  
      * receive the reply, and return the reply code.
 885  
      * <p>
 886  
      * @return The reply code received from the server.
 887  
      * @exception NNTPConnectionClosedException
 888  
      *      If the NNTP server prematurely closes the connection as a result
 889  
      *      of the client being idle or some other reason causing the server
 890  
      *      to send NNTP reply code 400.  This exception may be caught either
 891  
      *      as an IOException or independently as itself.
 892  
      * @exception IOException  If an I/O error occurs while either sending the
 893  
      *      command or receiving the server reply.
 894  
      ***/
 895  
     public int quit() throws IOException
 896  
     {
 897  0
         return sendCommand(NNTPCommand.QUIT);
 898  
     }
 899  
 
 900  
     /***
 901  
      * A convenience method to send the AUTHINFO USER command to the server,
 902  
      *  receive the reply, and return the reply code. (See RFC 2980)
 903  
      * <p>
 904  
      * @param username A valid username.
 905  
      * @return The reply code received from the server. The server should
 906  
      *          return a 381 or 281 for this command.
 907  
      * @exception NNTPConnectionClosedException
 908  
      *      If the NNTP server prematurely closes the connection as a result
 909  
      *      of the client being idle or some other reason causing the server
 910  
      *      to send NNTP reply code 400.  This exception may be caught either
 911  
      *      as an IOException or independently as itself.
 912  
      * @exception IOException  If an I/O error occurs while either sending the
 913  
      *      command or receiving the server reply.
 914  
      ***/
 915  
     public int authinfoUser(String username) throws IOException {
 916  0
         String userParameter = "USER " + username;
 917  0
         return sendCommand(NNTPCommand.AUTHINFO, userParameter);
 918  
     }
 919  
 
 920  
     /***
 921  
      * A convenience method to send the AUTHINFO PASS command to the server,
 922  
      * receive the reply, and return the reply code.  If this step is
 923  
      * required, it should immediately follow the AUTHINFO USER command
 924  
      * (See RFC 2980)
 925  
      * <p>
 926  
      * @param password a valid password.
 927  
      * @return The reply code received from the server. The server should
 928  
      *         return a 281 or 502 for this command.
 929  
      * @exception NNTPConnectionClosedException
 930  
      *      If the NNTP server prematurely closes the connection as a result
 931  
      *      of the client being idle or some other reason causing the server
 932  
      *      to send NNTP reply code 400.  This exception may be caught either
 933  
      *      as an IOException or independently as itself.
 934  
      * @exception IOException  If an I/O error occurs while either sending the
 935  
      *      command or receiving the server reply.
 936  
      ***/
 937  
     public int authinfoPass(String password) throws IOException {
 938  0
         String passParameter = "PASS " + password;
 939  0
         return sendCommand(NNTPCommand.AUTHINFO, passParameter);
 940  
     }
 941  
 
 942  
     /***
 943  
      * A convenience method to send the NNTP XOVER command to the server,
 944  
      * receive the reply, and return the reply code.
 945  
      * <p>
 946  
      * @param selectedArticles a String representation of the range of
 947  
      * article headers required. This may be an article number, or a
 948  
      * range of article numbers in the form "XXXX-YYYY", where XXXX
 949  
      * and YYYY are valid article numbers in the current group.  It
 950  
      * also may be of the form "XXX-", meaning "return XXX and all
 951  
      * following articles" In this revision, the last format is not
 952  
      * possible (yet).
 953  
      * @return The reply code received from the server.
 954  
      * @exception NNTPConnectionClosedException
 955  
      *      If the NNTP server prematurely closes the connection as a result
 956  
      *      of the client being idle or some other reason causing the server
 957  
      *      to send NNTP reply code 400.  This exception may be caught either
 958  
      *      as an IOException or independently as itself.
 959  
      * @exception IOException  If an I/O error occurs while either sending the
 960  
      *      command or receiving the server reply.
 961  
      ***/
 962  
     public int xover(String selectedArticles) throws IOException {
 963  0
         return sendCommand(NNTPCommand.XOVER, selectedArticles);
 964  
     }
 965  
 
 966  
     /***
 967  
      * A convenience method to send the NNTP XHDR command to the server,
 968  
      * receive the reply, and return the reply code.
 969  
      * <p>
 970  
      * @param header a String naming a header line (e.g., "subject").  See
 971  
      * RFC-1036 for a list of valid header lines.
 972  
      * @param selectedArticles a String representation of the range of
 973  
      * article headers required. This may be an article number, or a
 974  
      * range of article numbers in the form "XXXX-YYYY", where XXXX
 975  
      * and YYYY are valid article numbers in the current group.  It
 976  
      * also may be of the form "XXX-", meaning "return XXX and all
 977  
      * following articles" In this revision, the last format is not
 978  
      * possible (yet).
 979  
      * @return The reply code received from the server.
 980  
      * @exception NNTPConnectionClosedException
 981  
      *      If the NNTP server prematurely closes the connection as a result
 982  
      *      of the client being idle or some other reason causing the server
 983  
      *      to send NNTP reply code 400.  This exception may be caught either
 984  
      *      as an IOException or independently as itself.
 985  
      * @exception IOException  If an I/O error occurs while either sending the
 986  
      *      command or receiving the server reply.
 987  
      ***/
 988  
     public int xhdr(String header, String selectedArticles) throws IOException {
 989  0
         StringBuffer command = new StringBuffer(header);
 990  0
         command.append(" ");
 991  0
         command.append(selectedArticles);
 992  0
         return sendCommand(NNTPCommand.XHDR, command.toString());
 993  
     }
 994  
 
 995  
     /**
 996  
      * A convenience wrapper for the extended LIST command that takes
 997  
      * an argument, allowing us to selectively list multiple groups.
 998  
      * <p>
 999  
      * @param wildmat A wildmat (pseudo-regex) pattern. See RFC 2980 for
 1000  
      *                details.
 1001  
      * @return the reply code received from the server.
 1002  
      * @throws IOException
 1003  
      */
 1004  
     public int listActive(String wildmat) throws IOException {
 1005  0
         StringBuffer command = new StringBuffer("ACTIVE ");
 1006  0
         command.append(wildmat);
 1007  0
         return sendCommand(NNTPCommand.LIST, command.toString());
 1008  
     }
 1009  
 }
 1010  
 
 1011  
 /* Emacs configuration
 1012  
  * Local variables:        **
 1013  
  * mode:             java  **
 1014  
  * c-basic-offset:   4     **
 1015  
  * indent-tabs-mode: nil   **
 1016  
  * End:                    **
 1017  
  */

This report is generated by jcoverage, Maven and Maven JCoverage Plugin.