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
21 package org.apache.mailet;
22
23 import java.util.Collection;
24 import java.util.Iterator;
25
26 import javax.mail.MessagingException;
27 import javax.mail.internet.MimeMessage;
28
29 /**
30 * Defines a set of methods that can be used to interact with the mailet
31 * container. For example, it can be used to send a new message, to deliver
32 * a message locally, or to write to a log file.
33 * <p>
34 * Mailets and Matchers can retrieve a MailetContext through their
35 * respective MailetConfig and MatcherConfig objects, which are provided
36 * to them by the mailet container when they are initialized.
37 * <p>
38 * <b>Mailet Context Attributes</b>
39 * <p>
40 * The Mailet Context can provide additional configuration or other
41 * information not defined in this interface to Mailets and Matchers
42 * by using attributes. See your server documentation for information
43 * on the attributes it provides.
44 * <p>
45 * Every attribute consists of a name and a value.
46 * Attribute names should follow the same convention as package names.
47 * The Mailet API specification reserves names matching
48 * <i>org.apache.james.*</i> and <i>org.apache.mailet.*</i>.
49 * Attribute values can be arbitrary objects.
50 * <p>
51 * The list of attributes which are currently associated with a mailet
52 * context can be retrieved using the {@link #getAttributeNames}
53 * method, and given its name, the value of an attribute can be
54 * retrieved using the {@link #getAttribute} method.
55 *
56 */
57 public interface MailetContext {
58
59 /**
60 * Returns the major version number of the Mailet API that this mailet
61 * container supports. For example, if the mailet container supports
62 * version 1.2 of the Mailet API, this method returns 1.
63 *
64 * @return the major version number of the supported Mailet API
65 */
66 int getMajorVersion();
67
68 /**
69 * Returns the minor version number of the Mailet API that this mailet
70 * container supports. For example, if the mailet container supports
71 * version 1.2 of the Mailet API, this method returns 2.
72 *
73 * @return the minor version number of the supported Mailet API
74 */
75 int getMinorVersion();
76
77 /**
78 * Returns the name and version of the mailet container on which
79 * the mailet is running.
80 * <p>
81 * The returned string is of the form {@code <servername>/<versionnumber>},
82 * optionally followed by additional information in parentheses. For example,
83 * the JAMES mailet container may return the string {@code "JAMES/1.2"}
84 * or {@code "JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86)"}.
85 *
86 * @return the server information string
87 */
88 String getServerInfo();
89
90 /**
91 * Returns an Iterator over the names of all attributes which are set
92 * in this mailet context.
93 * <p>
94 * The {@link #getAttribute} method can be called to
95 * retrieve an attribute's value given its name.
96 *
97 * @return an Iterator (of Strings) over all attribute names
98 */
99 Iterator getAttributeNames();
100
101 /**
102 * Returns the value of the named mailet context attribute,
103 * or null if the attribute does not exist.
104 *
105 * @param name the attribute name
106 * @return the attribute value, or null if the attribute does not exist
107 */
108 Object getAttribute(String name);
109
110 /**
111 * Binds an object to a given attribute name in this mailet context. If the name
112 * specified is already used for an attribute, this method will remove the old
113 * attribute and bind the name to the new attribute.
114 * <p>
115 * Attribute names should follow the same convention as package names. The Java
116 * Mailet API specification reserves names matching java.*, javax.*, and sun.*.
117 *
118 * @param name - a String specifying the name of the attribute
119 * @param object - an Object representing the attribute to be bound
120 */
121
122 /**
123 * Associates an attribute with the given name and value with this mailet context.
124 * <p>
125 * If an attribute with the given name already exists, it is replaced, and the
126 * previous value is returned.
127 * <p>
128 * Attribute names should follow the same convention as package names.
129 * The Mailet API specification reserves names matching
130 * <i>org.apache.james.*</i> and <i>org.apache.mailet.*</i>.
131 *
132 * @param name the attribute name
133 * @param value the attribute value
134 */
135 void setAttribute(String name, Object value);
136
137 /**
138 * Removes the attribute with the given name from this Mail instance.
139 *
140 * @param name the name of the attribute to be removed
141 * @since Mailet API v2.1
142 */
143 void removeAttribute(String name);
144
145 /**
146 * Writes the specified message to a mailet log. The name and type of
147 * the mailet log is specific to the mailet container.
148 *
149 * @param message the message to be written to the log
150 */
151 void log(String message);
152
153 /**
154 * Writes the specified message to a mailet log, along with the stack
155 * trace of the given Throwable. The name and type of the mailet log
156 * is specific to the mailet container.
157 *
158 * @param message the message to be written to the log
159 * @param t the Throwable whose stack trace is to be written to the log
160 */
161 void log(String message, Throwable t);
162
163 /**
164 * Returns the Postmaster address for this mailet context.
165 *
166 * @return the Postmaster address
167 */
168 MailAddress getPostmaster();
169
170 /**
171 * Checks if a host name is local, i.e. this server is the
172 * final delivery destination for messages sent to this host.
173 *
174 * @param hostname the host name to check
175 * @return true if server is local, false otherwise
176 */
177 boolean isLocalServer(String hostname);
178
179 /**
180 * Checks if a user account is local, i.e. the account exists locally
181 * and this server is the final delivery destination for messages
182 * sent to this address.
183 * <p>
184 * This given user account string should contain the full
185 * user address, i.e. user@domain. If the domain part is
186 * missing, "localhost" will be used as the domain name.
187 *
188 * @param userAccount the full address of the account to be checked
189 * @return true if the account is a local account, false otherwise
190 * @deprecated use {@link #isLocalEmail(MailAddress)} instead
191 */
192 boolean isLocalUser(String userAccount);
193
194 /**
195 * Checks if an address is local, i.e. its account exists locally
196 * and this server is the final delivery destination for messages
197 * sent to this address.
198 *
199 * @param mailAddress the full address of the account to be checked
200 * @return true if the account is a local account, false otherwise
201 * @since Mailet API 2.4
202 */
203 boolean isLocalEmail(MailAddress mailAddress);
204
205 /**
206 * Returns the hostnames that are specified as mail handlers for
207 * the given domain name. The host names are determined using DNS
208 * lookup of MX records and are returned sorted by priority
209 * (as detailed in the SMTP RFC).
210 *
211 * @param domain the domain name whose mail handling hosts are requested
212 * @return the sorted mail-handling hostnames for the domain
213 */
214 Collection getMailServers(String domain);
215
216 /**
217 * Returns the SMTP host addresses specified as mail handlers for
218 * the given domain name. This is equivalent to calling the
219 * {@link #getMailServers} method and then performing address
220 * resolution lookups on all returned host names in order.
221 * The results are returned as instances of {@link HostAddress}
222 * containing the host and address information.
223 *
224 * @since Mailet API v2.3
225 * @param domain the domain whose mail handling SMTP host addresses are requested
226 * @return an Iterator over HostAddress, in proper order of priority, or
227 * an empty iterator if no hosts are found
228 */
229 Iterator getSMTPHostAddresses(String domain);
230
231 /**
232 * Sends an outgoing message to the top of this mailet container's root queue.
233 * This is functionally equivalent to having opened an SMTP session to the local
234 * host and delivering the message using the sender and recipients from within
235 * the message itself.
236 *
237 * @param message the message to send
238 * @throws MessagingException if an error occurs accessing or sending the message
239 */
240 void sendMail(MimeMessage message)
241 throws MessagingException;
242
243 /**
244 * Sends an outgoing message to the top of this mailet container's root queue.
245 * This is functionally equivalent to having opened an SMTP session to the local
246 * host and delivering the message using the given sender and recipients.
247 *
248 * @param sender the message sender
249 * @param recipients the message recipients as a Collection of MailAddress objects
250 * @param message the message to send
251 * @throws MessagingException if an error occurs accessing or sending the message
252 */
253 void sendMail(MailAddress sender, Collection recipients, MimeMessage message)
254 throws MessagingException;
255
256 /**
257 * Sends an outgoing message to the top of this mailet container's queue for the
258 * specified processor.
259 *
260 * @param sender the message sender
261 * @param recipients the message recipients as a Collection of MailAddress objects
262 * @param message the message to send
263 * @param state the state of the message, indicating the name of the processor for
264 * which the message will be queued
265 * @throws MessagingException if an error occurs accessing or sending the message
266 */
267 void sendMail(MailAddress sender, Collection recipients, MimeMessage message, String state)
268 throws MessagingException;
269
270 /**
271 * Sends an outgoing message to the top of this mailet container's root queue.
272 * This is the equivalent of opening an SMTP session to localhost.
273 * The Mail object provides all envelope and content information
274 *
275 * @param mail - the message that is to sent
276 * @throws MessagingException if an error occurs accessing or sending the message
277 */
278 void sendMail(Mail mail)
279 throws MessagingException;
280
281 /**
282 * Bounces the message using a standard format with the given message.
283 * <p>
284 * The message will be sent to the original sender from the postmaster address
285 * as configured in this mailet context, adding the message to top of mail
286 * server queue using {@code sendMail}.
287 *
288 * @param mail the message to bounce, with the original sender
289 * @param message a descriptive message explaining why the message bounced
290 * @throws MessagingException if an error occurs accessing or sending the message
291 */
292 void bounce(Mail mail, String message) throws MessagingException;
293
294 /**
295 * Bounces the message using a standard format with the given message.
296 * <p>
297 * The message will be sent to the original sender from the given address,
298 * adding the message to top of mail server queue using {@code sendMail}.
299 *
300 * @param mail the message to bounce, with the original sender
301 * @param message a descriptive message explaining why the message bounced
302 * @param bouncer the address used as the sender of the bounce message
303 * @throws MessagingException if an error occurs accessing or sending the message
304 */
305 void bounce(Mail mail, String message, MailAddress bouncer) throws MessagingException;
306
307 /**
308 * Stores the message is in the local repository associated with
309 * recipient for later retrieval, e.g., by a POP3 or IMAP service.
310 *
311 * @deprecated - use sparingly. Service will be replaced with
312 * resource acquired via JNDI.
313 * @param sender - the sender of the incoming message
314 * @param recipient - the user who is receiving this message (as a complete email address)
315 * @param message - the MimeMessage to store in a local mailbox
316 * @throws MessagingException - if the message fails to parse
317 */
318 void storeMail(MailAddress sender, MailAddress recipient, MimeMessage message)
319 throws MessagingException;
320
321 }