    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 * <p>
    044 * <p>
    045 * @see NNTPClient
    046 ***/
    047
    048public class SimpleNNTPHeader
    049{
    050    private final String __subject, __from;
    051    private final StringBuilder __newsgroups;
    052    private final StringBuilder __headerFields;
    053    private int __newsgroupCount;
    054
    055    /***
    056     * Creates a new SimpleNNTPHeader instance initialized with the given
    057     * from and subject header field values.
    058     * <p>
    059     * @param from  The value of the <code>From:</code> header field.  This
    060     *              should be the article poster's email address.
    061     * @param subject  The value of the <code>Subject:</code> header field.
    062     *              This should be the subject of the article.
    063     ***/
    064    public SimpleNNTPHeader(String from, String subject)
    065    {
    066        __from = from;
    067        __subject = subject;
    068        __newsgroups = new StringBuilder();
    069        __headerFields = new StringBuilder();
    070        __newsgroupCount = 0;
    071    }
    072
    073    /***
    074     * Adds a newsgroup to the article <code>Newsgroups:</code> field.
    075     * <p>
    076     * @param newsgroup  The newsgroup to add to the article's newsgroup
    077     *                   distribution list.
    078     ***/
    079    public void addNewsgroup(String newsgroup)
    080    {
    081        if (__newsgroupCount++ > 0) {
    082            __newsgroups.append(',');
    083        }
    084        __newsgroups.append(newsgroup);
    085    }
    086
    087    /***
    088     * Adds an arbitrary header field with the given value to the article
    089     * header.  These headers will be written after the From, Newsgroups,
    090     * and Subject fields when the SimpleNNTPHeader is convertered to a string.
    091     * An example use would be:
    092     * <pre>
    093     * header.addHeaderField("Organization", "Foobar, Inc.");
    094     * </pre>
    095     * <p>
    096     * @param headerField  The header field to add, not including the colon.
    097     * @param value  The value of the added header field.
    098     ***/
    099    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}