1 package org.apache.fulcrum.template;
2
3
4 /*
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
20 * under the License.
21 */
22
23
24 import java.net.URL;
25 import java.util.Hashtable;
26 import javax.mail.MessagingException;
27
28 import org.apache.commons.mail.EmailException;
29 import org.apache.commons.mail.HtmlEmail;
30
31 /**
32 * This is a simple class for sending html email from within the TemplateService.
33 * Essentially, the bodies (text and html) of the email are a TemplateService
34 * TemplateContext objects. The beauty of this is that you can send email
35 * from within your TemplateService template or from your business logic in
36 * your Java code. The body of the email is just a TemplateService template
37 * so you can use all the template functionality of your TemplateService within
38 * your emails!
39 *
40 * <p>This class allows you to send HTML email with embedded content
41 * and/or with attachments. You can access the TemplateHtmlEmail
42 * instance within your templates trough the <code>$mail</code>
43 * Velocity variable.
44 * <p><code>TemplateHtmlEmail myEmail= new TemplateHtmlEmail(context);<br>
45 * context.put("mail", theMessage);</code>
46 *
47 *
48 * <p>The templates should be located under your TemplateService template
49 * directory.
50 *
51 * <p>This class extends the HtmlEmail class. Thus, it uses the
52 * JavaMail API and also depends on having the mail.host property
53 * set in the System.getProperties().
54 *
55 * @author <a href="mailto:A.Schild@aarboard.ch">Andre Schild</a>
56 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
57 * @version $Id: TemplateHtmlEmail.java 535465 2007-05-05 06:58:06Z tv $
58 */
59 public class TemplateHtmlEmail
60 extends HtmlEmail
61 {
62 /**
63 * The html template to process, relative to VM's template
64 * directory.
65 */
66 private String htmlTemplate = null;
67
68 /**
69 * A Context object which stores the information
70 * needed to construct the email.
71 */
72 private TemplateContext context = null;
73
74 /**
75 * The text template to process, relative to VM's template
76 * directory.
77 */
78 private String textTemplate = null;
79
80 /** The map of embedded files. */
81 private Hashtable embmap = null;
82
83 /**
84 * The templateService to use in generating text
85 *
86 */
87 private TemplateService templateService;
88
89 /**
90 * Constructor, sets the TemplateContext object.
91 *
92 * @param data A TemplateContext object.
93 * @exception MessagingException.
94 */
95 public TemplateHtmlEmail(TemplateContext context)
96 throws MessagingException
97 {
98 this.context = context;
99 embmap = new Hashtable();
100 }
101
102 /**
103 * Set the HTML template for the mail. This is the TemplateService
104 * template to execute for the HTML part. Path is relative to the
105 * TemplateService templates directory.
106 *
107 * @param template A String.
108 * @return A TemplateHtmlEmail (self).
109 */
110 public TemplateHtmlEmail setHtmlTemplate(String template)
111 {
112 this.htmlTemplate = template;
113 return this;
114 }
115
116 /**
117 * Set the text template for the mail. This is the TemplateService
118 * template to execute for the text part. Path is relative to the
119 * TemplateService templates directory
120 *
121 * @param template A String.
122 * @return A TemplateHtmlEmail (self).
123 */
124 public TemplateHtmlEmail setTextTemplate(String template)
125 {
126 this.textTemplate = template;
127 return this;
128 }
129
130 /**
131 * Actually send the mail.
132 *
133 * @return the message id of the sent email
134 * @exception EmailException the sending of the message failed
135 */
136 public String send()
137 throws EmailException
138 {
139 context.put("mail",this);
140
141 String htmlbody = "";
142 String textbody = "";
143
144 // Process the templates.
145 try
146 {
147 if(htmlTemplate != null)
148 {
149 htmlbody = templateService.handleRequest(
150 context, htmlTemplate);
151 }
152
153 if(textTemplate != null)
154 {
155 textbody = templateService.handleRequest(
156 context, textTemplate);
157 }
158 }
159 catch( Exception e)
160 {
161 throw new EmailException("Cannot parse template", e);
162 }
163
164 setHtmlMsg(htmlbody);
165 setTextMsg(textbody);
166
167 return super.send();
168 }
169
170 /**
171 * Embed a file in the mail. The file can be referenced through
172 * its Content-ID. This function also registers the CID in an
173 * internal map, so the embedded file can be referenced more than
174 * once by using the getCid() function. This may be useful in a
175 * template.
176 *
177 * <p>Example of template:
178 *
179 * <code><pre width="80">
180 * <html>
181 * <!-- $mail.embed("http://server/border.gif","border.gif"); -->
182 * <img src=$mail.getCid("border.gif")>
183 * <p>This is your content
184 * <img src=$mail.getCid("border.gif")>
185 * </html>
186 * </pre></code>
187 *
188 * @param surl A String.
189 * @param name A String.
190 * @return A String with the cid of the embedded file.
191 * @exception EmailException.
192 * @see HtmlEmail#embed(URL surl, String name) embed.
193 */
194 public String embed(String surl,
195 String name)
196 throws EmailException
197 {
198 String cid ="";
199 try
200 {
201 URL url = new URL(surl);
202 cid = super.embed(url, name);
203 embmap.put(name,cid);
204 }
205 catch( Exception e )
206 {
207 // Log.error("cannot embed "+surl+": ", e);
208 }
209 return cid;
210 }
211
212 /**
213 * Get the cid of an embedded file.
214 *
215 * @param filename A String.
216 * @return A String with the cid of the embedded file.
217 * @see #embed(String surl, String name) embed.
218 */
219 public String getCid(String filename)
220 {
221 String cid = (String)embmap.get(filename);
222 return "cid:"+cid;
223 }
224
225 /**
226 * A javabean style setter for passing in manually a templateservice
227 * @param templateService The templateService to set.
228 */
229 public void setTemplateService(TemplateService templateService) {
230 this.templateService = templateService;
231 }
232 }
233