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