You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by er...@apache.org on 2012/07/18 14:41:30 UTC
svn commit: r1362915 -
/james/server/trunk/src/site/xdoc/dev-extend-mailet.xml
Author: eric
Date: Wed Jul 18 12:41:29 2012
New Revision: 1362915
URL: http://svn.apache.org/viewvc?rev=1362915&view=rev
Log:
Update the mailet developement documentation (package name, format, log level...) (JAMES-1424)
Modified:
james/server/trunk/src/site/xdoc/dev-extend-mailet.xml
Modified: james/server/trunk/src/site/xdoc/dev-extend-mailet.xml
URL: http://svn.apache.org/viewvc/james/server/trunk/src/site/xdoc/dev-extend-mailet.xml?rev=1362915&r1=1362914&r2=1362915&view=diff
==============================================================================
--- james/server/trunk/src/site/xdoc/dev-extend-mailet.xml (original)
+++ james/server/trunk/src/site/xdoc/dev-extend-mailet.xml Wed Jul 18 12:41:29 2012
@@ -27,39 +27,61 @@
<section name="Writing a Custom Mailet">
-<p>Implementing a custom mailet is generally a simple task, most of whose complexity
-lies in coding the actual work to be done by the mailet. This is largely due to the
-simplicity of the Mailet interface and the fact that a GenericMailet class is provided
-as part of the Mailet package.</p>
-<p>In this discussion we will assume that any mailet being implemented is a subclass of
-GenericMailet. The GenericMailet class serves to abstract away of the configuration and
-logging details. While it provides a noop implementation of the init() and destroy() methods,
-these can be easily overridden to provide useful functionality.</p>
-<p>In general, the only four methods that you should need to implement are init(), destroy(),
-getMailetInfo(), and service(Mail). And only the last is required in all cases.</p>
-
-<subsection name="Configuration">
-<p>As described in the <a href="config-mailetcontainer.html">SpoolManager configuration
-section</a>, mailets are configured with a set of String (name, value) pairs. These values are
-passed into the Mailet upon initialization (although the details of this process are hidden by
-the GenericMailet implementation). GenericMailet provides access to this configuration
-information through use of the getInitParameter(String) method. Passing in the name of the
-requested configuration value will yield the value if set, and null otherwise. Configuration
-values are available inside the init(), destroy(), and service(Mail) methods.</p>
-</subsection>
+ <p>
+ Implementing a custom mailet is generally a simple task, most of whose complexity
+ lies in coding the actual work to be done by the mailet. This is largely due to the
+ simplicity of the Mailet interface and the fact that a GenericMailet class is provided
+ as part of the Mailet package.
+ </p>
+
+ <p>
+ In this discussion we will assume that any mailet being implemented is a subclass of
+ GenericMailet. The GenericMailet class serves to abstract away of the configuration and
+ logging details. While it provides a noop implementation of the init() and destroy() methods,
+ these can be easily overridden to provide useful functionality.
+ </p>
+
+ <p>
+ In general, the only four methods that you should need to implement are init(), destroy(),
+ getMailetInfo(), and service(Mail). And only the last is required in all cases.
+ </p>
+
+ <subsection name="Configuration">
+ <p>
+ As described in the <a href="config-mailetcontainer.html">SpoolManager configuration
+ section</a>, mailets are configured with a set of String (name, value) pairs. These values are
+ passed into the Mailet upon initialization (although the details of this process are hidden by
+ the GenericMailet implementation). GenericMailet provides access to this configuration
+ information through use of the getInitParameter(String) method. Passing in the name of the
+ requested configuration value will yield the value if set, and null otherwise. Configuration
+ values are available inside the init(), destroy(), and service(Mail) methods.
+ </p>
+ </subsection>
+
+ <subsection name="Logging">
+
+ <p>
+ There is a simple logging mechanism provided by the Mailet API. It does not support
+ logging levels, so any log filtering will have to be implemented in the Mailet code.
+ Logging is done by calling one of the two logging methods on GenericMailet - log(String)
+ or log(String,Throwable). Logging is available inside the init(), destroy(), and service(Mail)
+ methods.
+ </p>
+ <p>
+ Please note that the log() method logs with DEBUG level. You will need to define that DEBUG level
+ in the log4j.properties.
+ </p>
+ <p>
+ The value of getMailetInfo() for the Mailet is prepended to the log entries for that
+ Mailet. So it may be desirable for you to override this method so you can distinguish mailet
+ log entries by Mailet.
+ </p>
+ <p>
+ Alternatively, you can instanciate your own logger and log with different level, as show in the
+ following snippet (don't forget to update the log4j.properties so you log are taken into account).
+ </p>
-<subsection name="Logging">
-<p>There is a simple logging mechanism provided by the Mailet API. It does not support
-logging levels, so any log filtering will have to be implemented in the Mailet code.
-Logging is done by calling one of the two logging methods on GenericMailet - log(String)
-or log(String,Throwable). Logging is available inside the init(), destroy(), and service(Mail)
-methods.</p>
-<p>The value of getMailetInfo() for the Mailet is prepended to the log entries for that
-Mailet. So it may be desirable for you to override this method so you can distinguish mailet
-log entries by Mailet.</p>
-<p>Alternatively, you can instanciate your own logger and log with different level, as show in the
-following snippet (don't forget to update the log4j.properties so you log are taken into account).</p>
-<code>
+<source>
package com.test;
import javax.mail.MessagingException;
@@ -78,94 +100,93 @@ public class MyMailet extends GenericMai
logger.debug("Log via slf4j with DEBUG level !!! Add log4j.logger.com.test=DEBUG, CONS, FILE in the log4j.properties");
}
}
-</code>
+</source>
</subsection>
<subsection name="Initialization">
-<p>As part of the Mailet lifecycle, a Mailet is guaranteed to be initialized immediately after
-being instantiated. This happens once and only once for each Mailet instance. The
-Initialization phase is where configuration parsing and per-Mailet resource creation generally
-take place. Depending on your Mailet, it may or may not be necessary to do any initialization
-of the mailet. Initialization logic is implemented by overriding the init() method of
-GenericMailet.</p>
+ <p>
+ As part of the Mailet lifecycle, a Mailet is guaranteed to be initialized immediately after
+ being instantiated. This happens once and only once for each Mailet instance. The
+ Initialization phase is where configuration parsing and per-Mailet resource creation generally
+ take place. Depending on your Mailet, it may or may not be necessary to do any initialization
+ of the mailet. Initialization logic is implemented by overriding the init() method of
+ GenericMailet.
+ </p>
</subsection>
<subsection name="Servicing">
-<p>The bulk of the Mailet logic is expected to be invoked from the service(Mail) method. This
-method is invoked each time a mail message is to be processed by the mailet. The message is
-passed in as an instance of the Mail interface, which is part of the Mailet API.</p>
-<p>The Mail interface is essentially a light wrapper around JavaMail's MimeMessage class with a
-few important differences. See the Javadoc for the interface for a description of the additional
-methods available on this wrapper.</p>
+ <p>
+ The bulk of the Mailet logic is expected to be invoked from the service(Mail) method. This
+ method is invoked each time a mail message is to be processed by the mailet. The message is
+ passed in as an instance of the Mail interface, which is part of the Mailet API.</p>
+ <p>The Mail interface is essentially a light wrapper around JavaMail's MimeMessage class with a
+ few important differences. See the Javadoc for the interface for a description of the additional
+ methods available on this wrapper.
+ </p>
</subsection>
<subsection name="Destruction">
-<p>As part of the Mailet lifecycle, a Mailet is guaranteed to be destroyed when the container
-cleans up the Mailet. This happens once and only once for each Mailet instance. The
-Destruction phase is where per-Mailet resource release generally takes place. Depending
-on your Mailet, it may or may not be necessary to do any destruction
-of the mailet. Destruction logic is implemented by overriding the destroy() method of
-GenericMailet.</p>
+ <p>
+ As part of the Mailet lifecycle, a Mailet is guaranteed to be destroyed when the container
+ cleans up the Mailet. This happens once and only once for each Mailet instance. The
+ Destruction phase is where per-Mailet resource release generally takes place. Depending
+ on your Mailet, it may or may not be necessary to do any destruction
+ of the mailet. Destruction logic is implemented by overriding the destroy() method of
+ GenericMailet.
+ </p>
</subsection>
</section>
+
<section name="Deploying a Custom Mailet">
-<p>Once a Mailet has been successfully implemented there are only a couple of
-additional steps necessary to actually deploy the Mailet.</p>
-<subsection name="Adding Your Mailet to the Classpath">
-<p>
-The Mailet must be added to James' classpath so that the Mailet can be loaded by James. There
-are three ways to add a custom Mailet to the classpath so that James will be able to load the
-Mailet. These are:
-</p>
-<p>
-1a. Download the source distribution, add a jar file containing the custom files to the lib
-directory of the unpacked source distribution, and build a new .sar file by following the
-directions <a href="build-instructions.html">here</a>. This new .sar file will now
-include your custom classes.
-</p>
-<p>
-or
-</p>
-<p>
-1b. Place a jar file containing the custom class files in the lib subdirectory of the James
-installation. It will also be necessary to unpack the JavaMail and James jar files from
-the provided .sar file and add them to this directory.
-</p>
-<p>
-or
-</p>
-<p>
-1c. Place a jar file containing the custom class files in
-/path/to/james/conf/lib/ subdirectory.
-</p>
-<p>
-2. After this is done get sure you add the mailet package to the mailetcontainer.xml. For example:
-<p>
+
+ <p>
+ Once a Mailet has been successfully implemented there are only a couple of
+ additional steps necessary to actually deploy the Mailet.
+ </p>
+
+ <subsection name="Adding Your Mailet to the Classpath">
+ <p>
+ The Mailet must be added to James' classpath so that the Mailet can be loaded by James. There
+ are two ways to add a custom Mailet to the classpath so that James will be able to load the
+ Mailet. These are:
+ </p>
+ <p>
+ 1a. Download the source distribution, add a jar file containing the custom files to the lib
+ directory of the unpacked source distribution, and build a new .tar.gz/zip file by following the
+ directions <a href="build-instructions.html">here</a>. This new tar.gz/zip file will now
+ include your custom classes.
+ </p>
+ <p>
+ or
+ </p>
+ <p>
+ 1b. Place a jar file containing the custom class files in
+ /path/to/james/conf/lib/ subdirectory.
+ </p>
+ <p>
+ 2. The mailetpackages entity is no longer required, the class attribute of mailets and matchers now takes a fully qualified class name e.g.
+ <p>
<source>
-<!-- Set the Java packages from which to load mailets and matchers -->
-<mailetpackages>
- <mailetpackage>org.apache.james.transport.mailets</mailetpackage>
- <mailetpackage>org.apache.james.transport.mailets.smime</mailetpackage>
- <mailetpackage>your.costum.package.transport-mailets</mailetpackage>
-</mailetpackages>
+<mailet match="All" class="com.your.company.MyMailet"/>
</source>
-</p>
-After that restart james.
-</p>
-</subsection>
-
-<subsection name="James Configuration">
-<p>Configuration of the processor chain is discussed
-<a href="config-mailetcontainer.html">elsewhere</a> in this documentation. The
-details of configuring mailet deployment is discussed at length. Here we will only comment
-that it is important to add the appropriate mailet package for your custom mailet to the
-<mailetpackages> list and that the name of your mailet should not conflict with any of
-the mailets described <a href="dev-provided-mailets.html">here</a>.
-</p>
-</subsection>
+ </p>
+ After that, restart James server.
+ </p>
+ </subsection>
+
+ <subsection name="James Configuration">
+ <p>Configuration of the processor chain is discussed
+ <a href="config-mailetcontainer.html">elsewhere</a> in this documentation. The
+ details of configuring mailet deployment is discussed at length. Here we will only comment
+ that it is important to add the appropriate mailet package for your custom mailet to the
+ <mailetpackages> list and that the name of your mailet should not conflict with any of
+ the mailets described <a href="dev-provided-mailets.html">here</a>.
+ </p>
+ </subsection>
</section>
</body>
+
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org