    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.smtp;
    019
    020/***
    021 * This class is used to construct a bare minimum
    022 * acceptable header for an email message.  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 mail sending
    028 * process, by relieving the programmer from having to explicitly format
    029 * a simple message header.  For example:
    030 * <pre>
    031 * writer = client.sendMessageData();
    032 * if(writer == null) // failure
    033 *   return false;
    034 * header =
    035 *    new SimpleSMTPHeader("foobar@foo.com", "foo@bar.com" "Just testing");
    036 * header.addCC("bar@foo.com");
    037 * header.addHeaderField("Organization", "Foobar, Inc.");
    038 * writer.write(header.toString());
    039 * writer.write("This is just a test");
    040 * writer.close();
    041 * if(!client.completePendingCommand()) // failure
    042 *   return false;
    043 * </pre>
    044 * <p>
    045 * <p>
    046 * @see SMTPClient
    047 ***/
    048
    049public class SimpleSMTPHeader
    050{
    051    private final String __subject, __from, __to;
    052    private final StringBuffer __headerFields;
    053    private StringBuffer __cc;
    054
    055    /***
    056     * Creates a new SimpleSMTPHeader instance initialized with the given
    057     * from, to, and subject header field values.
    058     * <p>
    059     * @param from  The value of the <code>From:</code> header field.  This
    060     *              should be the sender's email address.
    061     * @param to    The value of the <code>To:</code> header field.  This
    062     *              should be the recipient's email address.
    063     * @param subject  The value of the <code>Subject:</code> header field.
    064     *              This should be the subject of the message.
    065     ***/
    066    public SimpleSMTPHeader(String from, String to, String subject)
    067    {
    068        __to = to;
    069        __from = from;
    070        __subject = subject;
    071        __headerFields = new StringBuffer();
    072        __cc = null;
    073    }
    074
    075    /***
    076     * Adds an arbitrary header field with the given value to the article
    077     * header.  These headers will be written before the From, To, Subject, and
    078     * Cc fields when the SimpleSMTPHeader is convertered to a string.
    079     * An example use would be:
    080     * <pre>
    081     * header.addHeaderField("Organization", "Foobar, Inc.");
    082     * </pre>
    083     * <p>
    084     * @param headerField  The header field to add, not including the colon.
    085     * @param value  The value of the added header field.
    086     ***/
    087    public void addHeaderField(String headerField, String value)
    088    {
    089        __headerFields.append(headerField);
    090        __headerFields.append(": ");
    091        __headerFields.append(value);
    092        __headerFields.append('\n');
    093    }
    094
    095
    096    /***
    097     * Add an email address to the CC (carbon copy or courtesy copy) list.
    098     * <p>
    099     * @param address The email address to add to the CC list.
    100     ***/
    101    public void addCC(String address)
    102    {
    103        if (__cc == null) {
    104            __cc = new StringBuffer();
    105        } else {
    106            __cc.append(", ");
    107        }
    108
    109        __cc.append(address);
    110    }
    111
    112
    113    /***
    114     * Converts the SimpleSMTPHeader to a properly formatted header in
    115     * the form of a String, including the blank line used to separate
    116     * the header from the article body.  The header fields CC and Subject
    117     * are only included when they are non-null.
    118     * <p>
    119     * @return The message header in the form of a String.
    120     ***/
    121    @Override
    122    public String toString()
    123    {
    124        StringBuilder header = new StringBuilder();
    125
    126        if (__headerFields.length() > 0) {
    127            header.append(__headerFields.toString());
    128        }
    129
    130        header.append("From: ");
    131        header.append(__from);
    132        header.append("\nTo: ");
    133        header.append(__to);
    134
    135        if (__cc != null)
    136        {
    137            header.append("\nCc: ");
    138            header.append(__cc.toString());
    139        }
    140
    141        if (__subject != null)
    142        {
    143            header.append("\nSubject: ");
    144            header.append(__subject);
    145        }
    146
    147        header.append('\n');
    148        header.append('\n');
    149
    150        return header.toString();
    151    }
    152}
    153
    154
    155