View Javadoc

1   package org.apache.turbine.util.mail;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import java.util.Date;
20  import java.util.Properties;
21  import java.util.Vector;
22  
23  import javax.mail.Message;
24  import javax.mail.MessagingException;
25  import javax.mail.Session;
26  import javax.mail.Transport;
27  
28  import javax.mail.internet.InternetAddress;
29  import javax.mail.internet.MimeMessage;
30  
31  import org.apache.commons.configuration.Configuration;
32  
33  import org.apache.commons.lang.StringUtils;
34  
35  import org.apache.torque.util.Criteria;
36  
37  import org.apache.turbine.Turbine;
38  import org.apache.turbine.TurbineConstants;
39  
40  /***
41   * The base class for all email messages.  This class sets the
42   * sender's email & name, receiver's email & name, subject, and the
43   * sent date.  Subclasses are responsible for setting the message
44   * body.
45   *
46   * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
47   * @author <a href="mailto:frank.kim@clearink.com">Frank Y. Kim</a>
48   * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
49   * @author <a href="mailto:greg@shwoop.com">Greg Ritter</a>
50   * @author <a href="mailto:unknown">Regis Koenig</a>
51   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
52   * @version $Id: Email.java 264148 2005-08-29 14:21:04Z henning $
53   * @deprecated Use org.apache.commons.mail.Email instead.
54   */
55  public abstract class Email
56  {
57      /*** Constants used to Email classes. */
58      public static final String SENDER_EMAIL = "sender.email";
59      public static final String SENDER_NAME = "sender.name";
60      public static final String RECEIVER_EMAIL = "receiver.email";
61      public static final String RECEIVER_NAME = "receiver.name";
62      public static final String EMAIL_SUBJECT = "email.subject";
63      public static final String EMAIL_BODY = "email.body";
64      public static final String CONTENT_TYPE = "content.type";
65  
66      /*** @deprecated Use TurbineConstants.MAIL_SERVER_KEY */
67      public static final String MAIL_SERVER = TurbineConstants.MAIL_SERVER_KEY;
68  
69      /*** @deprecated Use TurbineConstants.MAIL_SMTP_FROM */
70      public static final String MAIL_SMTP_FROM = TurbineConstants.MAIL_SMTP_FROM;
71  
72      /*** Mail Host, for javax.mail */
73      public static final String MAIL_HOST = "mail.host";
74  
75      public static final String MAIL_TRANSPORT_PROTOCOL = "mail.transport.protocol";
76      public static final String SMTP = "SMTP";
77      public static final String TEXT_HTML = "text/html";
78      public static final String TEXT_PLAIN = "text/plain";
79      public static final String ATTACHMENTS = "attachments";
80      public static final String FILE_SERVER = "file.server";
81  
82      public static final String KOI8_R = "koi8-r";
83      public static final String ISO_8859_1 = "iso-8859-1";
84      public static final String US_ASCII = "us-ascii";
85  
86      /*** The email message to send. */
87      protected MimeMessage message;
88  
89      /*** The charset to use for this message */
90      protected String charset = null;
91  
92      /*** Lists of related email adresses */
93      private Vector toList;
94      private Vector ccList;
95      private Vector bccList;
96      private Vector replyList;
97  
98      /***
99       * Set the charset of the message.
100      *
101      * @param charset A String.
102      */
103     public void setCharset(String charset)
104     {
105         this.charset = charset;
106     }
107 
108     /***
109      * TODO: Document.
110      *
111      * @return A Session.
112      */
113     private Session getMailSession()
114     {
115         Configuration conf = Turbine.getConfiguration();
116         Properties properties = System.getProperties();
117 
118         properties.put(MAIL_TRANSPORT_PROTOCOL, SMTP);
119         properties.put(MAIL_HOST, conf.getString(TurbineConstants.MAIL_SERVER_KEY,
120                                                  TurbineConstants.MAIL_SERVER_DEFAULT));
121 
122 
123         String mailSMTPFrom = conf.getString(TurbineConstants.MAIL_SMTP_FROM);
124 
125         if (StringUtils.isNotEmpty(mailSMTPFrom))
126         {
127             properties.put(TurbineConstants.MAIL_SMTP_FROM, mailSMTPFrom);
128         }
129         return Session.getDefaultInstance(properties, null);
130     }
131 
132     /***
133      * Initializes the mail.
134      *
135      * Deprecated.
136      *
137      * @param criteria A Criteria.
138      * @exception MessagingException.
139      * @see #init() init.
140      */
141     protected void initialize(Criteria criteria) throws MessagingException
142     {
143         init();
144         initCriteria(criteria);
145     }
146 
147     /***
148      * Initializes the mail.
149      *
150      * <p>This is the first method that should be called by a subclass
151      * in its constructor.
152      *
153      * @exception MessagingException.
154      */
155     protected void init() throws MessagingException
156     {
157 
158         // Create the message.
159         message = new MimeMessage(getMailSession());
160 
161         toList = new Vector();
162         ccList = new Vector();
163         bccList = new Vector();
164         replyList = new Vector();
165 
166         // Set the sent date.
167         setSentDate(new Date());
168     }
169 
170     /***
171      * Initialize the mail according to the Criteria.
172      *
173      * <p>This method uses the criteria parameter to set the from, to
174      * and subject fields of the email.
175      *
176      * Deprecated; one should use the setFrom, addTo, etc. methods.
177      *
178      * @param criteria A Criteria.
179      * @exception MessagingException.
180      */
181     protected void initCriteria(Criteria criteria) throws MessagingException
182     {
183         // Set the FROM field.
184         if (criteria.containsKey(SENDER_EMAIL)
185                 && criteria.containsKey(SENDER_NAME))
186         {
187             setFrom(criteria.getString(SENDER_EMAIL),
188                     criteria.getString(SENDER_NAME));
189         }
190 
191         // Set the TO field.
192         if (criteria.containsKey(RECEIVER_EMAIL)
193                 && criteria.containsKey(RECEIVER_NAME))
194         {
195             addTo(criteria.getString(RECEIVER_EMAIL),
196                     criteria.getString(RECEIVER_NAME));
197         }
198 
199         // Set the SUBJECT field.
200         if (criteria.containsKey(EMAIL_SUBJECT))
201         {
202             setSubject(criteria.getString(EMAIL_SUBJECT));
203         }
204         else
205         {
206             setSubject("no subject available");
207         }
208     }
209 
210     /***
211      * Set the FROM field of the email.
212      *
213      * @param email A String.
214      * @param name A String.
215      * @return An Email.
216      * @exception MessagingException.
217      */
218     public Email setFrom(String email, String name) throws MessagingException
219     {
220         try
221         {
222             if (name == null || name.trim().equals(""))
223             {
224                 name = email;
225             }
226             message.setFrom(new InternetAddress(email, name));
227         }
228         catch (Exception e)
229         {
230             throw new MessagingException("cannot set from", e);
231         }
232         return this;
233     }
234 
235     /***
236      * Add a recipient TO to the email.
237      *
238      * @param email A String.
239      * @param name A String.
240      * @return An Email.
241      * @exception MessagingException.
242      */
243     public Email addTo(String email, String name) throws MessagingException
244     {
245         try
246         {
247             if (name == null || name.trim().equals(""))
248             {
249                 name = email;
250             }
251             toList.addElement(new InternetAddress(email, name));
252         }
253         catch (Exception e)
254         {
255             throw new MessagingException("cannot add to", e);
256         }
257         return this;
258     }
259 
260     /***
261      * Add a recipient CC to the email.
262      *
263      * @param email A String.
264      * @param name A String.
265      * @return An Email.
266      * @exception MessagingException.
267      */
268     public Email addCc(String email, String name) throws MessagingException
269     {
270 
271         try
272         {
273             if (name == null || name.trim().equals(""))
274             {
275                 name = email;
276             }
277             ccList.addElement(new InternetAddress(email, name));
278         }
279         catch (Exception e)
280         {
281             throw new MessagingException("cannot add cc", e);
282         }
283 
284         return this;
285     }
286 
287     /***
288      * Add a blind BCC recipient to the email.
289      *
290      * @param email A String.
291      * @param name A String.
292      * @return An Email.
293      * @exception MessagingException.
294      */
295     public Email addBcc(String email, String name)
296             throws MessagingException
297     {
298         try
299         {
300             if (name == null || name.trim().equals(""))
301             {
302                 name = email;
303             }
304             bccList.addElement(new InternetAddress(email, name));
305         }
306         catch (Exception e)
307         {
308             throw new MessagingException("cannot add bcc", e);
309         }
310 
311         return this;
312     }
313 
314     /***
315      * Add a reply to address to the email.
316      *
317      * @param email A String.
318      * @param name A String.
319      * @return An Email.
320      * @exception MessagingException.
321      */
322     public Email addReplyTo(String email, String name)
323             throws MessagingException
324     {
325         try
326         {
327             if (name == null || name.trim().equals(""))
328             {
329                 name = email;
330             }
331             replyList.addElement(new InternetAddress(email, name));
332         }
333         catch (Exception e)
334         {
335             throw new MessagingException("cannot add replyTo", e);
336         }
337         return this;
338     }
339 
340     /***
341      * Set the email subject.
342      *
343      * @param subject A String.
344      * @return An Email.
345      * @exception MessagingException.
346      */
347     public Email setSubject(String subject)
348             throws MessagingException
349     {
350         if (subject != null)
351         {
352             if (charset != null)
353             {
354                 message.setSubject(subject, charset);
355             }
356             else
357             {
358                 message.setSubject(subject);
359             }
360         }
361         return this;
362     }
363 
364     /***
365      * Set the sent date field.
366      *
367      * @param date A Date.
368      * @return An Email.
369      * @exception MessagingException.
370      */
371     public Email setSentDate(Date date)
372             throws MessagingException
373     {
374         if (date != null)
375         {
376             message.setSentDate(date);
377         }
378         return this;
379     }
380 
381     /***
382      * Define the content of the mail.  It should be overidden by the
383      * subclasses.
384      *
385      * @param msg A String.
386      * @return An Email.
387      * @exception MessagingException.
388      */
389     public abstract Email setMsg(String msg)
390             throws MessagingException;
391 
392     /***
393      * Does the work of actually sending the email.
394      *
395      * @exception MessagingException, if there was an error.
396      */
397     public void send()
398             throws MessagingException
399     {
400         InternetAddress[] foo = new InternetAddress[0];
401         message.setRecipients(Message.RecipientType.TO,
402                 toInternetAddressArray(toList));
403         message.setRecipients(Message.RecipientType.CC,
404                 toInternetAddressArray(ccList));
405         message.setRecipients(Message.RecipientType.BCC,
406                 toInternetAddressArray(bccList));
407         message.setReplyTo(toInternetAddressArray(replyList));
408         Transport.send(message);
409     }
410 
411     /***
412      * Utility to copy Vector of known InternetAddress objects into an
413      * array.
414      *
415      * @param v A Vector.
416      * @return An InternetAddress[].
417      */
418     private InternetAddress[] toInternetAddressArray(Vector v)
419     {
420         int size = v.size();
421         InternetAddress[] ia = new InternetAddress[size];
422         for (int i = 0; i < size; i++)
423         {
424             ia[i] = (InternetAddress) v.elementAt(i);
425         }
426         return ia;
427     }
428 }