    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
    018    package 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
    048    public class SimpleNNTPHeader
    049    {
    050        private String __subject, __from;
    051        private StringBuilder __newsgroups;
    052        private 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            __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(String headerField, 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            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            header.append('\n');
    160
    161            return header.toString();
    162        }
    163    }