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