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 package org.apache.jsieve.mail;
22
23 import java.util.List;
24 import java.util.ListIterator;
25
26 import org.apache.jsieve.InternetAddressException;
27 import org.apache.jsieve.SieveException;
28
29 /***
30 * <p>Interface <code>MailAdapter</code> defines the minimum functionality required of
31 * of a class implementing a mail message. This is the functionality neccesary to
32 * implement the Commands and Tests that RFC32028 mandates MUST be implemented.
33 * </p>
34 *
35 * <p>Typically, implementations will wrap an application's pre-existing mail
36 * message implementation. It is expected that implementations will extend the
37 * minimum level of functionality to provide support for Command and Test
38 * extensions that exploit the capabilities of a particular application.</p>
39 */
40 public interface MailAdapter
41 {
42 /***
43 * Method getActions answers the List of Actions accumulated by the receiver.
44 * Implementations may elect to supply an unmodifiable collection.
45 * @return <code>List</code> of {@link Action}'s, not null, possibly unmodifiable
46 */
47 public List getActions();
48
49 /***
50 * Method getActionIteraror answers an Iterator over the List of Actions
51 * accumulated by the receiver. Implementations may elect to supply
52 * an unmodifiable iterator.
53 * @return <code>ListIterator</code>, not null, possibly unmodifiable
54 */
55 public ListIterator getActionsIterator();
56
57 /***
58 * Method getHeader answers a List of all of the headers in the receiver whose
59 * name is equal to the passed name. If no headers are found an empty List is
60 * returned.
61 *
62 * @param name
63 * @return <code>List</code> not null, possibly empty, possible unmodifiable
64 * @throws SieveMailException
65 */
66 public List getHeader(String name) throws SieveMailException;
67
68 /***
69 * <p>Method getMatchingHeader answers a List of all of the headers in the
70 * receiver with the passed name. If no headers are found an empty List is
71 * returned.
72 * </p>
73 *
74 * <p>This method differs from getHeader(String) in that it ignores case and the
75 * whitespace prefixes and suffixes of a header name when performing the
76 * match, as required by RFC 3028. Thus "From", "from ", " From" and " from "
77 * are considered equal.
78 * </p>
79 *
80 * @param name
81 * @return <code>List</code>, not null possibly empty, possible unmodifiable
82 * @throws SieveMailException
83 */
84 public List getMatchingHeader(String name)
85 throws SieveMailException;
86
87 /***
88 * Method getHeaderNames answers a List of all of the headers in the receiver.
89 * No duplicates are allowed.
90 * @return <code>List</code>, not null possible empty, possible unmodifiable
91 * @throws SieveMailException
92 */
93 public List getHeaderNames() throws SieveMailException;
94
95 /***
96 * Method addAction adds an Action to the List of Actions to be performed by the
97 * receiver.
98 * @param action
99 */
100 public void addAction(Action action);
101
102 /***
103 * Method executeActions. Applies the Actions accumulated by the receiver.
104 */
105 public void executeActions() throws SieveException;
106
107 /***
108 * Method getSize answers the receiver's message size in octets.
109 * @return int
110 * @throws SieveMailException
111 */
112 int getSize() throws SieveMailException;
113
114
115 /***
116 * Method getContentType returns string/mime representation of the
117 * message type.
118 * @return String
119 * @throws SieveMailException
120 */
121 public String getContentType() throws SieveMailException;
122
123 /***
124 * Method getContent returns object containing the message content.
125 * @return Object
126 * @throws SieveMailException
127 */
128 public Object getContent() throws SieveMailException;
129
130 /***
131 * <p>Parses the named header value into individual addresses.</p>
132 *
133 * <p>Headers should be matched in a way that ignores case and the
134 * whitespace prefixes and suffixes of a header name when performing the
135 * match, as required by RFC 3028. Thus "From", "from ", " From" and " from "
136 * are considered equal.
137 * </p>
138 *
139 * @param headerName name of the header whose value is to be split
140 * @return addresses listed in the given header not null, possibly empty
141 * @throws InternetAddressException when the header value is not an address
142 * or list of addresses. Implemetations may elect to support only
143 * standard headers known to containing one or more addresses rather
144 * than parsing the value
145 * content
146 * @throws SieveMailException when the header value cannot be read
147 */
148 public Address[] parseAddresses(String headerName) throws SieveMailException, InternetAddressException;
149
150 /***
151 * Contains address data required for SIEVE processing.
152 */
153 public interface Address {
154
155 /***
156 * Gets the local part of the email address.
157 * Specified in
158 * <a href='http://james.apache.org/server/rfclist/basic/rfc0822.txt'>RFC822</a>.
159 * @return local part, not null
160 */
161 public String getLocalPart();
162
163 /***
164 * Gets the domain part of the email address.
165 * Specified in
166 * <a href='http://james.apache.org/server/rfclist/basic/rfc0822.txt'>RFC822</a>.
167 * @return domain, not null
168 */
169 public String getDomain();
170 }
171 }