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 acceptable header for most news readers. To construct more complicated headers you should refer to RFC 822. 022 * When the Java Mail API is finalized, you will be able to use it to compose fully compliant Internet text messages. 023 * <p> 024 * The main purpose of the class is to faciliatate the article posting process, by relieving the programmer from having to explicitly format an article header. 025 * For example: 026 * 027 * <pre> 028 * writer = client.postArticle(); 029 * if (writer == null) // failure 030 * return false; 031 * header = new SimpleNNTPHeader("foobar@foo.com", "Just testing"); 032 * header.addNewsgroup("alt.test"); 033 * header.addHeaderField("Organization", "Foobar, Inc."); 034 * writer.write(header.toString()); 035 * writer.write("This is just a test"); 036 * writer.close(); 037 * if (!client.completePendingCommand()) // failure 038 * return false; 039 * </pre> 040 * 041 * @see NNTPClient 042 */ 043 044public class SimpleNNTPHeader { 045 private final String subject, from; 046 private final StringBuilder newsgroups; 047 private final StringBuilder headerFields; 048 private int newsgroupCount; 049 050 /** 051 * Creates a new SimpleNNTPHeader instance initialized with the given from and subject header field values. 052 * <p> 053 * 054 * @param from The value of the <code>From:</code> header field. This should be the article poster's email address. 055 * @param subject The value of the <code>Subject:</code> header field. This should be the subject of the article. 056 */ 057 public SimpleNNTPHeader(final String from, final String subject) { 058 this.from = from; 059 this.subject = subject; 060 this.newsgroups = new StringBuilder(); 061 this.headerFields = new StringBuilder(); 062 this.newsgroupCount = 0; 063 } 064 065 /** 066 * Adds an arbitrary header field with the given value to the article header. These headers will be written after the From, Newsgroups, and Subject fields 067 * when the SimpleNNTPHeader is convertered to a string. An example use would be: 068 * 069 * <pre> 070 * header.addHeaderField("Organization", "Foobar, Inc."); 071 * </pre> 072 * <p> 073 * 074 * @param headerField The header field to add, not including the colon. 075 * @param value The value of the added header field. 076 */ 077 public void addHeaderField(final String headerField, final String value) { 078 headerFields.append(headerField); 079 headerFields.append(": "); 080 headerFields.append(value); 081 headerFields.append('\n'); 082 } 083 084 /** 085 * Adds a newsgroup to the article <code>Newsgroups:</code> field. 086 * <p> 087 * 088 * @param newsgroup The newsgroup to add to the article's newsgroup distribution list. 089 */ 090 public void addNewsgroup(final String newsgroup) { 091 if (newsgroupCount++ > 0) { 092 newsgroups.append(','); 093 } 094 newsgroups.append(newsgroup); 095 } 096 097 /** 098 * Returns the address used in the <code> From: </code> header field. 099 * <p> 100 * 101 * @return The from address. 102 */ 103 public String getFromAddress() { 104 return from; 105 } 106 107 /** 108 * Returns the contents of the <code> Newsgroups: </code> header field. 109 * <p> 110 * 111 * @return The comma-separated list of newsgroups to which the article is being posted. 112 */ 113 public String getNewsgroups() { 114 return newsgroups.toString(); 115 } 116 117 /** 118 * Returns the subject used in the <code> Subject: </code> header field. 119 * <p> 120 * 121 * @return The subject. 122 */ 123 public String getSubject() { 124 return subject; 125 } 126 127 /** 128 * Converts the SimpleNNTPHeader to a properly formatted header in the form of a String, including the blank line used to separate the header from the 129 * article body. 130 * <p> 131 * 132 * @return The article header in the form of a String. 133 */ 134 @Override 135 public String toString() { 136 final StringBuilder header = new StringBuilder(); 137 138 header.append("From: "); 139 header.append(from); 140 header.append("\nNewsgroups: "); 141 header.append(newsgroups.toString()); 142 header.append("\nSubject: "); 143 header.append(subject); 144 header.append('\n'); 145 if (headerFields.length() > 0) { 146 header.append(headerFields.toString()); 147 } 148 header.append('\n'); 149 150 return header.toString(); 151 } 152}