001: /****************************************************************
002: * Licensed to the Apache Software Foundation (ASF) under one *
003: * or more contributor license agreements. See the NOTICE file *
004: * distributed with this work for additional information *
005: * regarding copyright ownership. The ASF licenses this file *
006: * to you under the Apache License, Version 2.0 (the *
007: * "License"); you may not use this file except in compliance *
008: * with the License. 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, *
013: * software distributed under the License is distributed on an *
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
015: * KIND, either express or implied. See the License for the *
016: * specific language governing permissions and limitations *
017: * under the License. *
018: ****************************************************************/package org.apache.james.transport.mailets;
019:
020: import java.util.Collection;
021: import java.util.HashSet;
022:
023: import javax.mail.MessagingException;
024: import javax.mail.internet.InternetAddress;
025:
026: import org.apache.mailet.Mail;
027: import org.apache.mailet.MailAddress;
028:
029: /**
030: * <P>A mailet providing configurable redirection services.</P>
031: * <P>Can produce listserver, forward and notify behaviour, with the original
032: * message intact, attached, appended or left out altogether.</P>
033: * <P>It differs from {@link Resend} because
034: * (i) some defaults are different,
035: * notably for the following parameters: <I><recipients></I>, <I><to></I>,
036: * <I><reversePath></I> and <I><inline></I>;
037: * (ii) because it allows the use of the <I><static></I> parameter;.<BR>
038: * Use <CODE>Resend</CODE> if you need full control, <CODE>Redirect</CODE> if
039: * the more automatic behaviour of some parameters is appropriate.</P>
040: * <P>This built in functionality is controlled by the configuration as laid out below.
041: * In the table please note that the parameters controlling message headers
042: * accept the <B>"unaltered"</B> value, whose meaning is to keep the associated
043: * header unchanged and, unless stated differently, corresponds to the assumed default
044: * if the parameter is missing.</P>
045: * <P>The configuration parameters are:</P>
046: * <TABLE width="75%" border="1" cellspacing="2" cellpadding="2">
047: * <TR valign=top>
048: * <TD width="20%"><recipients></TD>
049: * <TD width="80%">
050: * A comma delimited list of addresses for recipients of
051: * this message; it will use the "to" list if not specified, and "unaltered"
052: * if none of the lists is specified.<BR>
053: * These addresses will only appear in the To: header if no "to" list is
054: * supplied.<BR>
055: * Such addresses can contain "full names", like
056: * <I>Mr. John D. Smith <john.smith@xyz.com></I>.<BR>
057: * The list can include constants "sender", "from", "replyTo", "postmaster", "reversePath", "recipients", "to", "null" and "unaltered";
058: * "replyTo" uses the ReplyTo header if available, otherwise the
059: * From header if available, otherwise the Sender header if available, otherwise the return-path;
060: * "from" is made equivalent to "sender", and "to" is made equivalent to "recipients";
061: * "null" is ignored.
062: * </TD>
063: * </TR>
064: * <TR valign=top>
065: * <TD width="20%"><to></TD>
066: * <TD width="80%">
067: * A comma delimited list of addresses to appear in the To: header;
068: * the email will be delivered to any of these addresses if it is also in the recipients
069: * list.<BR>
070: * The recipients list will be used if this list is not supplied;
071: * if none of the lists is specified it will be "unaltered".<BR>
072: * Such addresses can contain "full names", like
073: * <I>Mr. John D. Smith <john.smith@xyz.com></I>.<BR>
074: * The list can include constants "sender", "from", "replyTo", "postmaster", "reversePath", "recipients", "to", "null" and "unaltered";
075: * "from" uses the From header if available, otherwise the Sender header if available,
076: * otherwise the return-path;
077: * "replyTo" uses the ReplyTo header if available, otherwise the
078: * From header if available, otherwise the Sender header if available, otherwise the return-path;
079: * "recipients" is made equivalent to "to";
080: * if "null" is specified alone it will remove this header.
081: * </TD>
082: * </TR>
083: * <TR valign=top>
084: * <TD width="20%"><sender></TD>
085: * <TD width="80%">
086: * A single email address to appear in the From: and Return-Path: headers and become the sender.<BR>
087: * It can include constants "sender", "postmaster" and "unaltered";
088: * "sender" is equivalent to "unaltered".<BR>
089: * Default: "unaltered".
090: * </TD>
091: * </TR>
092: * <TR valign=top>
093: * <TD width="20%"><message></TD>
094: * <TD width="80%">
095: * A text message to insert into the body of the email.<BR>
096: * Default: no message is inserted.
097: * </TD>
098: * </TR>
099: * <TR valign=top>
100: * <TD width="20%"><inline></TD>
101: * <TD width="80%">
102: * <P>One of the following items:</P>
103: * <UL>
104: * <LI>unaltered The original message is the new
105: * message, for forwarding/aliasing</LI>
106: * <LI>heads The
107: * headers of the original message are appended to the message</LI>
108: * <LI>body The
109: * body of the original is appended to the new message</LI>
110: * <LI>all Both
111: * headers and body are appended</LI>
112: * <LI>none Neither
113: * body nor headers are appended</LI>
114: * </UL>
115: * Default: "body".
116: * </TD>
117: * </TR>
118: * <TR valign=top>
119: * <TD width="20%"><attachment></TD>
120: * <TD width="80%">
121: * <P>One of the following items:</P>
122: * <UL>
123: * <LI>heads The headers of the original
124: * are attached as text</LI>
125: * <LI>body The body of the original
126: * is attached as text</LI>
127: * <LI>all Both
128: * headers and body are attached as a single text file</LI>
129: * <LI>none Nothing is attached</LI>
130: * <LI>message The original message is attached as type message/rfc822,
131: * this means that it can, in many cases, be opened, resent, fw'd, replied
132: * to etc by email client software.</LI>
133: * </UL>
134: * Default: "none".
135: * </TD>
136: * </TR>
137: * <TR valign=top>
138: * <TD width="20%"><passThrough></TD>
139: * <TD width="80%">
140: * true or false, if true the original message continues in the
141: * mailet processor after this mailet is finished. False causes the original
142: * to be stopped.<BR>
143: * Default: false.
144: * </TD>
145: * </TR>
146: * <TR valign=top>
147: * <TD width="20%"><fakeDomainCheck></TD>
148: * <TD width="80%">
149: * true or false, if true will check if the sender domain is valid.<BR>
150: * Default: true.
151: * </TD>
152: * </TR>
153: * <TR valign=top>
154: * <TD width="20%"><attachError></TD>
155: * <TD width="80%">
156: * true or false, if true any error message available to the
157: * mailet is appended to the message body (except in the case of inline ==
158: * unaltered).<BR>
159: * Default: false.
160: * </TD>
161: * </TR>
162: * <TR valign=top>
163: * <TD width="20%"><replyTo></TD>
164: * <TD width="80%">
165: * A single email address to appear in the Reply-To: header.<BR>
166: * It can include constants "sender", "postmaster" "null" and "unaltered";
167: * if "null" is specified it will remove this header.<BR>
168: * Default: "unaltered".
169: * </TD>
170: * </TR>
171: * </TR>
172: * <TR valign=top>
173: * <TD width="20%"><reversePath></TD>
174: * <TD width="80%">
175: * A single email address to appear in the Return-Path: header.<BR>
176: * It can include constants "sender", "postmaster" and "null";
177: * if "null" is specified then it will set it to <>, meaning "null return path".<BR>
178: * Notice: the "unaltered" value is <I>not allowed</I>.<BR>
179: * Default: the value of the <I><sender></I> parameter, if set, otherwise remains unaltered.
180: * </TD>
181: * </TR>
182: * <TR valign=top>
183: * <TD width="20%"><subject></TD>
184: * <TD width="80%">
185: * An optional string to use as the subject.<BR>
186: * Default: keep the original message subject.
187: * </TD>
188: * </TR>
189: * <TR valign=top>
190: * <TD width="20%"><prefix></TD>
191: * <TD width="80%">
192: * An optional subject prefix prepended to the original message
193: * subject, or to a new subject specified with the <I><subject></I> parameter.<BR>
194: * For example: <I>[Undeliverable mail]</I>.<BR>
195: * Default: "".
196: * </TD>
197: * </TR>
198: * <TR valign=top>
199: * <TD width="20%"><isReply></TD>
200: * <TD width="80%">
201: * true or false, if true the IN_REPLY_TO header will be set to the
202: * id of the current message.<BR>
203: * Default: false.
204: * </TD>
205: * </TR>
206: * <TR valign=top>
207: * <TD width="20%"><debug></TD>
208: * <TD width="80%">
209: * true or false. If this is true it tells the mailet to write some debugging
210: * information to the mailet log.<BR>
211: * Default: false.
212: * </TD>
213: * </TR>
214: * <TR valign=top>
215: * <TD width="20%"><static></TD>
216: * <TD width="80%">
217: * true or false. If this is true it tells the mailet that it can
218: * reuse all the initial parameters (to, from, etc) without re-calculating
219: * their values. This will boost performance where a redirect task
220: * doesn't contain any dynamic values. If this is false, it tells the
221: * mailet to recalculate the values for each e-mail processed.<BR>
222: * Default: false.
223: * </TD>
224: * </TR>
225: * </TABLE>
226: *
227: * <P>Example:</P>
228: * <PRE><CODE>
229: * <mailet match="RecipientIs=test@localhost" class="Redirect">
230: * <recipients>x@localhost, y@localhost, z@localhost</recipients>
231: * <to>list@localhost</to>
232: * <sender>owner@localhost</sender>
233: * <message>sent on from James</message>
234: * <inline>unaltered</inline>
235: * <passThrough>FALSE</passThrough>
236: * <replyTo>postmaster</replyTo>
237: * <prefix xml:space="preserve">[test mailing] </prefix>
238: * <!-- note the xml:space="preserve" to preserve whitespace -->
239: * <static>TRUE</static>
240: * </mailet>
241: * </CODE></PRE>
242: *
243: * <P>and:</P>
244: *
245: * <PRE><CODE>
246: * <mailet match="All" class="Redirect">
247: * <recipients>x@localhost</recipients>
248: * <sender>postmaster</sender>
249: * <message xml:space="preserve">Message marked as spam:</message>
250: * <inline>heads</inline>
251: * <attachment>message</attachment>
252: * <passThrough>FALSE</passThrough>
253: * <attachError>TRUE</attachError>
254: * <replyTo>postmaster</replyTo>
255: * <prefix>[spam notification]</prefix>
256: * <static>TRUE</static>
257: * </mailet>
258: * </CODE></PRE>
259: * <P><I>replyto</I> can be used instead of
260: * <I>replyTo</I>; such name is kept for backward compatibility.</P>
261: *
262: * @version CVS $Revision: 494012 $ $Date: 2007-01-08 11:23:58 +0100 (Mo, 08 Jan 2007) $
263: */
264:
265: public class Redirect extends AbstractRedirect {
266:
267: /**
268: * Returns a string describing this mailet.
269: *
270: * @return a string describing this mailet
271: */
272: public String getMailetInfo() {
273: return "Redirect Mailet";
274: }
275:
276: /** Gets the expected init parameters. */
277: protected String[] getAllowedInitParameters() {
278: String[] allowedArray = { "static", "debug", "passThrough",
279: "fakeDomainCheck", "inline", "attachment", "message",
280: "recipients", "to", "replyTo", "replyto",
281: "reversePath", "sender", "subject", "prefix",
282: "attachError", "isReply" };
283: return allowedArray;
284: }
285:
286: /* ******************************************************************** */
287: /* ****************** Begin of getX and setX methods ****************** */
288: /* ******************************************************************** */
289:
290: /**
291: * @return the <CODE>static</CODE> init parameter
292: */
293: protected boolean isStatic() {
294: return isStatic;
295: }
296:
297: /**
298: * @return the <CODE>inline</CODE> init parameter
299: */
300: protected int getInLineType() throws MessagingException {
301: return getTypeCode(getInitParameter("inline", "body"));
302: }
303:
304: /**
305: * @return the <CODE>recipients</CODE> init parameter
306: * or the postmaster address
307: * or <CODE>SpecialAddress.SENDER</CODE>
308: * or <CODE>SpecialAddress.REVERSE_PATH</CODE>
309: * or <CODE>SpecialAddress.UNALTERED</CODE>
310: * or the <CODE>to</CODE> init parameter if missing
311: * or <CODE>null</CODE> if also the latter is missing
312: */
313: protected Collection getRecipients() throws MessagingException {
314: Collection newRecipients = new HashSet();
315: String addressList = getInitParameter("recipients",
316: getInitParameter("to"));
317:
318: // if nothing was specified, return <CODE>null</CODE> meaning no change
319: if (addressList == null) {
320: return null;
321: }
322:
323: try {
324: InternetAddress[] iaarray = InternetAddress.parse(
325: addressList, false);
326: for (int i = 0; i < iaarray.length; i++) {
327: String addressString = iaarray[i].getAddress();
328: MailAddress specialAddress = getSpecialAddress(
329: addressString, new String[] { "postmaster",
330: "sender", "from", "replyTo",
331: "reversePath", "unaltered",
332: "recipients", "to", "null" });
333: if (specialAddress != null) {
334: newRecipients.add(specialAddress);
335: } else {
336: newRecipients.add(new MailAddress(iaarray[i]));
337: }
338: }
339: } catch (Exception e) {
340: throw new MessagingException(
341: "Exception thrown in getRecipients() parsing: "
342: + addressList, e);
343: }
344: if (newRecipients.size() == 0) {
345: throw new MessagingException(
346: "Failed to initialize \"recipients\" list; empty <recipients> init parameter found.");
347: }
348:
349: return newRecipients;
350: }
351:
352: /**
353: * @return the <CODE>to</CODE> init parameter
354: * or the postmaster address
355: * or <CODE>SpecialAddress.SENDER</CODE>
356: * or <CODE>SpecialAddress.REVERSE_PATH</CODE>
357: * or <CODE>SpecialAddress.UNALTERED</CODE>
358: * or the <CODE>recipients</CODE> init parameter if missing
359: * or <CODE>null</CODE> if also the latter is missing
360: */
361: protected InternetAddress[] getTo() throws MessagingException {
362: InternetAddress[] iaarray = null;
363: String addressList = getInitParameter("to",
364: getInitParameter("recipients"));
365:
366: // if nothing was specified, return null meaning no change
367: if (addressList == null) {
368: return null;
369: }
370:
371: try {
372: iaarray = InternetAddress.parse(addressList, false);
373: for (int i = 0; i < iaarray.length; ++i) {
374: String addressString = iaarray[i].getAddress();
375: MailAddress specialAddress = getSpecialAddress(
376: addressString, new String[] { "postmaster",
377: "sender", "from", "replyTo",
378: "reversePath", "unaltered",
379: "recipients", "to", "null" });
380: if (specialAddress != null) {
381: iaarray[i] = specialAddress.toInternetAddress();
382: }
383: }
384: } catch (Exception e) {
385: throw new MessagingException(
386: "Exception thrown in getTo() parsing: "
387: + addressList, e);
388: }
389: if (iaarray.length == 0) {
390: throw new MessagingException(
391: "Failed to initialize \"to\" list; empty <to> init parameter found.");
392: }
393:
394: return iaarray;
395: }
396:
397: /**
398: * @return the <CODE>reversePath</CODE> init parameter
399: * or the postmaster address
400: * or <CODE>SpecialAddress.SENDER</CODE>
401: * or <CODE>SpecialAddress.NULL</CODE>
402: * or <CODE>null</CODE> if missing
403: */
404: protected MailAddress getReversePath() throws MessagingException {
405: String addressString = getInitParameter("reversePath");
406: if (addressString != null) {
407: MailAddress specialAddress = getSpecialAddress(
408: addressString, new String[] { "postmaster",
409: "sender", "null" });
410: if (specialAddress != null) {
411: return specialAddress;
412: }
413:
414: try {
415: return new MailAddress(addressString);
416: } catch (Exception e) {
417: throw new MessagingException(
418: "Exception thrown in getReversePath() parsing: "
419: + addressString, e);
420: }
421: }
422:
423: return null;
424: }
425:
426: /**
427: * @return {@link AbstractRedirect#getReversePath()};
428: * if null return {@link AbstractRedirect#getSender(Mail)},
429: * meaning the new requested sender if any
430: */
431: protected MailAddress getReversePath(Mail originalMail)
432: throws MessagingException {
433: MailAddress reversePath = super .getReversePath(originalMail);
434: if (reversePath == null) {
435: reversePath = getSender(originalMail);
436: }
437: return reversePath;
438: }
439:
440: /* ******************************************************************** */
441: /* ******************* End of getX and setX methods ******************* */
442: /* ******************************************************************** */
443:
444: }
|