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   * <p>
44   * <p>
45   * @see NNTPClient
46   ***/
47  
48  public class SimpleNNTPHeader
49  {
50      private final String __subject, __from;
51      private final StringBuilder __newsgroups;
52      private final StringBuilder __headerFields;
53      private int __newsgroupCount;
54  
55      /***
56       * Creates a new SimpleNNTPHeader instance initialized with the given
57       * from and subject header field values.
58       * <p>
59       * @param from  The value of the <code>From:</code> header field.  This
60       *              should be the article poster's email address.
61       * @param subject  The value of the <code>Subject:</code> header field.
62       *              This should be the subject of the article.
63       ***/
64      public SimpleNNTPHeader(String from, String subject)
65      {
66          __from = from;
67          __subject = subject;
68          __newsgroups = new StringBuilder();
69          __headerFields = new StringBuilder();
70          __newsgroupCount = 0;
71      }
72  
73      /***
74       * Adds a newsgroup to the article <code>Newsgroups:</code> field.
75       * <p>
76       * @param newsgroup  The newsgroup to add to the article's newsgroup
77       *                   distribution list.
78       ***/
79      public void addNewsgroup(String newsgroup)
80      {
81          if (__newsgroupCount++ > 0) {
82              __newsgroups.append(',');
83          }
84          __newsgroups.append(newsgroup);
85      }
86  
87      /***
88       * Adds an arbitrary header field with the given value to the article
89       * header.  These headers will be written after the From, Newsgroups,
90       * and Subject fields when the SimpleNNTPHeader is convertered to a string.
91       * An example use would be:
92       * <pre>
93       * header.addHeaderField("Organization", "Foobar, Inc.");
94       * </pre>
95       * <p>
96       * @param headerField  The header field to add, not including the colon.
97       * @param value  The value of the added header field.
98       ***/
99      public void addHeaderField(String headerField, String value)
100     {
101         __headerFields.append(headerField);
102         __headerFields.append(": ");
103         __headerFields.append(value);
104         __headerFields.append('\n');
105     }
106 
107 
108     /***
109      * Returns the address used in the <code> From: </code> header field.
110      * <p>
111      * @return The from address.
112      ***/
113     public String getFromAddress()
114     {
115         return __from;
116     }
117 
118     /***
119      * Returns the subject used in the <code> Subject: </code> header field.
120      * <p>
121      * @return The subject.
122      ***/
123     public String getSubject()
124     {
125         return __subject;
126     }
127 
128     /***
129      * Returns the contents of the <code> Newsgroups: </code> header field.
130      * <p>
131      * @return The comma-separated list of newsgroups to which the article
132      *         is being posted.
133      ***/
134     public String getNewsgroups()
135     {
136         return __newsgroups.toString();
137     }
138 
139     /***
140      * Converts the SimpleNNTPHeader to a properly formatted header in
141      * the form of a String, including the blank line used to separate
142      * the header from the article body.
143      * <p>
144      * @return The article header in the form of a String.
145      ***/
146     @Override
147     public String toString()
148     {
149         StringBuilder header = new StringBuilder();
150 
151         header.append("From: ");
152         header.append(__from);
153         header.append("\nNewsgroups: ");
154         header.append(__newsgroups.toString());
155         header.append("\nSubject: ");
156         header.append(__subject);
157         header.append('\n');
158         if (__headerFields.length() > 0) {
159             header.append(__headerFields.toString());
160         }
161         header.append('\n');
162 
163         return header.toString();
164     }
165 }