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 * @author Daniel F. Savarese
46 * @see NNTPClient
47 ***/
48
49 public class SimpleNNTPHeader
50 {
51 private String __subject, __from;
52 private StringBuilder __newsgroups;
53 private StringBuilder __headerFields;
54 private int __newsgroupCount;
55
56 /***
57 * Creates a new SimpleNNTPHeader instance initialized with the given
58 * from and subject header field values.
59 * <p>
60 * @param from The value of the <code>From:</code> header field. This
61 * should be the article poster's email address.
62 * @param subject The value of the <code>Subject:</code> header field.
63 * This should be the subject of the article.
64 ***/
65 public SimpleNNTPHeader(String from, String subject)
66 {
67 __from = from;
68 __subject = subject;
69 __newsgroups = new StringBuilder();
70 __headerFields = new StringBuilder();
71 __newsgroupCount = 0;
72 }
73
74 /***
75 * Adds a newsgroup to the article <code>Newsgroups:</code> field.
76 * <p>
77 * @param newsgroup The newsgroup to add to the article's newsgroup
78 * distribution list.
79 ***/
80 public void addNewsgroup(String newsgroup)
81 {
82 if (__newsgroupCount++ > 0)
83 __newsgroups.append(',');
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 StringBuffer header = new StringBuffer();
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 header.append('\n');
161
162 return header.toString();
163 }
164 }