org.apache.james.transport.mailets
Class Redirect

java.lang.Object
  extended by org.apache.mailet.base.GenericMailet
      extended by org.apache.james.transport.mailets.AbstractRedirect
          extended by org.apache.james.transport.mailets.Redirect
All Implemented Interfaces:
org.apache.mailet.Mailet, org.apache.mailet.MailetConfig

public class Redirect
extends AbstractRedirect

A mailet providing configurable redirection services.

Can produce listserver, forward and notify behaviour, with the original message intact, attached, appended or left out altogether.

It differs from Resend because (i) some defaults are different, notably for the following parameters: <recipients>, <to>, <reversePath> and <inline>; (ii) because it allows the use of the <static> parameter;.
Use Resend if you need full control, Redirect if the more automatic behaviour of some parameters is appropriate.

This built in functionality is controlled by the configuration as laid out below. In the table please note that the parameters controlling message headers accept the "unaltered" value, whose meaning is to keep the associated header unchanged and, unless stated differently, corresponds to the assumed default if the parameter is missing.

The configuration parameters are:

<recipients> A comma delimited list of addresses for recipients of this message; it will use the "to" list if not specified, and "unaltered" if none of the lists is specified.
These addresses will only appear in the To: header if no "to" list is supplied.
Such addresses can contain "full names", like Mr. John D. Smith <john.smith@xyz.com>.
The list can include constants "sender", "from", "replyTo", "postmaster", "reversePath", "recipients", "to", "null" and "unaltered"; "replyTo" uses the ReplyTo header if available, otherwise the From header if available, otherwise the Sender header if available, otherwise the return-path; "from" is made equivalent to "sender", and "to" is made equivalent to "recipients"; "null" is ignored.
<to> A comma delimited list of addresses to appear in the To: header; the email will be delivered to any of these addresses if it is also in the recipients list.
The recipients list will be used if this list is not supplied; if none of the lists is specified it will be "unaltered".
Such addresses can contain "full names", like Mr. John D. Smith <john.smith@xyz.com>.
The list can include constants "sender", "from", "replyTo", "postmaster", "reversePath", "recipients", "to", "null" and "unaltered"; "from" uses the From header if available, otherwise the Sender header if available, otherwise the return-path; "replyTo" uses the ReplyTo header if available, otherwise the From header if available, otherwise the Sender header if available, otherwise the return-path; "recipients" is made equivalent to "to"; if "null" is specified alone it will remove this header.
<sender> A single email address to appear in the From: and Return-Path: headers and become the sender.
It can include constants "sender", "postmaster" and "unaltered"; "sender" is equivalent to "unaltered".
Default: "unaltered".
<message> A text message to insert into the body of the email.
Default: no message is inserted.
<inline>

One of the following items:

  • unaltered     The original message is the new message, for forwarding/aliasing
  • heads          The headers of the original message are appended to the message
  • body           The body of the original is appended to the new message
  • all               Both headers and body are appended
  • none           Neither body nor headers are appended
Default: "body".
<attachment>

One of the following items:

  • heads      The headers of the original are attached as text
  • body       The body of the original is attached as text
  • all           Both headers and body are attached as a single text file
  • none       Nothing is attached
  • message  The original message is attached as type message/rfc822, this means that it can, in many cases, be opened, resent, fw'd, replied to etc by email client software.
