1 /************************************************************************
2 * Copyright (c) 2000-2006 The Apache Software Foundation. *
3 * All rights reserved. *
4 * ------------------------------------------------------------------- *
5 * Licensed under the Apache License, Version 2.0 (the "License"); you *
6 * may not use this file except in compliance with the License. You *
7 * may obtain a copy of the License at: *
8 * *
9 * http://www.apache.org/licenses/LICENSE-2.0 *
10 * *
11 * Unless required by applicable law or agreed to in writing, software *
12 * distributed under the License is distributed on an "AS IS" BASIS, *
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or *
14 * implied. See the License for the specific language governing *
15 * permissions and limitations under the License. *
16 ***********************************************************************/
17
18 package org.apache.james.transport.mailets;
19
20 import java.util.Collection;
21 import java.util.HashSet;
22
23
24 import javax.mail.MessagingException;
25 import javax.mail.internet.InternetAddress;
26
27 import org.apache.mailet.Mail;
28 import org.apache.mailet.MailAddress;
29
30
31 /***
32 * <P>A mailet providing configurable redirection services.</P>
33 * <P>Can produce listserver, forward and notify behaviour, with the original
34 * message intact, attached, appended or left out altogether.</P>
35 * <P>It differs from {@link Resend} because
36 * (i) some defaults are different,
37 * notably for the following parameters: <I><recipients></I>, <I><to></I>,
38 * <I><reversePath></I> and <I><inline></I>;
39 * (ii) because it allows the use of the <I><static></I> parameter;.<BR>
40 * Use <CODE>Resend</CODE> if you need full control, <CODE>Redirect</CODE> if
41 * the more automatic behaviour of some parameters is appropriate.</P>
42 * <P>This built in functionality is controlled by the configuration as laid out below.
43 * In the table please note that the parameters controlling message headers
44 * accept the <B>"unaltered"</B> value, whose meaning is to keep the associated
45 * header unchanged and, unless stated differently, corresponds to the assumed default
46 * if the parameter is missing.</P>
47 * <P>The configuration parameters are:</P>
48 * <TABLE width="75%" border="1" cellspacing="2" cellpadding="2">
49 * <TR valign=top>
50 * <TD width="20%"><recipients></TD>
51 * <TD width="80%">
52 * A comma delimited list of addresses for recipients of
53 * this message; it will use the "to" list if not specified, and "unaltered"
54 * if none of the lists is specified.<BR>
55 * These addresses will only appear in the To: header if no "to" list is
56 * supplied.<BR>
57 * Such addresses can contain "full names", like
58 * <I>Mr. John D. Smith <john.smith@xyz.com></I>.<BR>
59 * The list can include constants "sender", "from", "replyTo", "postmaster", "reversePath", "recipients", "to", "null" and "unaltered";
60 * "replyTo" uses the ReplyTo header if available, otherwise the
61 * From header if available, otherwise the Sender header if available, otherwise the return-path;
62 * "from" is made equivalent to "sender", and "to" is made equivalent to "recipients";
63 * "null" is ignored.
64 * </TD>
65 * </TR>
66 * <TR valign=top>
67 * <TD width="20%"><to></TD>
68 * <TD width="80%">
69 * A comma delimited list of addresses to appear in the To: header;
70 * the email will be delivered to any of these addresses if it is also in the recipients
71 * list.<BR>
72 * The recipients list will be used if this list is not supplied;
73 * if none of the lists is specified it will be "unaltered".<BR>
74 * Such addresses can contain "full names", like
75 * <I>Mr. John D. Smith <john.smith@xyz.com></I>.<BR>
76 * The list can include constants "sender", "from", "replyTo", "postmaster", "reversePath", "recipients", "to", "null" and "unaltered";
77 * "from" uses the From header if available, otherwise the Sender header if available,
78 * otherwise the return-path;
79 * "replyTo" uses the ReplyTo header if available, otherwise the
80 * From header if available, otherwise the Sender header if available, otherwise the return-path;
81 * "recipients" is made equivalent to "to";
82 * if "null" is specified alone it will remove this header.
83 * </TD>
84 * </TR>
85 * <TR valign=top>
86 * <TD width="20%"><sender></TD>
87 * <TD width="80%">
88 * A single email address to appear in the From: and Return-Path: headers and become the sender.<BR>
89 * It can include constants "sender", "postmaster" and "unaltered";
90 * "sender" is equivalent to "unaltered".<BR>
91 * Default: "unaltered".
92 * </TD>
93 * </TR>
94 * <TR valign=top>
95 * <TD width="20%"><message></TD>
96 * <TD width="80%">
97 * A text message to insert into the body of the email.<BR>
98 * Default: no message is inserted.
99 * </TD>
100 * </TR>
101 * <TR valign=top>
102 * <TD width="20%"><inline></TD>
103 * <TD width="80%">
104 * <P>One of the following items:</P>
105 * <UL>
106 * <LI>unaltered The original message is the new
107 * message, for forwarding/aliasing</LI>
108 * <LI>heads The
109 * headers of the original message are appended to the message</LI>
110 * <LI>body The
111 * body of the original is appended to the new message</LI>
112 * <LI>all Both
113 * headers and body are appended</LI>
114 * <LI>none Neither
115 * body nor headers are appended</LI>
116 * </UL>
117 * Default: "body".
118 * </TD>
119 * </TR>
120 * <TR valign=top>
121 * <TD width="20%"><attachment></TD>
122 * <TD width="80%">
123 * <P>One of the following items:</P>
124 * <UL>
125 * <LI>heads The headers of the original
126 * are attached as text</LI>
127 * <LI>body The body of the original
128 * is attached as text</LI>
129 * <LI>all Both
130 * headers and body are attached as a single text file</LI>
131 * <LI>none Nothing is attached</LI>
132 * <LI>message The original message is attached as type message/rfc822,
133 * this means that it can, in many cases, be opened, resent, fw'd, replied
134 * to etc by email client software.</LI>
135 * </UL>
136 * Default: "none".
137 * </TD>
138 * </TR>
139 * <TR valign=top>
140 * <TD width="20%"><passThrough></TD>
141 * <TD width="80%">
142 * true or false, if true the original message continues in the
143 * mailet processor after this mailet is finished. False causes the original
144 * to be stopped.<BR>
145 * Default: false.
146 * </TD>
147 * </TR>
148 * <TR valign=top>
149 * <TD width="20%"><fakeDomainCheck></TD>
150 * <TD width="80%">
151 * true or false, if true will check if the sender domain is valid.<BR>
152 * Default: true.
153 * </TD>
154 * </TR>
155 * <TR valign=top>
156 * <TD width="20%"><attachError></TD>
157 * <TD width="80%">
158 * true or false, if true any error message available to the
159 * mailet is appended to the message body (except in the case of inline ==
160 * unaltered).<BR>
161 * Default: false.
162 * </TD>
163 * </TR>
164 * <TR valign=top>
165 * <TD width="20%"><replyTo></TD>
166 * <TD width="80%">
167 * A single email address to appear in the Reply-To: header.<BR>
168 * It can include constants "sender", "postmaster" "null" and "unaltered";
169 * if "null" is specified it will remove this header.<BR>
170 * Default: "unaltered".
171 * </TD>
172 * </TR>
173 * </TR>
174 * <TR valign=top>
175 * <TD width="20%"><reversePath></TD>
176 * <TD width="80%">
177 * A single email address to appear in the Return-Path: header.<BR>
178 * It can include constants "sender", "postmaster" and "null";
179 * if "null" is specified then it will set it to <>, meaning "null return path".<BR>
180 * Notice: the "unaltered" value is <I>not allowed</I>.<BR>
181 * Default: the value of the <I><sender></I> parameter, if set, otherwise remains unaltered.
182 * </TD>
183 * </TR>
184 * <TR valign=top>
185 * <TD width="20%"><subject></TD>
186 * <TD width="80%">
187 * An optional string to use as the subject.<BR>
188 * Default: keep the original message subject.
189 * </TD>
190 * </TR>
191 * <TR valign=top>
192 * <TD width="20%"><prefix></TD>
193 * <TD width="80%">
194 * An optional subject prefix prepended to the original message
195 * subject, or to a new subject specified with the <I><subject></I> parameter.<BR>
196 * For example: <I>[Undeliverable mail]</I>.<BR>
197 * Default: "".
198 * </TD>
199 * </TR>
200 * <TR valign=top>
201 * <TD width="20%"><isReply></TD>
202 * <TD width="80%">
203 * true or false, if true the IN_REPLY_TO header will be set to the
204 * id of the current message.<BR>
205 * Default: false.
206 * </TD>
207 * </TR>
208 * <TR valign=top>
209 * <TD width="20%"><debug></TD>
210 * <TD width="80%">
211 * true or false. If this is true it tells the mailet to write some debugging
212 * information to the mailet log.<BR>
213 * Default: false.
214 * </TD>
215 * </TR>
216 * <TR valign=top>
217 * <TD width="20%"><static></TD>
218 * <TD width="80%">
219 * true or false. If this is true it tells the mailet that it can
220 * reuse all the initial parameters (to, from, etc) without re-calculating
221 * their values. This will boost performance where a redirect task
222 * doesn't contain any dynamic values. If this is false, it tells the
223 * mailet to recalculate the values for each e-mail processed.<BR>
224 * Default: false.
225 * </TD>
226 * </TR>
227 * </TABLE>
228 *
229 * <P>Example:</P>
230 * <PRE><CODE>
231 * <mailet match="RecipientIs=test@localhost" class="Redirect">
232 * <recipients>x@localhost, y@localhost, z@localhost</recipients>
233 * <to>list@localhost</to>
234 * <sender>owner@localhost</sender>
235 * <message>sent on from James</message>
236 * <inline>unaltered</inline>
237 * <passThrough>FALSE</passThrough>
238 * <replyTo>postmaster</replyTo>
239 * <prefix xml:space="preserve">[test mailing] </prefix>
240 * <!-- note the xml:space="preserve" to preserve whitespace -->
241 * <static>TRUE</static>
242 * </mailet>
243 * </CODE></PRE>
244 *
245 * <P>and:</P>
246 *
247 * <PRE><CODE>
248 * <mailet match="All" class="Redirect">
249 * <recipients>x@localhost</recipients>
250 * <sender>postmaster</sender>
251 * <message xml:space="preserve">Message marked as spam:</message>
252 * <inline>heads</inline>
253 * <attachment>message</attachment>
254 * <passThrough>FALSE</passThrough>
255 * <attachError>TRUE</attachError>
256 * <replyTo>postmaster</replyTo>
257 * <prefix>[spam notification]</prefix>
258 * <static>TRUE</static>
259 * </mailet>
260 * </CODE></PRE>
261 * <P><I>replyto</I> can be used instead of
262 * <I>replyTo</I>; such name is kept for backward compatibility.</P>
263 *
264 * @version CVS $Revision: 382444 $ $Date: 2006-03-02 16:56:32 +0000 (gio, 02 mar 2006) $
265 */
266
267 public class Redirect extends AbstractRedirect {
268
269 /***
270 * Returns a string describing this mailet.
271 *
272 * @return a string describing this mailet
273 */
274 public String getMailetInfo() {
275 return "Redirect Mailet";
276 }
277
278 /*** Gets the expected init parameters. */
279 protected String[] getAllowedInitParameters() {
280 String[] allowedArray = {
281 "static",
282 "debug",
283 "passThrough",
284 "fakeDomainCheck",
285 "inline",
286 "attachment",
287 "message",
288 "recipients",
289 "to",
290 "replyTo",
291 "replyto",
292 "reversePath",
293 "sender",
294 "subject",
295 "prefix",
296 "attachError",
297 "isReply"
298 };
299 return allowedArray;
300 }
301
302
303
304
305
306 /***
307 * @return the <CODE>static</CODE> init parameter
308 */
309 protected boolean isStatic() {
310 return isStatic;
311 }
312
313 /***
314 * @return the <CODE>inline</CODE> init parameter
315 */
316 protected int getInLineType() throws MessagingException {
317 return getTypeCode(getInitParameter("inline","body"));
318 }
319
320 /***
321 * @return the <CODE>recipients</CODE> init parameter
322 * or the postmaster address
323 * or <CODE>SpecialAddress.SENDER</CODE>
324 * or <CODE>SpecialAddress.REVERSE_PATH</CODE>
325 * or <CODE>SpecialAddress.UNALTERED</CODE>
326 * or the <CODE>to</CODE> init parameter if missing
327 * or <CODE>null</CODE> if also the latter is missing
328 */
329 protected Collection getRecipients() throws MessagingException {
330 Collection newRecipients = new HashSet();
331 String addressList = getInitParameter("recipients",getInitParameter("to"));
332
333
334 if (addressList == null) {
335 return null;
336 }
337
338 try {
339 InternetAddress[] iaarray = InternetAddress.parse(addressList, false);
340 for (int i = 0; i < iaarray.length; i++) {
341 String addressString = iaarray[i].getAddress();
342 MailAddress specialAddress = getSpecialAddress(addressString,
343 new String[] {"postmaster", "sender", "from", "replyTo", "reversePath", "unaltered", "recipients", "to", "null"});
344 if (specialAddress != null) {
345 newRecipients.add(specialAddress);
346 } else {
347 newRecipients.add(new MailAddress(iaarray[i]));
348 }
349 }
350 } catch (Exception e) {
351 throw new MessagingException("Exception thrown in getRecipients() parsing: " + addressList, e);
352 }
353 if (newRecipients.size() == 0) {
354 throw new MessagingException("Failed to initialize \"recipients\" list; empty <recipients> init parameter found.");
355 }
356
357 return newRecipients;
358 }
359
360 /***
361 * @return the <CODE>to</CODE> init parameter
362 * or the postmaster address
363 * or <CODE>SpecialAddress.SENDER</CODE>
364 * or <CODE>SpecialAddress.REVERSE_PATH</CODE>
365 * or <CODE>SpecialAddress.UNALTERED</CODE>
366 * or the <CODE>recipients</CODE> init parameter if missing
367 * or <CODE>null</CODE> if also the latter is missing
368 */
369 protected InternetAddress[] getTo() throws MessagingException {
370 InternetAddress[] iaarray = null;
371 String addressList = getInitParameter("to",getInitParameter("recipients"));
372
373
374 if (addressList == null) {
375 return null;
376 }
377
378 try {
379 iaarray = InternetAddress.parse(addressList, false);
380 for(int i = 0; i < iaarray.length; ++i) {
381 String addressString = iaarray[i].getAddress();
382 MailAddress specialAddress = getSpecialAddress(addressString,
383 new String[] {"postmaster", "sender", "from", "replyTo", "reversePath", "unaltered", "recipients", "to", "null"});
384 if (specialAddress != null) {
385 iaarray[i] = specialAddress.toInternetAddress();
386 }
387 }
388 } catch (Exception e) {
389 throw new MessagingException("Exception thrown in getTo() parsing: " + addressList, e);
390 }
391 if (iaarray.length == 0) {
392 throw new MessagingException("Failed to initialize \"to\" list; empty <to> init parameter found.");
393 }
394
395 return iaarray;
396 }
397
398 /***
399 * @return the <CODE>reversePath</CODE> init parameter
400 * or the postmaster address
401 * or <CODE>SpecialAddress.SENDER</CODE>
402 * or <CODE>SpecialAddress.NULL</CODE>
403 * or <CODE>null</CODE> if missing
404 */
405 protected MailAddress getReversePath() throws MessagingException {
406 String addressString = getInitParameter("reversePath");
407 if(addressString != null) {
408 MailAddress specialAddress = getSpecialAddress(addressString,
409 new String[] {"postmaster", "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("Exception thrown in getReversePath() parsing: " + addressString, e);
418 }
419 }
420
421 return null;
422 }
423
424 /***
425 * @return {@link AbstractRedirect#getReversePath()};
426 * if null return {@link AbstractRedirect#getSender(Mail)},
427 * meaning the new requested sender if any
428 */
429 protected MailAddress getReversePath(Mail originalMail) throws MessagingException {
430 MailAddress reversePath = super.getReversePath(originalMail);
431 if (reversePath == null) {
432 reversePath = getSender(originalMail);
433 }
434 return reversePath;
435 }
436
437
438
439
440
441 }