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