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-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org