KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > turbine > util > mail > Email


1 package org.apache.turbine.util.mail;
2
3 /*
4  * Copyright 2001-2004 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 JavaDoc;
20 import java.util.Properties JavaDoc;
21 import java.util.Vector JavaDoc;
22
23 import javax.mail.Message JavaDoc;
24 import javax.mail.MessagingException JavaDoc;
25 import javax.mail.Session JavaDoc;
26 import javax.mail.Transport JavaDoc;
27
28 import javax.mail.internet.InternetAddress JavaDoc;
29 import javax.mail.internet.MimeMessage JavaDoc;
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,v 1.8.2.2 2004/05/20 03:20:18 seade Exp $
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 JavaDoc SENDER_EMAIL = "sender.email";
59     public static final String JavaDoc SENDER_NAME = "sender.name";
60     public static final String JavaDoc RECEIVER_EMAIL = "receiver.email";
61     public static final String JavaDoc RECEIVER_NAME = "receiver.name";
62     public static final String JavaDoc EMAIL_SUBJECT = "email.subject";
63     public static final String JavaDoc EMAIL_BODY = "email.body";
64     public static final String JavaDoc CONTENT_TYPE = "content.type";
65
66     /** @deprecated Use TurbineConstants.MAIL_SERVER_KEY */
67     public static final String JavaDoc MAIL_SERVER = TurbineConstants.MAIL_SERVER_KEY;
68
69     /** @deprecated Use TurbineConstants.MAIL_SMTP_FROM */
70     public static final String JavaDoc MAIL_SMTP_FROM = TurbineConstants.MAIL_SMTP_FROM;
71
72     /** Mail Host, for javax.mail */
73     public static final String JavaDoc MAIL_HOST = "mail.host";
74
75     public static final String JavaDoc MAIL_TRANSPORT_PROTOCOL = "mail.transport.protocol";
76     public static final String JavaDoc SMTP = "SMTP";
77     public static final String JavaDoc TEXT_HTML = "text/html";
78     public static final String JavaDoc TEXT_PLAIN = "text/plain";
79     public static final String JavaDoc ATTACHMENTS = "attachments";
80     public static final String JavaDoc FILE_SERVER = "file.server";
81
82     public static final String JavaDoc KOI8_R = "koi8-r";
83     public static final String JavaDoc ISO_8859_1 = "iso-8859-1";
84     public static final String JavaDoc US_ASCII = "us-ascii";
85
86     /** The email message to send. */
87     protected MimeMessage JavaDoc message;
88
89     /** The charset to use for this message */
90     protected String JavaDoc charset = null;
91
92     /** Lists of related email adresses */
93     private Vector JavaDoc toList;
94     private Vector JavaDoc ccList;
95     private Vector JavaDoc bccList;
96     private Vector JavaDoc replyList;
97
98     /**
99      * Set the charset of the message.
100      *
101      * @param charset A String.
102      */
103     public void setCharset(String JavaDoc charset)
104     {
105         this.charset = charset;
106     }
107
108     /**
109      * TODO: Document.
110      *
111      * @return A Session.
112      */
113     private Session JavaDoc getMailSession()
114     {
115         Configuration conf = Turbine.getConfiguration();
116         Properties JavaDoc 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 JavaDoc 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 JavaDoc
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 JavaDoc
156     {
157
158         // Create the message.
159 message = new MimeMessage JavaDoc(getMailSession());
160
161         toList = new Vector JavaDoc();
162         ccList = new Vector JavaDoc();
163         bccList = new Vector JavaDoc();
164         replyList = new Vector JavaDoc();
165
166         // Set the sent date.
167 setSentDate(new Date JavaDoc());
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 JavaDoc
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 JavaDoc email, String JavaDoc name) throws MessagingException JavaDoc
219     {
220         try
221         {
222             if (name == null || name.trim().equals(""))
223             {
224                 name = email;
225             }
226             message.setFrom(new InternetAddress JavaDoc(email, name));
227         }
228         catch (Exception JavaDoc e)
229         {
230             throw new MessagingException JavaDoc("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 JavaDoc email, String JavaDoc name) throws MessagingException JavaDoc
244     {
245         try
246         {
247             if (name == null || name.trim().equals(""))
248             {
249                 name = email;
250             }
251             toList.addElement(new InternetAddress JavaDoc(email, name));
252         }
253         catch (Exception JavaDoc e)
254         {
255             throw new MessagingException JavaDoc("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 JavaDoc email, String JavaDoc name) throws MessagingException JavaDoc
269     {
270
271         try
272         {
273             if (name == null || name.trim().equals(""))
274             {
275                 name = email;
276             }
277             ccList.addElement(new InternetAddress JavaDoc(email, name));
278         }
279         catch (Exception JavaDoc e)
280         {
281             throw new MessagingException JavaDoc("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 JavaDoc email, String JavaDoc name)
296             throws MessagingException JavaDoc
297     {
298         try
299         {
300             if (name == null || name.trim().equals(""))
301             {
302                 name = email;
303             }
304             bccList.addElement(new InternetAddress JavaDoc(email, name));
305         }
306         catch (Exception JavaDoc e)
307         {
308             throw new MessagingException JavaDoc("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 JavaDoc email, String JavaDoc name)
323             throws MessagingException JavaDoc
324     {
325         try
326         {
327             if (name == null || name.trim().equals(""))
328             {
329                 name = email;
330             }
331             replyList.addElement(new InternetAddress JavaDoc(email, name));
332         }
333         catch (Exception JavaDoc e)
334         {
335             throw new MessagingException JavaDoc("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 JavaDoc subject)
348             throws MessagingException JavaDoc
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 JavaDoc date)
372             throws MessagingException JavaDoc
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 JavaDoc msg)
390             throws MessagingException JavaDoc;
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 JavaDoc
399     {
400         InternetAddress JavaDoc[] foo = new InternetAddress JavaDoc[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 JavaDoc[] toInternetAddressArray(Vector JavaDoc v)
419     {
420         int size = v.size();
421         InternetAddress JavaDoc[] ia = new InternetAddress JavaDoc[size];
422         for (int i = 0; i < size; i++)
423         {
424             ia[i] = (InternetAddress JavaDoc) v.elementAt(i);
425         }
426         return ia;
427     }
428 }
429
Popular Tags