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 }