1 /*
2 * Copyright (C) The Apache Software Foundation. All rights reserved.
3 *
4 * This software is published under the terms of the Apache Software License
5 * version 1.1, a copy of which has been included with this distribution in
6 * the LICENSE file.
7 */
8 package org.apache.mailet;
9
10 import javax.mail.MessagingException;
11 import javax.mail.internet.MimeMessage;
12 import java.util.Collection;
13 import java.util.Iterator;
14
15 /***
16 * Defines a set of methods that a mailet or matcher uses to communicate
17 * with its mailet container, for example, to send a new message, to
18 * deliver a message locally, or write to a log file.
19 *
20 * The MailetContext object is contained within the MailetConfig and
21 * MatcherConfig objects, which the mailet container provides the
22 * mailets and matchers when they are initialized.
23 *
24 * @version 1.0.0, 24/04/1999
25 * @author Federico Barbieri <scoobie@pop.systemy.it>
26 * @author Stefano Mazzocchi <stefano@apache.org>
27 * @author Pierpaolo Fumagalli <pier@apache.org>
28 * @author Serge Knystautas <sergek@lokitech.com>
29 */
30 public interface MailetContext {
31
32 /***
33 * Bounces the message using a standard format with the given message.
34 * Will be sent back to the sender from the postmaster as specified for
35 * this mailet context, adding message to top of mail server queue using
36 * sendMail().
37 *
38 * @param mail - the message that is to be bounced and sender to whom to return the message
39 * @param message - a descriptive message as to why the message bounced
40 */
41 void bounce(Mail mail, String message) throws MessagingException;
42
43 /***
44 * Bounces the email message using the provided email address as the
45 * sender of the bounce.
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 * @param bouncer - the address to give as the sender of the bounced message
50 */
51 void bounce(Mail mail, String message, MailAddress bouncer) throws MessagingException;
52
53 /***
54 * Returns a Collection of Strings of hostnames or ip addresses that
55 * are specified as mail server listeners for the given hostname.
56 * This is done using MX records, and the hostnames or ip addresses
57 * are returned sorted by MX priority.
58 *
59 * @param host - the domain name for which to find mail servers
60 * @return a Collection of Strings of hostnames, sorted by priority
61 */
62 Collection getMailServers(String host);
63
64 /***
65 * Returns the postmaster's address for this mailet context.
66 *
67 * @return a MailAddress of the Postmaster's address
68 */
69 MailAddress getPostmaster();
70
71 /***
72 * Returns the mailet container attribute with the given name, or null
73 * if there is no attribute by that name. An attribute allows a mailet container
74 * to give the mailet additional information not already provided by this interface.
75 * See * your server documentation for information about its attributes. A list of
76 * supported attributes can be retrieved using getAttributeNames.
77 * <p>
78 * The attribute is returned as a java.lang.Object or some subclass. Attribute
79 * names should follow the same convention as package names. The Java Mailet API
80 * specification reserves names matching java.*, javax.*, and sun.*
81 *
82 * @param name - a String specifying the name of the attribute
83 * @return an Object containing the value of the attribute, or null if no attribute
84 * exists matching the given name
85 */
86 Object getAttribute(String name);
87
88 /***
89 * Returns an Iterator containing the attribute names available within
90 * this mailet context. Use the getAttribute(java.lang.String) method with an
91 * attribute name to get the value of an attribute.
92 *
93 * @return an Iterator of attribute names
94 */
95 Iterator getAttributeNames();
96
97 /***
98 * Returns the minor version of the Mailet API that this mailet
99 * container supports. All implementations that comply with Version 1.2 must have
100 * this method return the integer 1.
101 *
102 * @return 1
103 */
104 int getMajorVersion();
105
106 /***
107 * Returns the minor 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 2.
110 *
111 * @return 2
112 */
113 int getMinorVersion();
114
115 /***
116 * Returns the name and version of the mailet container on which
117 * the mailet is running.
118 * <p>
119 * The form of the returned string is servername/versionnumber. For example,
120 * JAMES may return the string JAMES/1.2.
121 * <p>
122 * The mailet container may return other optional information after the primary
123 * string in parentheses, for example, JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86).
124 *
125 * @return a String containing at least the mailet container name and version number
126 */
127 String getServerInfo();
128
129 /***
130 * Checks if a server is serviced by mail context
131 *
132 * @param serverName - name of server.
133 * @return true if server is local, i.e. serviced by this mail context
134 */
135 boolean isLocalServer(String serverName);
136
137 /***
138 * Checks if a user account is exists in the mail context.
139 *
140 * @param userAccount - user identifier.
141 * @return true if the acount is a local account
142 */
143 boolean isLocalUser(String userAccount);
144
145 /***
146 * Writes the specified message to a mailet log file, usually an event
147 * log. The name and type of the mailet log file is specific to the mailet
148 * container.
149 *
150 * @param msg - a String specifying the message to be written to the log file
151 */
152 void log(String message);
153
154 /***
155 * Writes an explanatory message and a stack trace for a given Throwable
156 * exception to the mailet log file.
157 *
158 * @param message - a String that describes the error or exception
159 * @param throwable - the Throwable error or exception
160 */
161 void log(String message, Throwable t);
162
163 /***
164 * Removes the attribute with the given name from the mailet context. After
165 * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
166 * the attribute's value will return null.
167 *
168 * @param name - a String specifying the name of the attribute to be removed
169 */
170 void removeAttribute(String name);
171
172 /***
173 * Send an outgoing message to the top of this mailet container's root queue.
174 * This is the equivalent of opening an SMTP session to localhost.
175 * This uses sender and recipients as specified in the message itself.
176 *
177 * @param msg - the MimeMessage of the headers and body content of the outgoing message
178 * @throws MessagingException - if the message fails to parse
179 */
180 void sendMail(MimeMessage msg)
181 throws MessagingException;
182
183 /***
184 * Send an outgoing message to the top of this mailet container's root queue.
185 * Is the equivalent of opening an SMTP session to localhost.
186 *
187 * @param sender - the sender of the message
188 * @param recipients - a Collection of MailAddress objects of recipients
189 * @param msg - the MimeMessage of the headers and body content of the outgoing message
190 * @throws MessagingException - if the message fails to parse
191 */
192 void sendMail(MailAddress sender, Collection recipients, MimeMessage msg)
193 throws MessagingException;
194
195 /***
196 * Send an outgoing message to the top of this mailet container queue for the
197 * appropriate processor that is specified.
198 *
199 * @param sender - the sender of the message
200 * @param recipients - a Collection of MailAddress objects of recipients
201 * @param msg - the MimeMessage of the headers and body content of the outgoing message
202 * @param state - the state of the message, indicates which processor to use
203 * @throws MessagingException - if the message fails to parse
204 */
205 void sendMail(MailAddress sender, Collection recipients, MimeMessage msg, String state)
206 throws MessagingException;
207
208 /***
209 * Binds an object to a given attribute name in this mailet context. If the name
210 * specified is already used for an attribute, this method will remove the old
211 * attribute and bind the name to the new attribute.
212 * <p>
213 * Attribute names should follow the same convention as package names. The Java
214 * Mailet API specification reserves names matching java.*, javax.*, and sun.*.
215 *
216 * @param name - a String specifying the name of the attribute
217 * @param object - an Object representing the attribute to be bound
218 */
219 void setAttribute(String name, Object object);
220
221 /***
222 * Stores mail into local accounts (POP3 by default)
223 *
224 * @param sender - the sender of the incoming message
225 * @param recipient - the user who is receiving this message (as a complete email address)
226 * @param msg - the MimeMessage to store in a local mailbox
227 * @throws MessagingException - if the message fails to parse
228 */
229 void storeMail(MailAddress sender, MailAddress recipient, MimeMessage msg)
230 throws MessagingException;
231 }
This page was automatically generated by Maven