001: /****************************************************************
002: * Licensed to the Apache Software Foundation (ASF) under one *
003: * or more contributor license agreements. See the NOTICE file *
004: * distributed with this work for additional information *
005: * regarding copyright ownership. The ASF licenses this file *
006: * to you under the Apache License, Version 2.0 (the *
007: * "License"); you may not use this file except in compliance *
008: * with the License. You may obtain a copy of the License at *
009: * *
010: * http://www.apache.org/licenses/LICENSE-2.0 *
011: * *
012: * Unless required by applicable law or agreed to in writing, *
013: * software distributed under the License is distributed on an *
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
015: * KIND, either express or implied. See the License for the *
016: * specific language governing permissions and limitations *
017: * under the License. *
018: ****************************************************************/package org.apache.mailet;
019:
020: import java.util.Collection;
021: import java.util.Iterator;
022:
023: import javax.mail.MessagingException;
024: import javax.mail.internet.MimeMessage;
025:
026: /**
027: * Defines a set of methods that a mailet or matcher uses to communicate
028: * with its mailet container, for example, to send a new message, to
029: * deliver a message locally, or write to a log file.
030: *
031: * The MailetContext object is contained within the MailetConfig and
032: * MatcherConfig objects, which the mailet container provides to the
033: * mailets and matchers when they are initialized.
034: *
035: * @version 1.0.0, 24/04/1999
036: */
037: public interface MailetContext {
038:
039: /**
040: * Bounces the message using a standard format with the given message.
041: * The message will be sent back to the sender from the postmaster as specified for
042: * this mailet context, adding message to top of mail server queue using
043: * sendMail().
044: *
045: * @param mail - the message that is to be bounced and sender to whom to return the message
046: * @param message - a descriptive message as to why the message bounced
047: */
048: void bounce(Mail mail, String message) throws MessagingException;
049:
050: /**
051: * Bounces the email message using the provided email address as the
052: * sender of the bounce.
053: *
054: * @param mail - the message that is to be bounced and sender to whom to return the message
055: * @param message - a descriptive message as to why the message bounced
056: * @param bouncer - the address to give as the sender of the bounced message
057: */
058: void bounce(Mail mail, String message, MailAddress bouncer)
059: throws MessagingException;
060:
061: /**
062: * Returns a Collection of Strings of hostnames or ip addresses that
063: * are specified as mail server listeners for the given hostname.
064: * This is done using MX records, and the hostnames or ip addresses
065: * are returned sorted by MX priority.
066: *
067: * @param host - the domain name for which to find mail servers
068: * @return a Collection of Strings of hostnames, sorted by priority
069: */
070: Collection getMailServers(String host);
071:
072: /**
073: * Returns the postmaster's address for this mailet context.
074: *
075: * @return a MailAddress of the Postmaster's address
076: */
077: MailAddress getPostmaster();
078:
079: /**
080: * Returns the mailet container attribute with the given name, or null
081: * if there is no attribute by that name. An attribute allows a mailet container
082: * to give the mailet additional information not already provided by this interface.
083: * See your server documentation for information about its attributes. A list of
084: * supported attributes can be retrieved using getAttributeNames.
085: * <p>
086: * The attribute is returned as a java.lang.Object or some subclass. Attribute
087: * names should follow the same convention as package names. The Java Mailet API
088: * specification reserves names matching java.*, javax.*, and sun.*
089: *
090: * @param name - a String specifying the name of the attribute
091: * @return an Object containing the value of the attribute, or null if no attribute
092: * exists matching the given name
093: */
094: Object getAttribute(String name);
095:
096: /**
097: * Returns an Iterator containing the attribute names available within
098: * this mailet context. Use the getAttribute(java.lang.String) method with an
099: * attribute name to get the value of an attribute.
100: *
101: * @return an Iterator of attribute names
102: */
103: Iterator getAttributeNames();
104:
105: /**
106: * Returns the major version of the Mailet API that this mailet
107: * container supports. All implementations that comply with Version 1.2 must have
108: * this method return the integer 1.
109: *
110: * @return 1
111: */
112: int getMajorVersion();
113:
114: /**
115: * Returns the minor version of the Mailet API that this mailet
116: * container supports. All implementations that comply with Version 1.2 must have
117: * this method return the integer 2.
118: *
119: * @return 2
120: */
121: int getMinorVersion();
122:
123: /**
124: * Returns the name and version of the mailet container on which
125: * the mailet is running.
126: * <p>
127: * The form of the returned string is servername/versionnumber. For example,
128: * JAMES may return the string JAMES/1.2.
129: * <p>
130: * The mailet container may return other optional information after the primary
131: * string in parentheses, for example, JAMES/1.2 (JDK 1.3.0; Windows NT 4.0 x86).
132: *
133: * @return a String containing at least the mailet container name and version number
134: */
135: String getServerInfo();
136:
137: /**
138: * Checks if a server is serviced by mail context
139: *
140: * @param serverName - name of server.
141: * @return true if server is local, i.e. serviced by this mail context
142: */
143: boolean isLocalServer(String serverName);
144:
145: /**
146: * Checks if a user account is exists in the mail context.
147: *
148: * @param userAccount - user identifier.
149: * @return true if the acount is a local account
150: */
151: boolean isLocalUser(String userAccount);
152:
153: /**
154: * Writes the specified message to a mailet log file, usually an event
155: * log. The name and type of the mailet log file is specific to the mailet
156: * container.
157: *
158: * @param message - a String specifying the message to be written to the log file
159: */
160: void log(String message);
161:
162: /**
163: * Writes an explanatory message and a stack trace for a given Throwable
164: * exception to the mailet log file.
165: *
166: * @param message - a String that describes the error or exception
167: * @param throwable - the Throwable error or exception
168: */
169: void log(String message, Throwable t);
170:
171: /**
172: * Removes the attribute with the given name from the mailet context. After
173: * removal, subsequent calls to getAttribute(java.lang.String) to retrieve
174: * the attribute's value will return null.
175: *
176: * @param name - a String specifying the name of the attribute to be removed
177: */
178: void removeAttribute(String name);
179:
180: /**
181: * Send an outgoing message to the top of this mailet container's root queue.
182: * This is the equivalent of opening an SMTP session to localhost.
183: * This uses sender and recipients as specified in the message itself.
184: *
185: * @param msg - the MimeMessage of the headers and body content of the outgoing message
186: * @throws MessagingException - if the message fails to parse
187: */
188: void sendMail(MimeMessage msg) 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,
200: MimeMessage msg) 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,
214: MimeMessage msg, String state) 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) throws MessagingException;
225:
226: /**
227: * Binds an object to a given attribute name in this mailet context. If the name
228: * specified is already used for an attribute, this method will remove the old
229: * attribute and bind the name to the new attribute.
230: * <p>
231: * Attribute names should follow the same convention as package names. The Java
232: * Mailet API specification reserves names matching java.*, javax.*, and sun.*.
233: *
234: * @param name - a String specifying the name of the attribute
235: * @param object - an Object representing the attribute to be bound
236: */
237: void setAttribute(String name, Object object);
238:
239: /**
240: * Stores the message is in the local repository associated with
241: * recipient for later retrieval, e.g., by a POP3 or IMAP service.
242: *
243: * @deprecated - use sparingly. Service will be replaced with
244: * resource acquired via JNDI.
245: * @param sender - the sender of the incoming message
246: * @param recipient - the user who is receiving this message (as a complete email address)
247: * @param msg - the MimeMessage to store in a local mailbox
248: * @throws MessagingException - if the message fails to parse
249: */
250: void storeMail(MailAddress sender, MailAddress recipient,
251: MimeMessage msg) throws MessagingException;
252:
253: /**
254: * Returns an Iterator over HostAddress, a specialized subclass of
255: * javax.mail.URLName, which provides location information for
256: * servers that are specified as mail handlers for the given
257: * hostname. This is done using MX records, and the HostAddress
258: * instances are returned sorted by MX priority. If no host is
259: * found for domainName, the Iterator returned will be empty and the
260: * first call to hasNext() will return false.
261: *
262: * @since Mailet API v2.2.0a16-unstable
263: * @param domainName - the domain for which to find mail servers
264: * @return an Iterator over HostAddress instances, sorted by priority
265: */
266: Iterator getSMTPHostAddresses(String domainName);
267: }
|