    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            }
    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    }