%line | %branch | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
org.apache.turbine.util.velocity.VelocityEmail |
|
|
1 | package org.apache.turbine.util.velocity; |
|
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 javax.mail.MessagingException; |
|
20 | ||
21 | import org.apache.commons.lang.StringUtils; |
|
22 | ||
23 | import org.apache.commons.logging.Log; |
|
24 | import org.apache.commons.logging.LogFactory; |
|
25 | ||
26 | import org.apache.commons.mail.SimpleEmail; |
|
27 | ||
28 | import org.apache.turbine.Turbine; |
|
29 | import org.apache.turbine.TurbineConstants; |
|
30 | import org.apache.turbine.services.velocity.TurbineVelocity; |
|
31 | ||
32 | import org.apache.velocity.context.Context; |
|
33 | ||
34 | /** |
|
35 | * This is a simple class for sending email from within Velocity. |
|
36 | * Essentially, the body of the email is processed with a |
|
37 | * Velocity Context object. |
|
38 | * The beauty of this is that you can send email from within your |
|
39 | * Velocity template or from your business logic in your Java code. |
|
40 | * The body of the email is just a Velocity template so you can use |
|
41 | * all the template functionality of Velocity within your emails! |
|
42 | * |
|
43 | * <p>Example Usage (This all needs to be on one line in your |
|
44 | * template): |
|
45 | * |
|
46 | * <p>Setup your context: |
|
47 | * |
|
48 | * <p><code>context.put ("VelocityEmail", new VelocityEmail() );</code> |
|
49 | * |
|
50 | * <p>Then, in your template: |
|
51 | * |
|
52 | * <pre> |
|
53 | * $VelocityEmail.setTo("Jon Stevens", "jon@latchkey.com") |
|
54 | * .setFrom("Mom", "mom@mom.com").setSubject("Eat dinner") |
|
55 | * .setTemplate("email/momEmail.vm") |
|
56 | * .setContext($context) |
|
57 | * </pre> |
|
58 | * |
|
59 | * The email/momEmail.wm template will then be parsed with the |
|
60 | * Context that was defined with setContext(). |
|
61 | * |
|
62 | * <p>If you want to use this class from within your Java code all you |
|
63 | * have to do is something like this: |
|
64 | * |
|
65 | * <pre> |
|
66 | * VelocityEmail ve = new VelocityEmail(); |
|
67 | * ve.setTo("Jon Stevens", "jon@latchkey.com"); |
|
68 | * ve.setFrom("Mom", "mom@mom.com").setSubject("Eat dinner"); |
|
69 | * ve.setContext(context); |
|
70 | * ve.setTemplate("email/momEmail.vm") |
|
71 | * ve.send(); |
|
72 | * </pre> |
|
73 | * |
|
74 | * <p>(Note that when used within a Velocity template, the send method |
|
75 | * will be called for you when Velocity tries to convert the |
|
76 | * VelocityEmail to a string by calling toString()).</p> |
|
77 | * |
|
78 | * <p>If you need your email to be word-wrapped, you can add the |
|
79 | * following call to those above: |
|
80 | * |
|
81 | * <pre> |
|
82 | * ve.setWordWrap (60); |
|
83 | * </pre> |
|
84 | * |
|
85 | * <p>This class is just a wrapper around the SimpleEmail class from |
|
86 | * commons-mail using the JavaMail API. |
|
87 | * Thus, it depends on having the |
|
88 | * mail.server property set in the TurbineResources.properties file. |
|
89 | * If you want to use this class outside of Turbine for general |
|
90 | * processing that is also possible by making sure to set the path to |
|
91 | * the TurbineResources.properties. See the |
|
92 | * TurbineConfig class for more information.</p> |
|
93 | * |
|
94 | * <p>You can turn on debugging for the JavaMail API by calling |
|
95 | * setDebug(true). The debugging messages will be written to System.out. |
|
96 | * |
|
97 | * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a> |
|
98 | * @author <a href="mailto:gcoladonato@yahoo.com">Greg Coladonato</a> |
|
99 | * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a> |
|
100 | * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a> |
|
101 | * @version $Id: VelocityEmail.java,v 1.11.2.2 2004/05/20 03:28:01 seade Exp $ |
|
102 | */ |
|
103 | public class VelocityEmail extends SimpleEmail |
|
104 | { |
|
105 | /** Logging */ |
|
106 | 0 | private static Log log = LogFactory.getLog(VelocityEmail.class); |
107 | ||
108 | /** The column to word-wrap at. <code>0</code> indicates no wrap. */ |
|
109 | 0 | private int wordWrap = 0; |
110 | ||
111 | /** Address of outgoing mail server */ |
|
112 | private String mailServer; |
|
113 | ||
114 | /** The template to process, relative to Velocity template directory. */ |
|
115 | 0 | private String template = null; |
116 | ||
117 | /** Velocity context */ |
|
118 | 0 | private Context context = null; |
119 | ||
120 | /** |
|
121 | * Constructor |
|
122 | */ |
|
123 | public VelocityEmail() |
|
124 | 0 | { |
125 | 0 | } |
126 | ||
127 | /** |
|
128 | * Constructor |
|
129 | */ |
|
130 | public VelocityEmail(Context context) |
|
131 | 0 | { |
132 | 0 | this.context = context; |
133 | 0 | } |
134 | ||
135 | /** |
|
136 | * To: toName, toEmail |
|
137 | * |
|
138 | * @param toName A String with the TO toName. |
|
139 | * @param toEmail A String with the TO toEmail. |
|
140 | * @deprecated use addTo(email,name) instead |
|
141 | * @throws MessagingException email address could not be parsed |
|
142 | * @return A VelocityEmail (self). |
|
143 | */ |
|
144 | public VelocityEmail setTo(String toName, String toEmail) |
|
145 | throws MessagingException |
|
146 | { |
|
147 | 0 | addTo(toEmail,toName); |
148 | 0 | return this; |
149 | } |
|
150 | ||
151 | /** |
|
152 | * Velocity template to execute. Path is relative to the Velocity |
|
153 | * templates directory. |
|
154 | * |
|
155 | * @param template relative path of the template to parse including the |
|
156 | * filename. |
|
157 | * @return A VelocityEmail (self). |
|
158 | */ |
|
159 | public VelocityEmail setTemplate(String template) |
|
160 | { |
|
161 | 0 | this.template = template; |
162 | 0 | return this; |
163 | } |
|
164 | ||
165 | /** |
|
166 | * Set the column at which long lines of text should be word- |
|
167 | * wrapped. Setting to zero turns off word-wrap (default). |
|
168 | * |
|
169 | * NOTE: don't use tabs in your email template document, |
|
170 | * or your word-wrapping will be off for the lines with tabs |
|
171 | * in them. |
|
172 | * |
|
173 | * @param wordWrap The column at which to wrap long lines. |
|
174 | * @return A VelocityEmail (self). |
|
175 | */ |
|
176 | public VelocityEmail setWordWrap(int wordWrap) |
|
177 | { |
|
178 | 0 | this.wordWrap = wordWrap; |
179 | 0 | return this; |
180 | } |
|
181 | ||
182 | /** |
|
183 | * Set the context object that will be merged with the |
|
184 | * template. |
|
185 | * |
|
186 | * @param context A Velocity context object. |
|
187 | * @return A VelocityEmail (self). |
|
188 | */ |
|
189 | public VelocityEmail setContext(Context context) |
|
190 | { |
|
191 | 0 | this.context = context; |
192 | 0 | return this; |
193 | } |
|
194 | ||
195 | /** |
|
196 | * Get the context object that will be merged with the |
|
197 | * template. |
|
198 | * |
|
199 | * @return A Context (self). |
|
200 | */ |
|
201 | public Context getContext() |
|
202 | { |
|
203 | 0 | return this.context; |
204 | } |
|
205 | ||
206 | /** |
|
207 | * Sets the address of the outgoing mail server. This method |
|
208 | * should be used when you need to override the value stored in |
|
209 | * TR.props. |
|
210 | * |
|
211 | * @param serverAddress host name of your outgoing mail server |
|
212 | */ |
|
213 | public void setMailServer(String serverAddress) |
|
214 | { |
|
215 | 0 | this.mailServer = serverAddress; |
216 | 0 | } |
217 | ||
218 | /** |
|
219 | * Gets the host name of the outgoing mail server. If the server |
|
220 | * name has not been set by calling setMailServer(), the value |
|
221 | * from TR.props for mail.server will be returned. If TR.props |
|
222 | * has no value for mail.server, localhost will be returned. |
|
223 | * |
|
224 | * @return host name of the mail server. |
|
225 | */ |
|
226 | public String getMailServer() |
|
227 | { |
|
228 | 0 | return StringUtils.isNotEmpty(mailServer) ? mailServer |
229 | : Turbine.getConfiguration().getString( |
|
230 | TurbineConstants.MAIL_SERVER_KEY, |
|
231 | TurbineConstants.MAIL_SERVER_DEFAULT); |
|
232 | } |
|
233 | ||
234 | /** |
|
235 | * This method sends the email. |
|
236 | * <p>If the mail server was not set by calling, setMailServer() |
|
237 | * the value of mail.server will be used from TR.props. If that |
|
238 | * value was not set, localhost is used. |
|
239 | * |
|
240 | * @throws MessagingException Failure during merging the velocity |
|
241 | * template or sending the email. |
|
242 | */ |
|
243 | public void send() throws MessagingException |
|
244 | { |
|
245 | 0 | String body = null; |
246 | try |
|
247 | { |
|
248 | // Process the template. |
|
249 | 0 | body = TurbineVelocity.handleRequest(context, template); |
250 | } |
|
251 | 0 | catch (Exception e) |
252 | { |
|
253 | 0 | throw new MessagingException( |
254 | "Could not render velocitty template", e); |
|
255 | 0 | } |
256 | ||
257 | // If the caller desires word-wrapping, do it here |
|
258 | 0 | if (wordWrap > 0) |
259 | { |
|
260 | 0 | body = org.apache.turbine.util.StringUtils.wrapText(body, |
261 | System.getProperty("line.separator"), wordWrap); |
|
262 | } |
|
263 | ||
264 | 0 | setMsg(body); |
265 | 0 | setHostName(getMailServer()); |
266 | 0 | super.send(); |
267 | 0 | } |
268 | ||
269 | /** |
|
270 | * The method toString() calls send() for ease of use within a |
|
271 | * Velocity template (see example usage above). |
|
272 | * |
|
273 | * @return An empty string. |
|
274 | */ |
|
275 | public String toString() |
|
276 | { |
|
277 | try |
|
278 | { |
|
279 | 0 | send(); |
280 | } |
|
281 | 0 | catch (Exception e) |
282 | { |
|
283 | 0 | log.error("VelocityEmail error", e); |
284 | 0 | } |
285 | 0 | return ""; |
286 | } |
|
287 | } |
This report is generated by jcoverage, Maven and Maven JCoverage Plugin. |