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.matchers;
21  
22  import java.util.Collection;
23  
24  import javax.mail.MessagingException;
25  
26  import org.apache.mailet.GenericMatcher;
27  import org.apache.mailet.Mail;
28  import org.apache.mailet.MatcherConfig;
29  
30  /***
31   * <p>This Matcher determines if the mail contains the attribute specified in
32   * the condition and if the value answered when the method toString() is 
33   * invoked on the attribute is equal to the String value specified in the
34   * condition. If both tests are true, all recipients are returned, else null.
35   * </p>
36   * 
37   * <p>Notes:</p>
38   * <p>The current matcher implementation expects a single String value to match
39   * on. This matcher requires two values, the attribute name and attribute
40   * value. This requires some implicit rules to govern how the single value
41   * supplied to the matcher is parsed into two values.</p> 
42   * <ul>
43   * <li>In the match condition, the split between the attribute name and the
44   * attribute value is made at the first comma. Attribute names that include
45   * a comma will parse incorrectly and therefore are not supported by this
46   * matcher.
47   * </li>
48   * <li>Leading and trailing spaces are removed from both the attribute name and
49   * attribute value specified in the condition and the tested attribute value in
50   * the mail prior to matching. Therefore, "abc" , " abc", "abc " and " abc " 
51   * are considered equivalent.
52   * </li>
53   * <li>To test for an empty string, do not specify an attribute value after the
54   * comma.
55   * </li>
56   * </ul>
57   * 
58   * <p>Sample configuration:</p>
59   * <pre><code>
60   * &lt;mailet match="HasMailAttributeWithValue=name, value" class=&quot;&lt;any-class&gt;&quot;&gt;
61   * </code></pre>
62   *
63   * @version CVS $Revision: 494012 $ $Date: 2007-01-08 10:23:58 +0000 (Mon, 08 Jan 2007) $
64   * @since 2.2.0
65   **/
66  public class HasMailAttributeWithValue extends GenericMatcher
67  {
68  
69      /***
70       * The name of the attribute to match
71       */    
72      private String fieldAttributeName;
73  
74      /***
75       * The value of the attribute to match
76       */        
77      private String fieldAttributeValue;
78      
79  
80      /***
81       * <p>Answers the recipients of the mail if the attribute is present,
82       * and has a toString() value equal to the configured value.</p>
83       * 
84       * @see org.apache.mailet.Matcher#match(Mail)
85       */
86      public Collection match(Mail mail) throws MessagingException
87      {
88          Object attributeValue = mail.getAttribute(getAttributeName());
89  
90          if (attributeValue != null
91              && attributeValue.toString().trim().equals(getAttributeValue()))
92              return mail.getRecipients();
93          return null;
94      }
95  
96      /***
97       * Returns the attributeName.
98       * @return String
99       */
100     protected String getAttributeName()
101     {
102         return fieldAttributeName;
103     }
104 
105     /***
106      * Returns the attributeValue.
107      * @return String
108      */
109     protected String getAttributeValue()
110     {
111         return fieldAttributeValue;
112     }
113 
114     /***
115      * Sets the attributeName.
116      * @param attributeName The attributeName to set
117      */
118     protected void setAttributeName(String attributeName)
119     {
120         fieldAttributeName = attributeName;
121     }
122 
123     /***
124      * Sets the attributeValue.
125      * @param attributeValue The attributeValue to set
126      */
127     protected void setAttributeValue(String attributeValue)
128     {
129         fieldAttributeValue = attributeValue;
130     }
131 
132     /***
133      * @see org.apache.mailet.Matcher#init(MatcherConfig)
134      */
135     public void init(MatcherConfig config) throws MessagingException
136     {
137         super.init(config);
138         String condition = config.getCondition().trim();
139         int commaPosition = condition.indexOf(',');
140 
141         if (-1 == commaPosition)
142             throw new MessagingException("Syntax Error. Missing ','.");
143 
144         if (0 == commaPosition)
145             throw new MessagingException("Syntax Error. Missing attribute name.");
146 
147         setAttributeName(condition.substring(0, commaPosition).trim());
148         setAttributeValue(condition.substring(commaPosition + 1).trim());
149     }
150     
151     /***
152      * Return a string describing this matcher.
153      *
154      * @return a string describing this matcher
155      */
156     public String getMatcherInfo() {
157         return "Has Mail Attribute With Value Matcher";
158     }
159 }