Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
VelocityHtmlEmail |
|
| 1.6;1,6 |
1 | package org.apache.turbine.util.velocity; | |
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 | ||
27 | import org.apache.commons.lang.StringUtils; | |
28 | import org.apache.commons.logging.Log; | |
29 | import org.apache.commons.logging.LogFactory; | |
30 | import org.apache.commons.mail.EmailException; | |
31 | import org.apache.commons.mail.HtmlEmail; | |
32 | import org.apache.turbine.Turbine; | |
33 | import org.apache.turbine.TurbineConstants; | |
34 | import org.apache.turbine.pipeline.PipelineData; | |
35 | import org.apache.turbine.services.velocity.TurbineVelocity; | |
36 | import org.apache.turbine.util.RunData; | |
37 | import org.apache.velocity.context.Context; | |
38 | ||
39 | /** | |
40 | * This is a simple class for sending html email from within Velocity. | |
41 | * Essentially, the bodies (text and html) of the email are a Velocity | |
42 | * Context objects. The beauty of this is that you can send email | |
43 | * from within your Velocity template or from your business logic in | |
44 | * your Java code. The body of the email is just a Velocity template | |
45 | * so you can use all the template functionality of Velocity within | |
46 | * your emails! | |
47 | * | |
48 | * <p>This class allows you to send HTML email with embedded content | |
49 | * and/or with attachments. You can access the VelocityHtmlEmail | |
50 | * instance within your templates trough the <code>$mail</code> | |
51 | * Velocity variable. | |
52 | * <p><code>VelocityHtmlEmail myEmail= new VelocityHtmlEmail(data);<br> | |
53 | * context.put("mail", myMail);</code> | |
54 | * <b>or</b> | |
55 | * <code>VelocityHtmlEmail myEmail= new VelocityHtmlEmail(context);<br> | |
56 | * context.put("mail", myMail);</code> | |
57 | * | |
58 | * | |
59 | * <p>The templates should be located under your Template turbine | |
60 | * directory. | |
61 | * | |
62 | * <p>This class wraps the HtmlEmail class from commons-email. Thus, it uses | |
63 | * the JavaMail API and also depends on having the mail.server property | |
64 | * set in the TurbineResources.properties file. If you want to use | |
65 | * this class outside of Turbine for general processing that is also | |
66 | * possible by making sure to set the path to the | |
67 | * TurbineResources.properties. See the | |
68 | * TurbineResourceService.setPropertiesFileName() method for more | |
69 | * information. | |
70 | * | |
71 | * <p>This class is basically a conversion of the WebMacroHtmlEmail | |
72 | * written by Regis Koenig | |
73 | * | |
74 | * <p>You can turn on debugging for the JavaMail API by calling | |
75 | * setDebug(true). The debugging messages will be written to System.out. | |
76 | * | |
77 | * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a> | |
78 | * @author <a href="mailto:A.Schild@aarboard.ch">Andre Schild</a> | |
79 | * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a> | |
80 | * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a> | |
81 | * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a> | |
82 | * @version $Id: VelocityHtmlEmail.java 929479 2010-03-31 11:24:21Z tv $ | |
83 | */ | |
84 | public class VelocityHtmlEmail extends HtmlEmail | |
85 | { | |
86 | /** Logging */ | |
87 | 0 | private static Log log = LogFactory.getLog(VelocityHtmlEmail.class); |
88 | ||
89 | /** | |
90 | * The html template to process, relative to VM's template | |
91 | * directory. | |
92 | */ | |
93 | 0 | private String htmlTemplate = null; |
94 | ||
95 | /** | |
96 | * The text template to process, relative to VM's template | |
97 | * directory. | |
98 | */ | |
99 | 0 | private String textTemplate = null; |
100 | ||
101 | /** The cached context object. */ | |
102 | 0 | private Context context = null; |
103 | ||
104 | /** The map of embedded files. */ | |
105 | 0 | private Hashtable embmap = null; |
106 | ||
107 | /** Address of outgoing mail server */ | |
108 | private String mailServer; | |
109 | ||
110 | /** | |
111 | * Constructor, sets the context object from the passed RunData object | |
112 | * @deprecated use PipelineData version instead | |
113 | * @param data A Turbine RunData object. | |
114 | */ | |
115 | public VelocityHtmlEmail(RunData data) | |
116 | 0 | { |
117 | 0 | this.context = TurbineVelocity.getContext(data); |
118 | 0 | embmap = new Hashtable(); |
119 | 0 | } |
120 | ||
121 | /** | |
122 | * Constructor, sets the context object from the passed RunData object | |
123 | * | |
124 | * @param data A Turbine RunData object. | |
125 | */ | |
126 | public VelocityHtmlEmail(PipelineData pipelineData) | |
127 | 0 | { |
128 | 0 | this.context = TurbineVelocity.getContext(pipelineData); |
129 | 0 | embmap = new Hashtable(); |
130 | 0 | } |
131 | ||
132 | /** | |
133 | * Constructor, sets the context object. | |
134 | * | |
135 | * @param context A Velocity context object. | |
136 | */ | |
137 | public VelocityHtmlEmail(Context context) | |
138 | 0 | { |
139 | 0 | this.context = context; |
140 | 0 | embmap = new Hashtable(); |
141 | 0 | } |
142 | ||
143 | /** | |
144 | * Set the HTML template for the mail. This is the Velocity | |
145 | * template to execute for the HTML part. Path is relative to the | |
146 | * VM templates directory. | |
147 | * | |
148 | * @param template A String. | |
149 | * @return A VelocityHtmlEmail (self). | |
150 | */ | |
151 | public VelocityHtmlEmail setHtmlTemplate(String template) | |
152 | { | |
153 | 0 | this.htmlTemplate = template; |
154 | 0 | return this; |
155 | } | |
156 | ||
157 | /** | |
158 | * Set the text template for the mail. This is the Velocity | |
159 | * template to execute for the text part. Path is relative to the | |
160 | * VM templates directory | |
161 | * | |
162 | * @param template A String. | |
163 | * @return A VelocityHtmlEmail (self). | |
164 | */ | |
165 | public VelocityHtmlEmail setTextTemplate(String template) | |
166 | { | |
167 | 0 | this.textTemplate = template; |
168 | 0 | return this; |
169 | } | |
170 | ||
171 | /** | |
172 | * Sets the address of the outgoing mail server. This method | |
173 | * should be used when you need to override the value stored in | |
174 | * TR.props. | |
175 | * | |
176 | * @param serverAddress host name of your outgoing mail server | |
177 | */ | |
178 | public void setMailServer(String serverAddress) | |
179 | { | |
180 | 0 | this.mailServer = serverAddress; |
181 | 0 | } |
182 | ||
183 | /** | |
184 | * Gets the host name of the outgoing mail server. If the server | |
185 | * name has not been set by calling setMailServer(), the value | |
186 | * from TR.props for mail.server will be returned. If TR.props | |
187 | * has no value for mail.server, localhost will be returned. | |
188 | * | |
189 | * @return host name of the mail server. | |
190 | */ | |
191 | public String getMailServer() | |
192 | { | |
193 | 0 | return StringUtils.isNotEmpty(mailServer) ? mailServer |
194 | : Turbine.getConfiguration().getString( | |
195 | TurbineConstants.MAIL_SERVER_KEY, | |
196 | TurbineConstants.MAIL_SERVER_DEFAULT); | |
197 | } | |
198 | ||
199 | /** | |
200 | * Actually send the mail. | |
201 | * | |
202 | * @exception EmailException thrown if mail cannot be sent. | |
203 | */ | |
204 | public String send() throws EmailException | |
205 | { | |
206 | 0 | context.put("mail", this); |
207 | ||
208 | try | |
209 | { | |
210 | 0 | if (htmlTemplate != null) |
211 | { | |
212 | 0 | setHtmlMsg( |
213 | TurbineVelocity.handleRequest(context, htmlTemplate)); | |
214 | } | |
215 | 0 | if (textTemplate != null) |
216 | { | |
217 | 0 | setTextMsg( |
218 | TurbineVelocity.handleRequest(context, textTemplate)); | |
219 | } | |
220 | } | |
221 | 0 | catch (Exception e) |
222 | { | |
223 | 0 | throw new EmailException("Cannot parse velocity template", e); |
224 | 0 | } |
225 | 0 | setHostName(getMailServer()); |
226 | 0 | return super.send(); |
227 | } | |
228 | ||
229 | /** | |
230 | * Embed a file in the mail. The file can be referenced through | |
231 | * its Content-ID. This function also registers the CID in an | |
232 | * internal map, so the embedded file can be referenced more than | |
233 | * once by using the getCid() function. This may be useful in a | |
234 | * template. | |
235 | * | |
236 | * <p>Example of template: | |
237 | * | |
238 | * <code><pre width="80"> | |
239 | * <html> | |
240 | * <!-- $mail.embed("http://server/border.gif","border.gif"); --> | |
241 | * <img src=$mail.getCid("border.gif")> | |
242 | * <p>This is your content | |
243 | * <img src=$mail.getCid("border.gif")> | |
244 | * </html> | |
245 | * </pre></code> | |
246 | * | |
247 | * @param surl A String. | |
248 | * @param name A String. | |
249 | * @return A String with the cid of the embedded file. | |
250 | * | |
251 | * @see HtmlEmail#embed(URL surl, String name) embed. | |
252 | */ | |
253 | public String embed(String surl, String name) | |
254 | { | |
255 | 0 | String cid = ""; |
256 | try | |
257 | { | |
258 | 0 | URL url = new URL(surl); |
259 | 0 | cid = embed(url, name); |
260 | } | |
261 | 0 | catch (Exception e) |
262 | { | |
263 | 0 | log.error("cannot embed " + surl + ": ", e); |
264 | 0 | } |
265 | 0 | return cid; |
266 | } | |
267 | ||
268 | /** | |
269 | * Get the cid of an embedded file. | |
270 | * | |
271 | * @param filename A String. | |
272 | * @return A String with the cid of the embedded file. | |
273 | * @see #embed(String surl, String name) embed. | |
274 | */ | |
275 | public String getCid(String filename) | |
276 | { | |
277 | 0 | String cid = (String) embmap.get(filename); |
278 | 0 | return "cid:" + cid; |
279 | } | |
280 | ||
281 | } |