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 }