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