View Javadoc

1   /************************************************************************
2    * Copyright (c) 2000-2006 The Apache Software Foundation.             *
3    * All rights reserved.                                                *
4    * ------------------------------------------------------------------- *
5    * Licensed under the Apache License, Version 2.0 (the "License"); you *
6    * may not use this file except in compliance with the License. You    *
7    * may obtain a copy of the License at:                                *
8    *                                                                     *
9    *     http://www.apache.org/licenses/LICENSE-2.0                      *
10   *                                                                     *
11   * Unless required by applicable law or agreed to in writing, software *
12   * distributed under the License is distributed on an "AS IS" BASIS,   *
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or     *
14   * implied.  See the License for the specific language governing       *
15   * permissions and limitations under the License.                      *
16   ***********************************************************************/
17  
18  package org.apache.james.transport.matchers;
19  
20  import java.util.Collection;
21  
22  import javax.mail.MessagingException;
23  
24  import org.apache.mailet.GenericMatcher;
25  import org.apache.mailet.Mail;
26  import org.apache.mailet.MatcherConfig;
27  
28  /***
29   * <p>This Matcher determines if the mail contains the attribute specified in
30   * the condition and if the value answered when the method toString() is 
31   * invoked on the attribute is equal to the String value specified in the
32   * condition. If both tests are true, all recipients are returned, else null.
33   * </p>
34   * 
35   * <p>Notes:</p>
36   * <p>The current matcher implementation expects a single String value to match
37   * on. This matcher requires two values, the attribute name and attribute
38   * value. This requires some implicit rules to govern how the single value
39   * supplied to the matcher is parsed into two values.</p> 
40   * <ul>
41   * <li>In the match condition, the split between the attribute name and the
42   * attribute value is made at the first comma. Attribute names that include
43   * a comma will parse incorrectly and therefore are not supported by this
44   * matcher.
45   * </li>
46   * <li>Leading and trailing spaces are removed from both the attribute name and
47   * attribute value specified in the condition and the tested attribute value in
48   * the mail prior to matching. Therefore, "abc" , " abc", "abc " and " abc " 
49   * are considered equivalent.
50   * </li>
51   * <li>To test for an empty string, do not specify an attribute value after the
52   * comma.
53   * </li>
54   * </ul>
55   * 
56   * <p>Sample configuration:</p>
57   * <pre><code>
58   * &lt;mailet match="HasMailAttributeWithValue=name, value" class=&quot;&lt;any-class&gt;&quot;&gt;
59   * </code></pre>
60   *
61   * @version CVS $Revision: 365582 $ $Date: 2006-01-03 08:51:21 +0000 (mar, 03 gen 2006) $
62   * @since 2.2.0
63   **/
64  public class HasMailAttributeWithValue extends GenericMatcher
65  {
66  
67      /***
68       * The name of the attribute to match
69       */    
70      private String fieldAttributeName;
71  
72      /***
73       * The value of the attribute to match
74       */        
75      private String fieldAttributeValue;
76      
77  
78      /***
79       * <p>Answers the recipients of the mail if the attribute is present,
80       * and has a toString() value equal to the configured value.</p>
81       * 
82       * @see org.apache.mailet.Matcher#match(Mail)
83       */
84      public Collection match(Mail mail) throws MessagingException
85      {
86          Object attributeValue = mail.getAttribute(getAttributeName());
87  
88          if (attributeValue != null
89              && attributeValue.toString().trim().equals(getAttributeValue()))
90              return mail.getRecipients();
91          return null;
92      }
93  
94      /***
95       * Returns the attributeName.
96       * @return String
97       */
98      protected String getAttributeName()
99      {
100         return fieldAttributeName;
101     }
102 
103     /***
104      * Returns the attributeValue.
105      * @return String
106      */
107     protected String getAttributeValue()
108     {
109         return fieldAttributeValue;
110     }
111 
112     /***
113      * Sets the attributeName.
114      * @param attributeName The attributeName to set
115      */
116     protected void setAttributeName(String attributeName)
117     {
118         fieldAttributeName = attributeName;
119     }
120 
121     /***
122      * Sets the attributeValue.
123      * @param attributeValue The attributeValue to set
124      */
125     protected void setAttributeValue(String attributeValue)
126     {
127         fieldAttributeValue = attributeValue;
128     }
129 
130     /***
131      * @see org.apache.mailet.Matcher#init(MatcherConfig)
132      */
133     public void init(MatcherConfig config) throws MessagingException
134     {
135         super.init(config);
136         String condition = config.getCondition().trim();
137         int commaPosition = condition.indexOf(',');
138 
139         if (-1 == commaPosition)
140             throw new MessagingException("Syntax Error. Missing ','.");
141 
142         if (0 == commaPosition)
143             throw new MessagingException("Syntax Error. Missing attribute name.");
144 
145         setAttributeName(condition.substring(0, commaPosition).trim());
146         setAttributeValue(condition.substring(commaPosition + 1).trim());
147     }
148     
149     /***
150      * Return a string describing this matcher.
151      *
152      * @return a string describing this matcher
153      */
154     public String getMatcherInfo() {
155         return "Has Mail Attribute With Value Matcher";
156     }
157 }