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 import java.util.ListIterator;
24
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 * Method getActions answers the List of Actions accumulated by the
75 * receiver. Implementations may elect to supply an unmodifiable collection.
76 *
77 * @return <code>List</code> of {@link Action}'s, not null, possibly
78 * unmodifiable
79 */
80 public List getActions();
81
82 /**
83 * Method getActionIteraror answers an Iterator over the List of Actions
84 * accumulated by the receiver. Implementations may elect to supply an
85 * unmodifiable iterator.
86 *
87 * @return <code>ListIterator</code>, not null, possibly unmodifiable
88 */
89 public ListIterator getActionsIterator();
90
91 /**
92 * Method getHeader answers a List of all of the headers in the receiver
93 * whose name is equal to the passed name. If no headers are found an empty
94 * List is returned.
95 *
96 * @param name
97 * @return <code>List</code> not null, possibly empty, possible
98 * unmodifiable
99 * @throws SieveMailException
100 */
101 public List getHeader(String name) throws SieveMailException;
102
103 /**
104 * <p>
105 * Method getMatchingHeader answers a List of all of the headers in the
106 * receiver with the passed name. If no headers are found an empty List is
107 * returned.
108 * </p>
109 *
110 * <p>
111 * This method differs from getHeader(String) in that it ignores case and
112 * the whitespace prefixes and suffixes of a header name when performing the
113 * match, as required by RFC 3028. Thus "From", "from ", " From" and " from "
114 * are considered equal.
115 * </p>
116 *
117 * @param name
118 * @return <code>List</code>, not null possibly empty, possible
119 * unmodifiable
120 * @throws SieveMailException
121 */
122 public List getMatchingHeader(String name) throws SieveMailException;
123
124 /**
125 * Method getHeaderNames answers a List of all of the headers in the
126 * receiver. No duplicates are allowed.
127 *
128 * @return <code>List</code>, not null possible empty, possible
129 * unmodifiable
130 * @throws SieveMailException
131 */
132 public List getHeaderNames() throws SieveMailException;
133
134 /**
135 * Method addAction adds an Action to the List of Actions to be performed by
136 * the receiver.
137 *
138 * @param action
139 */
140 public void addAction(Action action);
141
142 /**
143 * Method executeActions. Applies the Actions accumulated by the receiver.
144 */
145 public void executeActions() throws SieveException;
146
147 /**
148 * Method getSize answers the receiver's message size in octets.
149 *
150 * @return int
151 * @throws SieveMailException
152 */
153 int getSize() throws SieveMailException;
154
155 /**
156 * Method getContentType returns string/mime representation of the message
157 * type.
158 *
159 * @return String
160 * @throws SieveMailException
161 */
162 public String getContentType() throws SieveMailException;
163
164 /**
165 * Method getContent returns object containing the message content. TODO:
166 * This is poorly defined. TODO: This is used to search a mail body and
167 * needs to return a string. TODO: But creating a string is not efficient.
168 * TODO: It would be better to allow the adapter to search.
169 *
170 * @return Object
171 * @throws SieveMailException
172 */
173 public Object getContent() throws SieveMailException;
174
175 /**
176 * <p>
177 * Parses the named header value into individual addresses.
178 * </p>
179 *
180 * <p>
181 * Headers should be matched in a way that ignores case and the whitespace
182 * prefixes and suffixes of a header name when performing the match, as
183 * required by RFC 3028. Thus "From", "from ", " From" and " from " are
184 * considered equal.
185 * </p>
186 *
187 * @param headerName
188 * name of the header whose value is to be split
189 * @return addresses listed in the given header not null, possibly empty
190 * @throws InternetAddressException
191 * when the header value is not an address or list of addresses.
192 * Implemetations may elect to support only standard headers
193 * known to containing one or more addresses rather than parsing
194 * the value content
195 * @throws SieveMailException
196 * when the header value cannot be read
197 */
198 public Address[] parseAddresses(String headerName)
199 throws SieveMailException, InternetAddressException;
200
201 /**
202 * Contains address data required for SIEVE processing.
203 */
204 public interface Address {
205
206 /**
207 * Gets the local part of the email address. Specified in <a
208 * href='http://james.apache.org/server/rfclist/basic/rfc0822.txt'>RFC822</a>.
209 *
210 * @return local part, not null
211 */
212 public String getLocalPart();
213
214 /**
215 * Gets the domain part of the email address. Specified in <a
216 * href='http://james.apache.org/server/rfclist/basic/rfc0822.txt'>RFC822</a>.
217 *
218 * @return domain, not null
219 */
220 public String getDomain();
221 }
222 }