001: package org.apache.turbine.util.velocity;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import org.apache.commons.lang.StringUtils;
023: import org.apache.commons.lang.WordUtils;
024: import org.apache.commons.logging.Log;
025: import org.apache.commons.logging.LogFactory;
026: import org.apache.commons.mail.EmailException;
027: import org.apache.commons.mail.SimpleEmail;
028: import org.apache.turbine.Turbine;
029: import org.apache.turbine.TurbineConstants;
030: import org.apache.turbine.services.velocity.TurbineVelocity;
031: import org.apache.velocity.context.Context;
032:
033: /**
034: * This is a simple class for sending email from within Velocity.
035: * Essentially, the body of the email is processed with a
036: * Velocity Context object.
037: * The beauty of this is that you can send email from within your
038: * Velocity template or from your business logic in your Java code.
039: * The body of the email is just a Velocity template so you can use
040: * all the template functionality of Velocity within your emails!
041: *
042: * <p>Example Usage (This all needs to be on one line in your
043: * template):
044: *
045: * <p>Setup your context:
046: *
047: * <p><code>context.put ("VelocityEmail", new VelocityEmail() );</code>
048: *
049: * <p>Then, in your template:
050: *
051: * <pre>
052: * $VelocityEmail.setTo("Jon Stevens", "jon@latchkey.com")
053: * .setFrom("Mom", "mom@mom.com").setSubject("Eat dinner")
054: * .setTemplate("email/momEmail.vm")
055: * .setContext($context)
056: * </pre>
057: *
058: * The email/momEmail.wm template will then be parsed with the
059: * Context that was defined with setContext().
060: *
061: * <p>If you want to use this class from within your Java code all you
062: * have to do is something like this:
063: *
064: * <pre>
065: * VelocityEmail ve = new VelocityEmail();
066: * ve.setTo("Jon Stevens", "jon@latchkey.com");
067: * ve.setFrom("Mom", "mom@mom.com").setSubject("Eat dinner");
068: * ve.setContext(context);
069: * ve.setTemplate("email/momEmail.vm")
070: * ve.send();
071: * </pre>
072: *
073: * <p>(Note that when used within a Velocity template, the send method
074: * will be called for you when Velocity tries to convert the
075: * VelocityEmail to a string by calling toString()).</p>
076: *
077: * <p>If you need your email to be word-wrapped, you can add the
078: * following call to those above:
079: *
080: * <pre>
081: * ve.setWordWrap (60);
082: * </pre>
083: *
084: * <p>This class is just a wrapper around the SimpleEmail class from
085: * commons-mail using the JavaMail API.
086: * Thus, it depends on having the
087: * mail.server property set in the TurbineResources.properties file.
088: * If you want to use this class outside of Turbine for general
089: * processing that is also possible by making sure to set the path to
090: * the TurbineResources.properties. See the
091: * TurbineConfig class for more information.</p>
092: *
093: * <p>You can turn on debugging for the JavaMail API by calling
094: * setDebug(true). The debugging messages will be written to System.out.
095: *
096: * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
097: * @author <a href="mailto:gcoladonato@yahoo.com">Greg Coladonato</a>
098: * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
099: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
100: * @version $Id: VelocityEmail.java 534527 2007-05-02 16:10:59Z tv $
101: */
102: public class VelocityEmail extends SimpleEmail {
103: /** Logging */
104: private static Log log = LogFactory.getLog(VelocityEmail.class);
105:
106: /** The column to word-wrap at. <code>0</code> indicates no wrap. */
107: private int wordWrap = 0;
108:
109: /** Address of outgoing mail server */
110: private String mailServer;
111:
112: /** The template to process, relative to Velocity template directory. */
113: private String template = null;
114:
115: /** Velocity context */
116: private Context context = null;
117:
118: /**
119: * Constructor
120: */
121: public VelocityEmail() {
122: }
123:
124: /**
125: * Constructor
126: */
127: public VelocityEmail(Context context) {
128: this .context = context;
129: }
130:
131: /**
132: * To: toName, toEmail
133: *
134: * @param toName A String with the TO toName.
135: * @param toEmail A String with the TO toEmail.
136: * @deprecated use addTo(email,name) instead
137: * @throws EmailException email address could not be parsed
138: * @return A VelocityEmail (self).
139: */
140: public VelocityEmail setTo(String toName, String toEmail)
141: throws EmailException {
142: addTo(toEmail, toName);
143: return this ;
144: }
145:
146: /**
147: * Velocity template to execute. Path is relative to the Velocity
148: * templates directory.
149: *
150: * @param template relative path of the template to parse including the
151: * filename.
152: * @return A VelocityEmail (self).
153: */
154: public VelocityEmail setTemplate(String template) {
155: this .template = template;
156: return this ;
157: }
158:
159: /**
160: * Set the column at which long lines of text should be word-
161: * wrapped. Setting to zero turns off word-wrap (default).
162: *
163: * NOTE: don't use tabs in your email template document,
164: * or your word-wrapping will be off for the lines with tabs
165: * in them.
166: *
167: * @param wordWrap The column at which to wrap long lines.
168: * @return A VelocityEmail (self).
169: */
170: public VelocityEmail setWordWrap(int wordWrap) {
171: this .wordWrap = wordWrap;
172: return this ;
173: }
174:
175: /**
176: * Set the context object that will be merged with the
177: * template.
178: *
179: * @param context A Velocity context object.
180: * @return A VelocityEmail (self).
181: */
182: public VelocityEmail setContext(Context context) {
183: this .context = context;
184: return this ;
185: }
186:
187: /**
188: * Get the context object that will be merged with the
189: * template.
190: *
191: * @return A Context (self).
192: */
193: public Context getContext() {
194: return this .context;
195: }
196:
197: /**
198: * Sets the address of the outgoing mail server. This method
199: * should be used when you need to override the value stored in
200: * TR.props.
201: *
202: * @param serverAddress host name of your outgoing mail server
203: */
204: public void setMailServer(String serverAddress) {
205: this .mailServer = serverAddress;
206: }
207:
208: /**
209: * Gets the host name of the outgoing mail server. If the server
210: * name has not been set by calling setMailServer(), the value
211: * from TR.props for mail.server will be returned. If TR.props
212: * has no value for mail.server, localhost will be returned.
213: *
214: * @return host name of the mail server.
215: */
216: public String getMailServer() {
217: return StringUtils.isNotEmpty(mailServer) ? mailServer
218: : Turbine.getConfiguration().getString(
219: TurbineConstants.MAIL_SERVER_KEY,
220: TurbineConstants.MAIL_SERVER_DEFAULT);
221: }
222:
223: /**
224: * This method sends the email.
225: * <p>If the mail server was not set by calling, setMailServer()
226: * the value of mail.server will be used from TR.props. If that
227: * value was not set, localhost is used.
228: *
229: * @throws EmailException Failure during merging the velocity
230: * template or sending the email.
231: */
232: public String send() throws EmailException {
233: String body = null;
234: try {
235: // Process the template.
236: body = TurbineVelocity.handleRequest(context, template);
237: } catch (Exception e) {
238: throw new EmailException(
239: "Could not render velocitty template", e);
240: }
241:
242: // If the caller desires word-wrapping, do it here
243: if (wordWrap > 0) {
244: body = WordUtils.wrap(body, wordWrap, System
245: .getProperty("line.separator"), false);
246: }
247:
248: setMsg(body);
249: setHostName(getMailServer());
250: return super .send();
251: }
252:
253: /**
254: * The method toString() calls send() for ease of use within a
255: * Velocity template (see example usage above).
256: *
257: * @return An empty string.
258: */
259: public String toString() {
260: try {
261: send();
262: } catch (Exception e) {
263: log.error("VelocityEmail error", e);
264: }
265: return "";
266: }
267: }
|