View Javadoc

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&lt;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 }