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