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