View Javadoc

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 org.apache.mailet.MailAddress;
23  
24  import javax.mail.MessagingException;
25  import javax.mail.internet.InternetAddress;
26  import java.util.HashSet;
27  import java.util.Collection;
28  
29  /***
30   * <P>Sends a notification message to the sender of a message.</P>
31   * <P>A sender of the notification message can optionally be specified.
32   * If one is not specified, the postmaster's address will be used.<BR>
33   * The "To:" header of the notification message can be set to "unaltered";
34   * if missing will be set to the sender of the notified message.<BR>
35   * A notice text can be specified, and in such case will be inserted into the 
36   * notification inline text.<BR>
37   * If the notified message has an "error message" set, it will be inserted into the 
38   * notification inline text. If the <CODE>attachStackTrace</CODE> init parameter
39   * is set to true, such error message will be attached to the notification message.<BR>
40   * The notified messages are attached in their entirety (headers and
41   * content) and the resulting MIME part type is "message/rfc822".</P>
42   * <P>Supports the <CODE>passThrough</CODE> init parameter (true if missing).</P>
43   *
44   * <P>Sample configuration:</P>
45   * <PRE><CODE>
46   * &lt;mailet match="All" class="NotifySender">
47   *   &lt;sender&gt;<I>an address or postmaster or sender or unaltered, default=postmaster</I>&lt;/sender&gt;
48   *   &lt;attachError&gt;<I>true or false, default=false</I>&lt;/attachError&gt;
49   *   &lt;prefix&gt;<I>optional subject prefix prepended to the original message</I>&lt;/prefix&gt;
50   *   &lt;inline&gt;<I>see {@link Resend}, default=none</I>&lt;/inline&gt;
51   *   &lt;attachment&gt;<I>see {@link Resend}, default=message</I>&lt;/attachment&gt;
52   *   &lt;passThrough&gt;<I>true or false, default=true</I>&lt;/passThrough&gt;
53   *   &lt;fakeDomainCheck&gt;<I>true or false, default=true</I>&lt;/fakeDomainCheck&gt;
54   *   &lt;to&gt;<I>unaltered or sender or from(optional, defaults to sender)</I>&lt;/to&gt;
55   *   &lt;debug&gt;<I>true or false, default=false</I>&lt;/debug&gt;
56   * &lt;/mailet&gt;
57   * </CODE></PRE>
58   *
59   * <P>The behaviour of this mailet is equivalent to using Resend with the following
60   * configuration:</P>
61   * <PRE><CODE>
62   * &lt;mailet match="All" class="Resend">
63   *   &lt;sender&gt;<I>an address or postmaster or sender or unaltered</I>&lt;/sender&gt;
64   *   &lt;attachError&gt;<I>true or false</I>&lt;/attachError&gt;
65   *   &lt;message&gt;<I><B>dynamically built</B></I>&lt;/message&gt;
66   *   &lt;prefix&gt;<I>a string</I>&lt;/prefix&gt;
67   *   &lt;passThrough&gt;true&lt;/passThrough&gt;
68   *   &lt;fakeDomainCheck&gt;<I>true or false</I>&lt;/fakeDomainCheck&gt;
69   *   &lt;to&gt;<I>unaltered or sender or from&lt</I>;/to&gt;
70   *   &lt;recipients&gt;<B>sender</B>&lt;/recipients&gt;
71   *   &lt;inline&gt;none&lt;/inline&gt;
72   *   &lt;attachment&gt;message&lt;/attachment&gt;
73   *   &lt;isReply&gt;true&lt;/isReply&gt;
74   *   &lt;debug&gt;<I>true or false</I>&lt;/debug&gt;
75   * &lt;/mailet&gt;
76   * </CODE></PRE>
77   * <P><I>notice</I>, <I>sendingAddress</I> and <I>attachStackTrace</I> can be used instead of
78   * <I>message</I>, <I>sender</I> and <I>attachError</I>; such names are kept for backward compatibility.</P>
79   *
80   * @version CVS $Revision: 494012 $ $Date: 2007-01-08 10:23:58 +0000 (Mon, 08 Jan 2007) $
81   */
82  public class NotifySender extends AbstractNotify {
83  
84      /***
85       * Return a string describing this mailet.
86       *
87       * @return a string describing this mailet
88       */
89      public String getMailetInfo() {
90          return "NotifySender Mailet";
91      }
92  
93      /*** Gets the expected init parameters. */
94      protected  String[] getAllowedInitParameters() {
95          String[] allowedArray = {
96  //            "static",
97              "debug",
98              "passThrough",
99              "fakeDomainCheck",
100             "inline",
101             "attachment",
102             "message",
103             "notice",
104             "sender",
105             "sendingAddress",
106             "prefix",
107             "attachError",
108             "attachStackTrace",
109             "to"
110         };
111         return allowedArray;
112     }
113     
114     /* ******************************************************************** */
115     /* ****************** Begin of getX and setX methods ****************** */
116     /* ******************************************************************** */
117 
118     /***
119      * @return <CODE>SpecialAddress.SENDER</CODE>, indicating the sender of the current mail
120      */
121     protected Collection getRecipients() {
122         Collection newRecipients = new HashSet();
123         newRecipients.add(SpecialAddress.SENDER);
124         return newRecipients;
125     }
126 
127     /***
128      * @return <CODE>SpecialAddress.UNALTERED</CODE> if specified or <CODE>SpecialAddress.SENDER</CODE> if missing
129      */
130     protected InternetAddress[] getTo() throws MessagingException {
131         String addressList = getInitParameter("to");
132         InternetAddress[] iaarray = new InternetAddress[1];
133         iaarray[0] = SpecialAddress.SENDER.toInternetAddress();
134         if (addressList != null) {
135             MailAddress specialAddress = getSpecialAddress(addressList,
136                                             new String[] {"sender", "unaltered", "from"});
137             if (specialAddress != null) {
138                 iaarray[0] = specialAddress.toInternetAddress();
139             } else {
140                 log("\"to\" parameter ignored, set to sender");
141             }
142         }
143         return iaarray;
144     }
145 
146     /***
147      * @return the <CODE>attachStackTrace</CODE> init parameter, 
148      * or the <CODE>attachError</CODE> init parameter if missing,
149      * or false if missing 
150      */
151     protected boolean attachError() throws MessagingException {
152         String parameter = getInitParameter("attachStackTrace");
153         if (parameter == null) {
154             return super.attachError();
155         }        
156         return new Boolean(parameter).booleanValue();
157     }
158 
159     /* ******************************************************************** */
160     /* ******************* End of getX and setX methods ******************* */
161     /* ******************************************************************** */
162     
163 }
164