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 javax.mail.MessagingException;
021: import java.util.Iterator;
022:
023: /**
024: * GenericMailet makes writing mailets easier. It provides simple
025: * versions of the lifecycle methods init and destroy and of the methods
026: * in the MailetConfig interface. GenericMailet also implements the log
027: * method, declared in the MailetContext interface.
028: * <p>
029: * To write a generic mailet, you need only override the abstract service
030: * method.
031: *
032: * @version 1.0.0, 24/04/1999
033: */
034: public abstract class GenericMailet implements Mailet, MailetConfig {
035: private MailetConfig config = null;
036:
037: /**
038: * Called by the mailer container to indicate to a mailet that the
039: * mailet is being taken out of service.
040: */
041: public void destroy() {
042: //Do nothing
043: }
044:
045: /**
046: * Returns a String containing the value of the named initialization
047: * parameter, or null if the parameter does not exist.
048: * <p>
049: * This method is supplied for convenience. It gets the value of the
050: * named parameter from the mailet's MailetConfig object.
051: *
052: * @param name - a String specifying the name of the initialization parameter
053: * @return a String containing the value of the initalization parameter
054: */
055: public String getInitParameter(String name) {
056: return config.getInitParameter(name);
057: }
058:
059: /**
060: * Returns a String containing the value of the named initialization
061: * parameter, or defValue if the parameter does not exist.
062: * <p>
063: * This method is supplied for convenience. It gets the value of the
064: * named parameter from the mailet's MailetConfig object.
065: *
066: * @param name - a String specifying the name of the initialization parameter
067: * @param defValue - a String specifying the default value when the parameter
068: * is not present
069: * @return a String containing the value of the initalization parameter
070: */
071: public String getInitParameter(String name, String defValue) {
072: String res = config.getInitParameter(name);
073: if (res == null) {
074: return defValue;
075: } else {
076: return res;
077: }
078: }
079:
080: /**
081: * Returns the names of the mailet's initialization parameters as an
082: * Iterator of String objects, or an empty Iterator if the mailet has no
083: * initialization parameters.
084: * <p>
085: * This method is supplied for convenience. It gets the parameter names from
086: * the mailet's MailetConfig object.
087: *
088: * @return an Iterator of String objects containing the names of
089: * the mailet's initialization parameters
090: */
091: public Iterator getInitParameterNames() {
092: return config.getInitParameterNames();
093: }
094:
095: /**
096: * Returns this Mailet's MailetConfig object.
097: *
098: * @return the MailetConfig object that initialized this mailet
099: */
100: public MailetConfig getMailetConfig() {
101: return config;
102: }
103:
104: /**
105: * Returns a reference to the MailetContext in which this mailet is
106: * running.
107: *
108: * @return the MailetContext object passed to this mailet by the init method
109: */
110: public MailetContext getMailetContext() {
111: return getMailetConfig().getMailetContext();
112: }
113:
114: /**
115: * Returns information about the mailet, such as author, version, and
116: * copyright. By default, this method returns an empty string. Override
117: * this method to have it return a meaningful value.
118: *
119: * @return information about this mailet, by default an empty string
120: */
121: public String getMailetInfo() {
122: return "";
123: }
124:
125: /**
126: * Returns the name of this mailet instance.
127: *
128: * @return the name of this mailet instance
129: */
130: public String getMailetName() {
131: return config.getMailetName();
132: }
133:
134: /**
135: * <p>Called by the mailet container to indicate to a mailet that the
136: * mailet is being placed into service.</p>
137: *
138: * <p>This implementation stores the MailetConfig object it receives from
139: * the mailet container for later use. When overriding this form of the
140: * method, call super.init(config).</p>
141: *
142: * @param MailetConfig newconfig - the MailetConfig object that contains
143: * configutation information for this mailet
144: * @throws MessagingException
145: * if an exception occurs that interrupts the mailet's normal operation
146: */
147: public void init(MailetConfig newConfig) throws MessagingException {
148: config = newConfig;
149: init();
150: }
151:
152: /**
153: * <p>A convenience method which can be overridden so that there's no
154: * need to call super.init(config).</p>
155: *
156: * Instead of overriding init(MailetConfig), simply override this
157: * method and it will be called by GenericMailet.init(MailetConfig config).
158: * The MailetConfig object can still be retrieved via getMailetConfig().
159: *
160: * @throws MessagingException
161: * if an exception occurs that interrupts the mailet's normal operation
162: */
163: public void init() throws MessagingException {
164: //Do nothing... can be overriden
165: }
166:
167: /**
168: * Writes the specified message to a mailet log file, prepended by
169: * the mailet's name.
170: *
171: * @param message - a String specifying the message to be written to the log file
172: */
173: public void log(String message) {
174: StringBuffer logBuffer = new StringBuffer(256).append(
175: getMailetName()).append(": ").append(message);
176: getMailetContext().log(logBuffer.toString());
177: }
178:
179: /**
180: * Writes an explanatory message and a stack trace for a given Throwable
181: * exception to the mailet log file, prepended by the mailet's name.
182: *
183: * @param message - a String that describes the error or exception
184: * @param t - the java.lang.Throwable to be logged
185: */
186: public void log(String message, Throwable t) {
187: StringBuffer logBuffer = new StringBuffer(256).append(
188: config.getMailetName()).append(": ").append(message);
189: getMailetContext().log(logBuffer.toString(), t);
190: }
191:
192: /**
193: * <p>Called by the mailet container to allow the mailet to process a
194: * message.</p>
195: *
196: * <p>This method is declared abstract so subclasses must override it.</p>
197: *
198: * @param mail - the Mail object that contains the MimeMessage and
199: * routing information
200: * @throws javax.mail.MessagingException - if an exception occurs that interferes with the mailet's normal operation
201: */
202: public abstract void service(Mail mail)
203: throws javax.mail.MessagingException;
204: }
|