Default: "none".
<passThrough> true or false, if true the original message continues in the mailet processor after this mailet is finished. False causes the original to be stopped.
Default: false.
<fakeDomainCheck> true or false, if true will check if the sender domain is valid.
Default: true.
<attachError> true or false, if true any error message available to the mailet is appended to the message body (except in the case of inline == unaltered).
Default: false.
<replyTo> A single email address to appear in the Reply-To: header.
It can include constants "sender", "postmaster" "null" and "unaltered"; if "null" is specified it will remove this header.
Default: "unaltered".
<reversePath> A single email address to appear in the Return-Path: header.
It can include constants "sender", "postmaster" and "null"; if "null" is specified then it will set it to <>, meaning "null return path".
Notice: the "unaltered" value is not allowed.
Default: the value of the <sender> parameter, if set, otherwise remains unaltered.
<subject> An optional string to use as the subject.
Default: keep the original message subject.
<prefix> An optional subject prefix prepended to the original message subject, or to a new subject specified with the <subject> parameter.
For example: [Undeliverable mail].
Default: "".
<isReply> true or false, if true the IN_REPLY_TO header will be set to the id of the current message.
Default: false.
<debug> true or false. If this is true it tells the mailet to write some debugging information to the mailet log.
Default: false.
<static> true or false. If this is true it tells the mailet that it can reuse all the initial parameters (to, from, etc) without re-calculating their values. This will boost performance where a redirect task doesn't contain any dynamic values. If this is false, it tells the mailet to recalculate the values for each e-mail processed.
Default: false.

Example:


  <mailet match="RecipientIs=test@localhost" class="Redirect">
    <recipients>x@localhost, y@localhost, z@localhost</recipients>
    <to>list@localhost</to>
    <sender>owner@localhost</sender>
    <message>sent on from James</message>
    <inline>unaltered</inline>
    <passThrough>FALSE</passThrough>
    <replyTo>postmaster</replyTo>
    <prefix xml:space="preserve">[test mailing] </prefix>
    <!-- note the xml:space="preserve" to preserve whitespace -->
    <static>TRUE</static>
 </mailet>
 

and:


  <mailet match="All" class="Redirect">
    <recipients>x@localhost</recipients>
    <sender>postmaster</sender>
    <message xml:space="preserve">Message marked as spam:</message>
    <inline>heads</inline>
    <attachment>message</attachment>
    <passThrough>FALSE</passThrough>
    <attachError>TRUE</attachError>
    <replyTo>postmaster</replyTo>
    <prefix>[spam notification]</prefix>
    <static>TRUE</static>
  </mailet>
 

replyto can be used instead of replyTo; such name is kept for backward compatibility.

Version:
CVS $Revision: 426007 $ $Date: 2006-07-27 09:52:06 +0100 (Thu, 27 Jul 2006) $

Nested Class Summary
 
Nested classes/interfaces inherited from class org.apache.james.transport.mailets.AbstractRedirect
AbstractRedirect.SpecialAddress
 
Field Summary
 
Fields inherited from class org.apache.james.transport.mailets.AbstractRedirect
ALL, BODY, HEADS, isDebug, isStatic, MESSAGE, NONE, UNALTERED
 
Constructor Summary
Redirect()
           
 
Method Summary
protected  java.lang.String[] getAllowedInitParameters()
          Gets the expected init parameters.
protected  int getInLineType()
          Gets the inline property.
 java.lang.String getMailetInfo()
          Returns a string describing this mailet.
protected  java.util.Collection getRecipients()
          Gets the recipients property.
protected  org.apache.mailet.MailAddress getReversePath()
          Gets the reversePath property.
protected  org.apache.mailet.MailAddress getReversePath(org.apache.mailet.Mail originalMail)
          Gets the reversePath property, built dynamically using the original Mail object.
protected  javax.mail.internet.InternetAddress[] getTo()
          Gets the to property.
protected  boolean isStatic()
          Gets the static property.
 
Methods inherited from class org.apache.james.transport.mailets.AbstractRedirect
attachError, attachError, buildAlteredMessage, changeSubject, getAttachmentType, getAttachmentType, getFakeDomainCheck, getFakeDomainCheck, getInLineType, getMessage, getMessage, getMessageHeaders, getPassThrough, getPassThrough, getRecipients, getReplyTo, getReplyTo, getSender, getSender, getSpecialAddress, getSubject, getSubject, getSubjectPrefix, getSubjectPrefix, getTo, getTypeCode, init, isReply, isReply, replaceInternetAddresses, replaceMailAddresses, senderDomainIsValid, service, setIsReply, setRecipients, setReplyTo, setReversePath, setSender, setSubjectPrefix, setTo
 
