View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package org.apache.commons.net.smtp;
19  
20  /***
21   * This class is used to construct a bare minimum
22   * acceptable header for an email message.  To construct more
23   * complicated headers you should refer to RFC 822.  When the
24   * Java Mail API is finalized, you will be
25   * able to use it to compose fully compliant Internet text messages.
26   * <p>
27   * The main purpose of the class is to faciliatate the mail sending
28   * process, by relieving the programmer from having to explicitly format
29   * a simple message header.  For example:
30   * <pre>
31   * writer = client.sendMessageData();
32   * if(writer == null) // failure
33   *   return false;
34   * header =
35   *    new SimpleSMTPHeader("foobar@foo.com", "foo@bar.com" "Just testing");
36   * header.addCC("bar@foo.com");
37   * header.addHeaderField("Organization", "Foobar, Inc.");
38   * writer.write(header.toString());
39   * writer.write("This is just a test");
40   * writer.close();
41   * if(!client.completePendingCommand()) // failure
42   *   return false;
43   * </pre>
44   * <p>
45   * <p>
46   * @see SMTPClient
47   ***/
48  
49  public class SimpleSMTPHeader
50  {
51      private final String __subject, __from, __to;
52      private final StringBuffer __headerFields;
53      private StringBuffer __cc;
54  
55      /***
56       * Creates a new SimpleSMTPHeader instance initialized with the given
57       * from, to, and subject header field values.
58       * <p>
59       * @param from  The value of the <code>From:</code> header field.  This
60       *              should be the sender's email address.
61       * @param to    The value of the <code>To:</code> header field.  This
62       *              should be the recipient's email address.
63       * @param subject  The value of the <code>Subject:</code> header field.
64       *              This should be the subject of the message.
65       ***/
66      public SimpleSMTPHeader(String from, String to, String subject)
67      {
68          __to = to;
69          __from = from;
70          __subject = subject;
71          __headerFields = new StringBuffer();
72          __cc = null;
73      }
74  
75      /***
76       * Adds an arbitrary header field with the given value to the article
77       * header.  These headers will be written before the From, To, Subject, and
78       * Cc fields when the SimpleSMTPHeader is convertered to a string.
79       * An example use would be:
80       * <pre>
81       * header.addHeaderField("Organization", "Foobar, Inc.");
82       * </pre>
83       * <p>
84       * @param headerField  The header field to add, not including the colon.
85       * @param value  The value of the added header field.
86       ***/
87      public void addHeaderField(String headerField, String value)
88      {
89          __headerFields.append(headerField);
90          __headerFields.append(": ");
91          __headerFields.append(value);
92          __headerFields.append('\n');
93      }
94  
95  
96      /***
97       * Add an email address to the CC (carbon copy or courtesy copy) list.
98       * <p>
99       * @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