001 /*
002 * Copyright 2001-2005 The Apache Software Foundation
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.apache.commons.net.nntp;
017
018 /***
019 * This class is used to construct the bare minimum
020 * acceptable header for most news readers. To construct more
021 * complicated headers you should refer to RFC 822. When the
022 * Java Mail API is finalized, you will be
023 * able to use it to compose fully compliant Internet text messages.
024 * <p>
025 * The main purpose of the class is to faciliatate the article posting
026 * process, by relieving the programmer from having to explicitly format
027 * an article header. For example:
028 * <pre>
029 * writer = client.postArticle();
030 * if(writer == null) // failure
031 * return false;
032 * header = new SimpleNNTPHeader("foobar@foo.com", "Just testing");
033 * header.addNewsgroup("alt.test");
034 * header.addHeaderField("Organization", "Foobar, Inc.");
035 * writer.write(header.toString());
036 * writer.write("This is just a test");
037 * writer.close();
038 * if(!client.completePendingCommand()) // failure
039 * return false;
040 * </pre>
041 * <p>
042 * <p>
043 * @author Daniel F. Savarese
044 * @see NNTPClient
045 ***/
046
047 public class SimpleNNTPHeader
048 {
049 private String __subject, __from;
050 private StringBuffer __newsgroups;
051 private StringBuffer __headerFields;
052 private int __newsgroupCount;
053
054 /***
055 * Creates a new SimpleNNTPHeader instance initialized with the given
056 * from and subject header field values.
057 * <p>
058 * @param from The value of the <code>From:</code> header field. This
059 * should be the article poster's email address.
060 * @param subject The value of the <code>Subject:</code> header field.
061 * This should be the subject of the article.
062 ***/
063 public SimpleNNTPHeader(String from, String subject)
064 {
065 __from = from;
066 __subject = subject;
067 __newsgroups = new StringBuffer();
068 __headerFields = new StringBuffer();
069 __newsgroupCount = 0;
070 }
071
072 /***
073 * Adds a newsgroup to the article <code>Newsgroups:</code> field.
074 * <p>
075 * @param newsgroup The newsgroup to add to the article's newsgroup
076 * distribution list.
077 ***/
078 public void addNewsgroup(String newsgroup)
079 {
080 if (__newsgroupCount++ > 0)
081 __newsgroups.append(',');
082 __newsgroups.append(newsgroup);
083 }
084
085 /***
086 * Adds an arbitrary header field with the given value to the article
087 * header. These headers will be written after the From, Newsgroups,
088 * and Subject fields when the SimpleNNTPHeader is convertered to a string.
089 * An example use would be:
090 * <pre>
091 * header.addHeaderField("Organization", "Foobar, Inc.");
092 * </pre>
093 * <p>
094 * @param headerField The header field to add, not including the colon.
095 * @param value The value of the added header field.
096 ***/
097 public void addHeaderField(String headerField, String value)
098 {
099 __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 }