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 }