1 /************************************************************************
2 * Copyright (c) 1999-2006 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 }