View Javadoc

    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  /****
    19   * This class is used to construct the bare minimum
    20   * acceptable header for most news readers.  To construct more
    21   * complicated headers you should refer to RFC 822.  When the
    22   * Java Mail API is finalized, you will be
    23   * able to use it to compose fully compliant Internet text messages.
    24   * <p>
    25   * The main purpose of the class is to faciliatate the article posting
    26   * process, by relieving the programmer from having to explicitly format
    27   * an article header.  For example:
    28   * <pre>
    29   * writer = client.postArticle();
    30   * if(writer == null) // failure
    31   *   return false;
    32   * header = new SimpleNNTPHeader("foobar@foo.com", "Just testing");
    33   * header.addNewsgroup("alt.test");
    34   * header.addHeaderField("Organization", "Foobar, Inc.");
    35   * writer.write(header.toString());
    36   * writer.write("This is just a test");
    37   * writer.close();
    38   * if(!client.completePendingCommand()) // failure
    39   *   return false;
    40   * </pre>
    41   * <p>
    42   * <p>
    43   * @author Daniel F. Savarese
    44   * @see NNTPClient
    45   ***/
    46
    47  public class SimpleNNTPHeader
    48  {
    49      private String __subject, __from;
    50      private StringBuffer __newsgroups;
    51      private StringBuffer __headerFields;
    52      private int __newsgroupCount;
    53
    54      /****
    55       * Creates a new SimpleNNTPHeader instance initialized with the given
    56       * from and subject header field values.
    57       * <p>
    58       * @param from  The value of the <code>From:</code> header field.  This
    59       *              should be the article poster's email address.
    60       * @param subject  The value of the <code>Subject:</code> header field.
    61       *              This should be the subject of the article.
    62       ***/
    63      public SimpleNNTPHeader(String from, String subject)
    64      {
    65          __from = from;
    66          __subject = subject;
    67          __newsgroups = new StringBuffer();
    68          __headerFields = new StringBuffer();
    69          __newsgroupCount = 0;
    70      }
    71
    72      /****
    73       * Adds a newsgroup to the article <code>Newsgroups:</code> field.
    74       * <p>
    75       * @param newsgroup  The newsgroup to add to the article's newsgroup
    76       *                   distribution list.
    77       ***/
    78      public void addNewsgroup(String newsgroup)
    79      {
    80          if (__newsgroupCount++ > 0)
    81              __newsgroups.append(',');
    82          __newsgroups.append(newsgroup);
    83      }
    84
    85      /****
    86       * Adds an arbitrary header field with the given value to the article
    87       * header.  These headers will be written after the From, Newsgroups,
    88       * and Subject fields when the SimpleNNTPHeader is convertered to a string.
    89       * An example use would be:
    90       * <pre>
    91       * header.addHeaderField("Organization", "Foobar, Inc.");
    92       * </pre>
    93       * <p>
    94       * @param headerField  The header field to add, not including the colon.
    95       * @param value  The value of the added header field.
    96       ***/
    97      public void addHeaderField(String headerField, String value)
    98      {
    99          __headerFields.append(headerField);
    100         __headerFields.append(": ");
    101         __headerFields.append(value);
    102         __headerFields.append('\n');
    103     }
    104
    105
    106     /****
    107      * Returns the address used in the <code> From: </code> header field.
    108      * <p>
    109      * @return The from address.
    110      ***/
    111     public String getFromAddress()
    112     {
    113         return __from;
    114     }
    115
    116     /****
    117      * Returns the subject used in the <code> Subject: </code> header field.
    118      * <p>
    119      * @return The subject.
    120      ***/
    121     public String getSubject()
    122     {
    123         return __subject;
    124     }
    125
    126     /****
    127      * Returns the contents of the <code> Newsgroups: </code> header field.
    128      * <p>
    129      * @return The comma-separated list of newsgroups to which the article
    130      *         is being posted.
    131      ***/
    132     public String getNewsgroups()
    133     {
    134         return __newsgroups.toString();
    135     }
    136
    137     /****
    138      * Converts the SimpleNNTPHeader to a properly formatted header in
    139      * the form of a String, including the blank line used to separate
    140      * the header from the article body.
    141      * <p>
    142      * @return The article header in the form of a String.
    143      ***/
    144     public String toString()
    145     {
    146         StringBuffer header = new StringBuffer();
    147
    148         header.append("From: ");
    149         header.append(__from);
    150         header.append("\nNewsgroups: ");
    151         header.append(__newsgroups.toString());
    152         header.append("\nSubject: ");
    153         header.append(__subject);
    154         header.append('\n');
    155         if (__headerFields.length() > 0)
    156             header.append(__headerFields.toString());
    157         header.append('\n');
    158
    159         return header.toString();
    160     }
    161 }