Methods inherited from class org.apache.mailet.base.GenericMailet
arrayToString, checkInitParameters, destroy, getInitParameter, getInitParameter, getInitParameter, getInitParameterNames, getMailetConfig, getMailetContext, getMailetName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Redirect

public Redirect()
Method Detail

getMailetInfo

public java.lang.String getMailetInfo()
Returns a string describing this mailet.

Specified by:
getMailetInfo in interface org.apache.mailet.Mailet
Overrides:
getMailetInfo in class org.apache.mailet.base.GenericMailet
Returns:
a string describing this mailet

getAllowedInitParameters

protected java.lang.String[] getAllowedInitParameters()
Gets the expected init parameters.

Overrides:
getAllowedInitParameters in class AbstractRedirect
Returns:
null meaning no check

isStatic

protected boolean isStatic()
Description copied from class: AbstractRedirect

Gets the static property.

Return true to reduce calls to getTo, getSender, getRecipients, getReplyTo, getReversePath amd getMessage where these values don't change (eg hard coded, or got at startup from the mailet config); return false where any of these methods generate their results dynamically eg in response to the message being processed, or by reference to a repository of users.

It is now (from version 2.2) somehow obsolete, as should be always true because the "good practice" is to use "getX()" methods statically, and use instead "getX(Mail)" methods for dynamic situations. A false value is now meaningful only for subclasses of Redirect older than version 2.2 that were relying on this.

Is a "getX()" method.

Overrides:
isStatic in class AbstractRedirect
Returns:
the static init parameter

getInLineType

protected int getInLineType()
                     throws javax.mail.MessagingException
Description copied from class: AbstractRedirect
Gets the inline property. May return one of the following values to indicate how to append the original message to build the new message: Is a "getX()" method.

Overrides:
getInLineType in class AbstractRedirect
Returns:
the inline init parameter
Throws:
javax.mail.MessagingException

getRecipients

protected java.util.Collection getRecipients()
                                      throws javax.mail.MessagingException
Description copied from class: AbstractRedirect
Gets the recipients property. Returns the collection of recipients of the new message, or null if no change is requested. Is a "getX()" method.

Overrides:
getRecipients in class AbstractRedirect
Returns:
the recipients init parameter or the postmaster address or SpecialAddress.SENDER or SpecialAddress.REVERSE_PATH or SpecialAddress.UNALTERED or the to init parameter if missing or null if also the latter is missing
Throws:
javax.mail.MessagingException

getTo

protected javax.mail.internet.InternetAddress[] getTo()
                                               throws javax.mail.MessagingException
Description copied from class: AbstractRedirect
Gets the to property. Returns the "To:" recipients of the new message. or null if no change is requested. Is a "getX()" method.

Overrides:
getTo in class AbstractRedirect
Returns:
the to init parameter or the postmaster address or SpecialAddress.SENDER or SpecialAddress.REVERSE_PATH or SpecialAddress.UNALTERED or the recipients init parameter if missing or null if also the latter is missing
Throws:
javax.mail.MessagingException

getReversePath

protected org.apache.mailet.MailAddress getReversePath()
                                                throws javax.mail.MessagingException
Description copied from class: AbstractRedirect
Gets the reversePath property. Returns the reverse-path of the new message, or null if no change is requested. Is a "getX()" method.

Overrides:
getReversePath in class AbstractRedirect
Returns:
the reversePath init parameter or the postmaster address or SpecialAddress.SENDER or SpecialAddress.NULL or null if missing
Throws:
javax.mail.MessagingException

getReversePath

protected org.apache.mailet.MailAddress getReversePath(org.apache.mailet.Mail originalMail)
                                                throws javax.mail.MessagingException
Description copied from class: AbstractRedirect
Gets the reversePath property, built dynamically using the original Mail object. Is a "getX(Mail)" method.

Overrides:
getReversePath in class AbstractRedirect
Returns:
AbstractRedirect.getReversePath(); if null return AbstractRedirect.getSender(Mail), meaning the new requested sender if any
Throws:
javax.mail.MessagingException


Copyright ? 2002-2009 The Apache Software Foundation. All Rights Reserved.