org.apache.jsieve.mail.MailAdapter Maven / Gradle / Ivy
Show all versions of apache-jsieve Show documentation
/****************************************************************
* Licensed to the Apache Software Foundation (ASF) under one *
* or more contributor license agreements. See the NOTICE file *
* distributed with this work for additional information *
* regarding copyright ownership. The ASF licenses this file *
* to you under the Apache License, Version 2.0 (the *
* "License"); you may not use this file except in compliance *
* with the License. You may obtain a copy of the License at *
* *
* http://www.apache.org/licenses/LICENSE-2.0 *
* *
* Unless required by applicable law or agreed to in writing, *
* software distributed under the License is distributed on an *
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
* KIND, either express or implied. See the License for the *
* specific language governing permissions and limitations *
* under the License. *
****************************************************************/
package org.apache.jsieve.mail;
import java.util.List;
import java.util.ListIterator;
import org.apache.jsieve.exception.InternetAddressException;
import org.apache.jsieve.exception.SieveException;
/**
*
* Interface MailAdapter defines the minimum functionality
* required of of a class implementing a mail message. This is the functionality
* neccesary to implement the Commands and Tests that RFC32028 mandates MUST be
* implemented.
*
*
*
* Typically, implementations will wrap an application's pre-existing mail
* message implementation. It is expected that implementations will extend the
* minimum level of functionality to provide support for Command and Test
* extensions that exploit the capabilities of a particular application.
*
*
* Implementing parseAddresses
*
* Apache Mime4J is a parser for
* MIME. It can easily
* be used to parse an address string into addresses. For example:
*
*
* import org.apache.james.mime4j.field.address.AddressList;
* import org.apache.james.mime4j.field.address.Mailbox;
* import org.apache.james.mime4j.field.address.MailboxList;
* import org.apache.james.mime4j.field.address.parser.ParseException;
* ...
* public Address[] parseAddresses(String arg) throws SieveMailException, InternetAddressException {
* try {
* final MailboxList list = AddressList.parse(arg).flatten();
* final int size = list.size();
* final Address[] results = new Address[size];
* for (int i=0;i<size;i++) {
* final Mailbox mailbox = list.get(i);
* results[i] = new AddressImpl(mailbox.getLocalPart(), mailbox.getDomain());
* }
* return null;
* } catch (ParseException e) {
* throw new InternetAddressException(e);
* }
* }
* List of {@link Action}'s, not null, possibly
* unmodifiable
*/
public List getActions();
/**
* Method getActionIteraror answers an Iterator over the List of Actions
* accumulated by the receiver. Implementations may elect to supply an
* unmodifiable iterator.
*
* @return ListIterator, not null, possibly unmodifiable
*/
public ListIterator getActionsIterator();
/**
* Method getHeader answers a List of all of the headers in the receiver
* whose name is equal to the passed name. If no headers are found an empty
* List is returned.
*
* @param name
* @return List not null, possibly empty, possible
* unmodifiable
* @throws SieveMailException
*/
public List getHeader(String name) throws SieveMailException;
/**
*
* Method getMatchingHeader answers a List of all of the headers in the
* receiver with the passed name. If no headers are found an empty List is
* returned.
*
*
*
* This method differs from getHeader(String) in that it ignores case and
* the whitespace prefixes and suffixes of a header name when performing the
* match, as required by RFC 3028. Thus "From", "from ", " From" and " from "
* are considered equal.
*
*
* @param name
* @return List, not null possibly empty, possible
* unmodifiable
* @throws SieveMailException
*/
public List getMatchingHeader(String name) throws SieveMailException;
/**
* Method getHeaderNames answers a List of all of the headers in the
* receiver. No duplicates are allowed.
*
* @return List, not null possible empty, possible
* unmodifiable
* @throws SieveMailException
*/
public List getHeaderNames() throws SieveMailException;
/**
* Method addAction adds an Action to the List of Actions to be performed by
* the receiver.
*
* @param action
*/
public void addAction(Action action);
/**
* Method executeActions. Applies the Actions accumulated by the receiver.
*/
public void executeActions() throws SieveException;
/**
* Method getSize answers the receiver's message size in octets.
*
* @return int
* @throws SieveMailException
*/
int getSize() throws SieveMailException;
/**
* Method getContentType returns string/mime representation of the message
* type.
*
* @return String
* @throws SieveMailException
*/
public String getContentType() throws SieveMailException;
/**
* Method getContent returns object containing the message content. TODO:
* This is poorly defined. TODO: This is used to search a mail body and
* needs to return a string. TODO: But creating a string is not efficient.
* TODO: It would be better to allow the adapter to search.
*
* @return Object
* @throws SieveMailException
*/
public Object getContent() throws SieveMailException;
/**
*
* Parses the named header value into individual addresses.
*
*
*
* Headers should be matched in a way that ignores case and the whitespace
* prefixes and suffixes of a header name when performing the match, as
* required by RFC 3028. Thus "From", "from ", " From" and " from " are
* considered equal.
*
*
* @param headerName
* name of the header whose value is to be split
* @return addresses listed in the given header not null, possibly empty
* @throws InternetAddressException
* when the header value is not an address or list of addresses.
* Implemetations may elect to support only standard headers
* known to containing one or more addresses rather than parsing
* the value content
* @throws SieveMailException
* when the header value cannot be read
*/
public Address[] parseAddresses(String headerName)
throws SieveMailException, InternetAddressException;
/**
* Contains address data required for SIEVE processing.
*/
public interface Address {
/**
* Gets the local part of the email address. Specified in RFC822.
*
* @return local part, not null
*/
public String getLocalPart();
/**
* Gets the domain part of the email address. Specified in RFC822.
*
* @return domain, not null
*/
public String getDomain();
}
}