1 package org.apache.turbine.util.velocity;
2
3 /* ====================================================================
4 * The Apache Software License, Version 1.1
5 *
6 * Copyright (c) 2001 The Apache Software Foundation. All rights
7 * reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * 1. Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 *
16 * 2. Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in
18 * the documentation and/or other materials provided with the
19 * distribution.
20 *
21 * 3. The end-user documentation included with the redistribution,
22 * if any, must include the following acknowledgment:
23 * "This product includes software developed by the
24 * Apache Software Foundation (http://www.apache.org/)."
25 * Alternately, this acknowledgment may appear in the software itself,
26 * if and wherever such third-party acknowledgments normally appear.
27 *
28 * 4. The names "Apache" and "Apache Software Foundation" and
29 * "Apache Turbine" must not be used to endorse or promote products
30 * derived from this software without prior written permission. For
31 * written permission, please contact apache@apache.org.
32 *
33 * 5. Products derived from this software may not be called "Apache",
34 * "Apache Turbine", nor may "Apache" appear in their name, without
35 * prior written permission of the Apache Software Foundation.
36 *
37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48 * SUCH DAMAGE.
49 * ====================================================================
50 *
51 * This software consists of voluntary contributions made by many
52 * individuals on behalf of the Apache Software Foundation. For more
53 * information on the Apache Software Foundation, please see
54 * <http://www.apache.org/>.
55 */
56
57 import org.apache.turbine.services.velocity.TurbineVelocity;
58 import org.apache.turbine.util.Log;
59 import org.apache.turbine.util.StringUtils;
60 import org.apache.turbine.util.mail.SimpleEmail;
61 import org.apache.velocity.context.Context;
62
63 /***
64 * This is a simple class for sending email from within Velocity.
65 * Essentially, the body of the email is processed with a
66 * Velocity Context object.
67 * The beauty of this is that you can send email from within your
68 * Velocity template or from your business logic in your Java code.
69 * The body of the email is just a Velocity template so you can use
70 * all the template functionality of Velocity within your emails!
71 *
72 * <p>Example Usage (This all needs to be on one line in your
73 * template):
74 *
75 * <p>Setup your context:
76 *
77 * <p>context.put ("VelocityEmail", new VelocityEmail() );
78 *
79 * <p>Then, in your template:
80 *
81 * <pre>
82 * $VelocityEmail.setTo("Jon Stevens", "jon@latchkey.com")
83 * .setFrom("Mom", "mom@mom.com").setSubject("Eat dinner")
84 * .setTemplate("email/momEmail.vm")
85 * .setContext($context)
86 * </pre>
87 *
88 * The email/momEmail.wm template will then be parsed with the
89 * Context that was defined with setContext().
90 *
91 * <p>If you want to use this class from within your Java code all you
92 * have to do is something like this:
93 *
94 * <pre>
95 * VelocityEmail ve = new VelocityEmail();
96 * ve.setTo("Jon Stevens", "jon@latchkey.com");
97 * ve.setFrom("Mom", "mom@mom.com").setSubject("Eat dinner");
98 * ve.setContext(context);
99 * ve.setTemplate("email/momEmail.vm")
100 * ve.send();
101 * </pre>
102 *
103 * <p>(Note that when used within a Velocity template, the send method
104 * will be called for you when Velocity tries to convert the
105 * VelocityEmail to a string by calling toString()).</p>
106 *
107 * <p>If you need your email to be word-wrapped, you can add the
108 * following call to those above:
109 *
110 * <pre>
111 * ve.setWordWrap (60);
112 * </pre>
113 *
114 * <p>This class is just a wrapper around the SimpleEmail class.
115 * Thus, it uses the JavaMail API and also depends on having the
116 * mail.server property set in the TurbineResources.properties file.
117 * If you want to use this class outside of Turbine for general
118 * processing that is also possible by making sure to set the path to
119 * the TurbineResources.properties. See the
120 * TurbineConfig class for more information.</p>
121 *
122 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
123 * @author <a href="mailto:gcoladonato@yahoo.com">Greg Coladonato</a>
124 * @version $Id: VelocityEmail.java,v 1.2 2002/07/11 16:53:19 mpoeschl Exp $
125 */
126 public class VelocityEmail
127 {
128 /*** The to name field. */
129 private String toName = null;
130
131 /*** The to email field. */
132 private String toEmail = null;
133
134 /*** The from name field. */
135 private String fromName = null;
136
137 /*** The from email field. */
138 private String fromEmail = null;
139
140 /*** The subject of the message. */
141 private String subject = null;
142
143 /*** The column to word-wrap at. <code>0</code> indicates no wrap. */
144 private int wordWrap = 0;
145
146 /***
147 * The template to process, relative to WM's template
148 * directory.
149 */
150 private String template = null;
151
152 /***
153 * A Context
154 */
155 private Context context = null;
156
157 /***
158 * Constructor
159 */
160 public VelocityEmail()
161 {
162 }
163
164 /***
165 * Constructor
166 */
167 public VelocityEmail(Context context)
168 {
169 this.context = context;
170 }
171
172 /***
173 * To: name, email
174 *
175 * @param to A String with the TO name.
176 * @param email A String with the TO email.
177 * @return A VelocityEmail (self).
178 */
179 public VelocityEmail setTo(String to, String email)
180 {
181 this.toName = to;
182 this.toEmail = email;
183 return (this);
184 }
185
186 /***
187 * From: name, email.
188 *
189 * @param from A String with the FROM name.
190 * @param email A String with the FROM email.
191 * @return A VelocityEmail (self).
192 */
193 public VelocityEmail setFrom(String from, String email)
194 {
195 this.fromName = from;
196 this.fromEmail = email;
197 return (this);
198 }
199
200 /***
201 * Subject.
202 *
203 * @param subject A String with the subject.
204 * @return A VelocityEmail (self).
205 */
206 public VelocityEmail setSubject(String subject)
207 {
208 this.subject = subject;
209 return (this);
210 }
211
212 /***
213 * Velocity template to execute. Path is relative to the Velocity
214 * templates directory.
215 *
216 * @param template A String with the template.
217 * @return A VelocityEmail (self).
218 */
219 public VelocityEmail setTemplate(String template)
220 {
221 this.template = template;
222 return (this);
223 }
224
225 /***
226 * Set the column at which long lines of text should be word-
227 * wrapped. Setting to zero turns off word-wrap (default).
228 *
229 * NOTE: don't use tabs in your email template document,
230 * or your word-wrapping will be off for the lines with tabs
231 * in them.
232 *
233 * @param wordWrap The column at which to wrap long lines.
234 * @return A VelocityEmail (self).
235 */
236 public VelocityEmail setWordWrap(int wordWrap)
237 {
238 this.wordWrap = wordWrap;
239 return (this);
240 }
241
242 /***
243 * Set the context object that will be merged with the
244 * template.
245 *
246 * @param context A Velocity context object.
247 * @return A VelocityEmail (self).
248 */
249 public VelocityEmail setContext(Context context)
250 {
251 this.context = context;
252 return (this);
253 }
254
255 /***
256 * Get the context object that will be merged with the
257 * template.
258 *
259 * @return A Context (self).
260 */
261 public Context getContext()
262 {
263 return this.context;
264 }
265
266 /***
267 * This method sends the email.
268 */
269 public void send()
270 throws Exception
271 {
272 // Process the template.
273 String body = TurbineVelocity.handleRequest(context,template);
274
275 // If the caller desires word-wrapping, do it here
276 if (wordWrap > 0)
277 {
278 body = StringUtils.wrapText(body,
279 System.getProperty("line.separator"), wordWrap);
280 }
281
282 SimpleEmail se = new SimpleEmail();
283 se.setFrom(fromEmail, fromName);
284 se.addTo(toEmail, toName);
285 se.setSubject(subject);
286 se.setMsg(body);
287 se.send();
288 }
289
290 /***
291 * The method toString() calls send() for ease of use within a
292 * Velocity template (see example usage above).
293 *
294 * @return An empty string.
295 */
296 public String toString()
297 {
298 try
299 {
300 send();
301 }
302 catch (Exception e)
303 {
304 Log.error ("VelocityEmail error", e);
305 }
306 return "";
307 }
308 }
This page was automatically generated by Maven