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.jsieve.mail;
21
22 import java.util.List;
23
24 import org.apache.jsieve.SieveContext;
25 import org.apache.jsieve.exception.InternetAddressException;
26 import org.apache.jsieve.exception.SieveException;
27
28 /**
29 * <p>
30 * Interface <code>MailAdapter</code> defines the minimum functionality
31 * required of of a class implementing a mail message. This is the functionality
32 * neccesary to implement the Commands and Tests that RFC32028 mandates MUST be
33 * implemented.
34 * </p>
35 *
36 * <p>
37 * Typically, implementations will wrap an application's pre-existing mail
38 * message implementation. It is expected that implementations will extend the
39 * minimum level of functionality to provide support for Command and Test
40 * extensions that exploit the capabilities of a particular application.
41 * </p>
42 *
43 * <h4>Implementing parseAddresses</h4>
44 * <p>
45 * <a href='http://james.apache.org/mime4j'>Apache Mime4J</a> is a parser for
46 * <abbr title='Multipurpose Internet Mail Extensions'> <a
47 * href='http://www.faqs.org/rfcs/rfc2045.html'>MIME</a></abbr>. It can easily
48 * be used to parse an address string into addresses. For example:
49 * </p>
50 * <code><pre>
51 * import org.apache.james.mime4j.field.address.AddressList;
52 * import org.apache.james.mime4j.field.address.Mailbox;
53 * import org.apache.james.mime4j.field.address.MailboxList;
54 * import org.apache.james.mime4j.field.address.parser.ParseException;
55 * ...
56 * public Address[] parseAddresses(String arg) throws SieveMailException, InternetAddressException {
57 * try {
58 * final MailboxList list = AddressList.parse(arg).flatten();
59 * final int size = list.size();
60 * final Address[] results = new Address[size];
61 * for (int i=0;i<size;i++) {
62 * final Mailbox mailbox = list.get(i);
63 * results[i] = new AddressImpl(mailbox.getLocalPart(), mailbox.getDomain());
64 * }
65 * return null;
66 * } catch (ParseException e) {
67 * throw new InternetAddressException(e);
68 * }
69 * }
70 * </pre></code>
71 */
72 public interface MailAdapter {
73
74 /**
75 * <p>Sets the context for the current sieve script execution.</p>
76 * <p>Sieve engines <code>MUST</code> set this property before any calls
77 * related to the execution of a script are made.</p>
78 * <p>Implementations intended to be shared between separate threads of
79 * execution <code>MUST</code> ensure that they manage concurrency contexts,
80 * for example by storage in a thread local variable. Engines <code>MUST</code>
81 * - for a script execution - ensure that all calls are made within the
82 * same thread of execution.</p>
83 * @param context the current context,
84 * or null to clear the contest once the execution of a script has completed.
85 */
86 public void setContext(SieveContext context);
87
88 /**
89 * Method getActions answers the List of Actions accumulated by the
90 * receiver. Implementations may elect to supply an unmodifiable collection.
91 *
92 * @return <code>List</code> of {@link Action}'s, not null, possibly
93 * unmodifiable
94 */
95 public List<Action> getActions();
96
97 /**
98 * Method getHeader answers a List of all of the headers in the receiver
99 * whose name is equal to the passed name. If no headers are found an empty
100 * List is returned.
101 *
102 * @param name
103 * @return <code>List</code> not null, possibly empty, possible
104 * unmodifiable
105 * @throws SieveMailException
106 */
107 public List<String> getHeader(String name) throws SieveMailException;
108
109 /**
110 * <p>
111 * Method getMatchingHeader answers a List of all of the headers in the
112 * receiver with the passed name. If no headers are found an empty List is
113 * returned.
114 * </p>
115 *
116 * <p>
117 * This method differs from getHeader(String) in that it ignores case and
118 * the whitespace prefixes and suffixes of a header name when performing the
119 * match, as required by RFC 3028. Thus "From", "from ", " From" and " from "
120 * are considered equal.
121 * </p>
122 *
123 * @param name
124 * @return <code>List</code>, not null possibly empty, possible
125 * unmodifiable
126 * @throws SieveMailException
127 */
128 public List<String> getMatchingHeader(String name) throws SieveMailException;
129
130 /**
131 * Method getHeaderNames answers a List of all of the headers in the
132 * receiver. No duplicates are allowed.
133 *
134 * @return <code>List</code>, not null possible empty, possible
135 * unmodifiable
136 * @throws SieveMailException
137 */
138 public List<String> getHeaderNames() throws SieveMailException;
139
140 /**
141 * Method addAction adds an Action to the List of Actions to be performed by
142 * the receiver.
143 *
144 * @param action
145 */
146 public void addAction(Action action);
147
148 /**
149 * Method executeActions. Applies the Actions accumulated by the receiver.
150 */
151 public void executeActions() throws SieveException;
152
153 /**
154 * Method getSize answers the receiver's message size in octets.
155 *
156 * @return int
157 * @throws SieveMailException
158 */
159 int getSize() throws SieveMailException;
160
161 /**
162 * Method getContentType returns string/mime representation of the message
163 * type.
164 *
165 * @return String
166 * @throws SieveMailException
167 */
168 public String getContentType() throws SieveMailException;
169
170 /**
171 * Is the given phrase found in the body text of this mail?
172 * This search should be case insensitive.
173 * @param phraseCaseInsensitive the phrase to search
174 * @return true when the mail has a textual body and contains the phrase
175 * (case insensitive), false otherwise
176 * @throws SieveMailException when the search cannot be completed
177 */
178 public boolean isInBodyText(final String phraseCaseInsensitive) throws SieveMailException;
179
180 /**
181 * <p>
182 * Parses the named header value into individual addresses.
183 * </p>
184 *
185 * <p>
186 * Headers should be matched in a way that ignores case and the whitespace
187 * prefixes and suffixes of a header name when performing the match, as
188 * required by RFC 3028. Thus "From", "from ", " From" and " from " are
189 * considered equal.
190 * </p>
191 *
192 * @param headerName
193 * name of the header whose value is to be split
194 * @return addresses listed in the given header not null, possibly empty
195 * @throws InternetAddressException
196 * when the header value is not an address or list of addresses.
197 * Implemetations may elect to support only standard headers
198 * known to containing one or more addresses rather than parsing
199 * the value content
200 * @throws SieveMailException
201 * when the header value cannot be read
202 */
203 public Address[] parseAddresses(String headerName)
204 throws SieveMailException, InternetAddressException;
205
206 /**
207 * Contains address data required for SIEVE processing.
208 */
209 public interface Address {
210
211 /**
212 * Gets the local part of the email address. Specified in <a
213 * href='http://james.apache.org/server/rfclist/basic/rfc0822.txt'>RFC822</a>.
214 *
215 * @return local part, not null
216 */
217 public String getLocalPart();
218
219 /**
220 * Gets the domain part of the email address. Specified in <a
221 * href='http://james.apache.org/server/rfclist/basic/rfc0822.txt'>RFC822</a>.
222 *
223 * @return domain, not null
224 */
225 public String getDomain();
226 }
227 }