MailetContext


1   /***********************************************************************
2    * Copyright (c) 1999-2004 The Apache Software Foundation.             *
3    * All rights reserved.                                                *
4    * ------------------------------------------------------------------- *
5    * Licensed under the Apache License, Version 2.0 (the "License"); you *
6    * may not use this file except in compliance with the License. You    *
7    * may obtain a copy of the License at:                                *
8    *                                                                     *
9    *     http://www.apache.org/licenses/LICENSE-2.0                      *
10   *                                                                     *
11   * Unless required by applicable law or agreed to in writing, software *
12   * distributed under the License is distributed on an "AS IS" BASIS,   *
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or     *
14   * implied.  See the License for the specific language governing       *
15   * permissions and limitations under the License.                      *
16   ***********************************************************************/
17  
18  package org.apache.mailet;
19  
20  import java.util.Collection  ;
21  import java.util.Iterator  ;
22  
23  import javax.mail.MessagingException  ;
24  import javax.mail.internet.MimeMessage  ;
25  
26  /**
27   * Defines a set of methods that a mailet or matcher uses to communicate
28   * with its mailet container, for example, to send a new message, to
29   * deliver a message locally, or write to a log file.
30   *
31   * The MailetContext object is contained within the MailetConfig and
32   * MatcherConfig objects, which the mailet container provides to the
33   * mailets and matchers when they are initialized.
34   *
35   * @version 1.0.0, 24/04/1999
36   */
37  public interface MailetContext {
38  
39      /**
40       * Bounces the message using a standard format with the given message.
41       * The message will be sent back to the sender from the postmaster as specified for
42       * this mailet context, adding message to top of mail server queue using
43       * sendMail().
44       *
45       * @param mail - the message that is to be bounced and sender to whom to return the message
46       * @param message - a descriptive message as to why the message bounced
47       */
48      void bounce(Mail mail, String   message) throws MessagingException  ;
49  
50      /**
51       * Bounces the email message using the provided email address as the
52       * sender of the bounce.
53       *
54       * @param mail - the message that is to be bounced and sender to whom to return the message
55       * @param message - a descriptive message as to why the message bounced
56       * @param bouncer - the address to give as the sender of the bounced message
57       */
58      void bounce(Mail mail, String   message, MailAddress bouncer) throws MessagingException  ;
59  
60      /**
61       * Returns a Collection of Strings of hostnames or ip addresses that
62       * are specified as mail server listeners for the given hostname.
63       * This is done using MX records, and the hostnames or ip addresses
64       * are returned sorted by MX priority.
65       *
66       * @param host - the domain name for which to find mail servers
67       * @return a Collection of Strings of hostnames, sorted by priority
68       */
69      Collection   getMailServers(String   host);
70  
71      /**
72       * Returns the postmaster's address for this mailet context.
73       *
74       * @return a MailAddress of the Postmaster's address
75       */
76      MailAddress getPostmaster();
77  
78      /**
79       * Returns the mailet container attribute with the given name, or null
80       * if there is no attribute by that name.  An attribute allows a mailet container
81       * to give the mailet additional information not already provided by this interface.
82       * See your server documentation for information about its attributes. A list of
83       * supported attributes can be retrieved using getAttributeNames.
84       * <p>
85       * The attribute is returned as a java.lang.Object or some subclass. Attribute
86       * names should follow the same convention as package names. The Java Mailet API
87       * specification reserves names matching java.*, javax.*, and sun.*
88       *
89       * @param name - a String specifying the name of the attribute
90       * @return an Object containing the value of the attribute, or null if no attribute
91       *      exists matching the given name
92       */
93      Object   getAttribute(String   name);
94  
95      /**
96       * Returns an Iterator containing the attribute names available within
97       * this mailet context.  Use the getAttribute(java.lang.String) method with an
98       * attribute name to get the value of an attribute.
99       *
100      * @return an Iterator of attribute names
101      */
102     Iterator   getAttributeNames();
103 
104     /**
105      * Returns the major version of the Mailet API that this mailet
106      * container supports. All implementations that comply with Version 1.2 must have
107      * this method return the integer 1.
108      *
109      * @return 1
110      */
111     int getMajorVersion();
112 
113     /**
114      * Returns the minor version of the Mailet API that this mailet
115      * container supports.  All implementations that comply with Version 1.2 must have
116      * this method return the integer 2.
117      *
118      * @return 2
119      */
120     int getMinorVersion();
121 
122     /**
123      * Returns the name and version of the mailet container on which
124      * the mailet is running.
125      * <p>
126      * The form of the returned string is servername/versionnumber. For example,
127      * JAMES may return the string JAMES/1.2.
128      * <p>
129      * The mailet container may return other optional information after the primary
130      * string in parentheses, for example, JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86).
131      *
132      * @return a String containing at least the mailet container name and version number
133      */
134     String   getServerInfo();
135 
136     /**
137      * Checks if a server is serviced by mail context
138      *
139      * @param serverName - name of server.
140      * @return true if server is local, i.e. serviced by this mail context
141      */
142     boolean isLocalServer(String   serverName);
143 
144     /**
145      * Checks if a user account is exists in the mail context.
146      *
147      * @param userAccount - user identifier.
148      * @return true if the acount is a local account
149      */
150     boolean isLocalUser(String   userAccount);
151 
152     /**
153      * Writes the specified message to a mailet log file, usually an event
154      * log.  The name and type of the mailet log file is specific to the mailet
155      * container.
156      *
157      * @param message - a String specifying the message to be written to the log file
158      */
159     void log(String   message);
160 
161     /**
162      * Writes an explanatory message and a stack trace for a given Throwable
163      * exception to the mailet log file.
164      *
165      * @param message - a String that describes the error or exception
166      * @param throwable - the Throwable error or exception
167      */
168     void log(String   message, Throwable   t);
169 
170     /**
171      * Removes the attribute with the given name from the mailet context.  After
172      * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
173      * the attribute's value will return null.
174      *
175      * @param name - a String specifying the name of the attribute to be removed
176      */
177     void removeAttribute(String   name);
178 
179     /**
180      * Send an outgoing message to the top of this mailet container's root queue.
181      * This is the equivalent of opening an SMTP session to localhost.
182      * This uses sender and recipients as specified in the message itself.
183      *
184      * @param msg - the MimeMessage of the headers and body content of the outgoing message
185      * @throws MessagingException - if the message fails to parse
186      */
187     void sendMail(MimeMessage   msg)
188         throws MessagingException  ;
189 
190     /**
191      * Send an outgoing message to the top of this mailet container's root queue.
192      * This is the equivalent of opening an SMTP session to localhost.
193      *
194      * @param sender - the sender of the message
195      * @param recipients - a Collection of MailAddress objects of recipients
196      * @param msg - the MimeMessage of the headers and body content of the outgoing message
197      * @throws MessagingException - if the message fails to parse
198      */
199     void sendMail(MailAddress sender, Collection   recipients, MimeMessage   msg)
200         throws MessagingException  ;
201 
202     /**
203      * Send an outgoing message to the top of this mailet container queue for the
204      * appropriate processor that is specified.
205      *
206      * @param sender - the sender of the message
207      * @param recipients - a Collection of MailAddress objects of recipients
208      * @param msg - the MimeMessage of the headers and body content of the outgoing message
209      * @param state - the state of the message, indicates which processor to use
210      * This is a String that names a processor for which the message will be queued
211      * @throws MessagingException - if the message fails to parse
212      */
213     void sendMail(MailAddress sender, Collection   recipients, MimeMessage   msg, String   state)
214         throws MessagingException  ;
215 
216     /**
217      * Send an outgoing message to the top of this mailet container's root queue.
218      * This is the equivalent of opening an SMTP session to localhost.
219      * The Mail object provides all envelope and content information
220      *
221      * @param mail - the message that is to sent
222      * @throws MessagingException - if the message fails to spool
223      */
224     void sendMail(Mail mail)
225             throws MessagingException  ;
226 
227     /**
228      * Binds an object to a given attribute name in this mailet context.  If the name
229      * specified is already used for an attribute, this method will remove the old
230      * attribute and bind the name to the new attribute.
231      * <p>
232      * Attribute names should follow the same convention as package names. The Java
233      * Mailet API specification reserves names matching java.*, javax.*, and sun.*.
234      *
235      * @param name - a String specifying the name of the attribute
236      * @param object - an Object representing the attribute to be bound
237      */
238     void setAttribute(String   name, Object   object);
239 
240     /**
241      * Stores the message is in the local repository associated with
242      * recipient for later retrieval, e.g., by a POP3 or IMAP service.
243      *
244      * @deprecated - use sparingly.  Service will be replaced with
245      * resource acquired via JNDI.
246      * @param sender - the sender of the incoming message
247      * @param recipient - the user who is receiving this message (as a complete email address)
248      * @param msg - the MimeMessage to store in a local mailbox
249      * @throws MessagingException - if the message fails to parse
250      */
251     void storeMail(MailAddress sender, MailAddress recipient, MimeMessage   msg)
252         throws MessagingException  ;
253 
254     /**
255      * Returns an Iterator over HostAddress, a specialized subclass of
256      * javax.mail.URLName, which provides location information for
257      * servers that are specified as mail handlers for the given
258      * hostname.  This is done using MX records, and the HostAddress
259      * instances are returned sorted by MX priority.  If no host is
260      * found for domainName, the Iterator returned will be empty and the
261      * first call to hasNext() will return false.
262      *
263      * @since Mailet API v2.2.0a16-unstable
264      * @param domainName - the domain for which to find mail servers
265      * @return an Iterator over HostAddress instances, sorted by priority
266      */
267     Iterator   getSMTPHostAddresses(String   domainName);
268 }
269
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags