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