How do I deploy my custom mailets?

This information applies to James v2.2 and later -- instructions for older versions are at the bottom of the page.

You can place:

• classes in <instdir>/apps/james/SAR-INF/classes

• jar files in <instdir>/apps/james/SAR-INF/lib/

You can place classes upon which your classes depend here also.

You then have to configure James to look in those packages for your mailets:

• You can reference mailet classes by using a fully qualified mailet or matcher class name in a Mailet configuration.
• Alternatively you can tell James to search your package for classes mentioned with unqualified names.

For this example, ours are in tld.domain.james.transport.mailets (do not use this name in a real package).

{{{ <mailetpackages>

• <mailetpackage>org.apache.james.transport.mailets</mailetpackage> <mailetpackage>tld.domain.james.transport.mailets</mailetpackage>

• </mailetpackages>

  <matcherpackages>

  • <matcherpackage>org.apache.james.transport.matchers</matcherpackage> <matcherpackage>tld.domain.james.transport.matchers</matcherpackage>

  </matcherpackages> }}}

Mailet Developers Please Note

The classloaders created inherit the same loader used by the spoolmanager, and hence have access to all the same classes in the same loader as James does. This allows mailets to access the underlying Avalon services via the mailet context. This breaks the intended design for the v3 mailet context, which should be unable to be used to get details of the context implementation.

However, this classloader seperation is not applicable to v2, so the changes conform to James & Mailet v2. But we would STRONGLY URGE mailet developers not to access the underlying Avalon services directly where at all possible (or make this code easily maintainable) because this access WILL be restricted in future versions for security reasons.

It is our stated intention that we will improve mailet deployment by supporting "mailet applications" which will run in an isolated classloader space, thereby preventing access from those mailets to James and other mailet applications running in the same James instance. Therefore in James v3 and Mailet v3 the only services available will be accessed via mechanisms explicitly provided by the mailet context.

Instructions for older versions

Community member IanH contributes the following:

If you are on 2.1.x, you need to

1. unjar the James.sar file
2. unjar the james.jar (or .bar for 2.0.x) file
3. add your mailet class in the james.jar (or .bar for 2.0.x) file
4. rejar james.jar or .bar
5. rejar james.sar

Here's the ant xml snippet which requires James 2.1.x (doesn't work for James 2.0.x) and Ant version that supports <jar ... update='true' />

{{{ <!--

• | src.sar.file = The james.sar (WATCH IT: SAR FILE not JAR FILE) | from James 2.1.x | | update.sar.file = The orignal james.sar + your custom mailets .

• -->

• <property name="src.sar.file" value="./james.sar" /> <property name="updated.sar.file" location="./customSAR/james.sar" />

  <!--

  • | This is where ant will do its work |

  • -->

  <property name='sar.work.dir' location='./sarWorkDir'/>

  <!--

  • | This is where your custom mailet classes should reside | They will be merged into james.jar

  • -->

  <property name='compiled.dir' location='./myCompiledMailet' />

  <!-- here's where all the work is being done -->

  <target name="assemble" description="Assembling SAR + Adding Custom Mailet">

  • <echo>removing and re-creating work directory [${sar.work.dir}]</echo> <delete dir="${sar.work.dir}" verbose="no" /> <mkdir dir="${sar.work.dir}/" />

    <delete dir="./customSAR" verbose="no" /> <mkdir dir="./customSAR" />

    <!-- Unjar'ing the SAR file to get at the James.jar file -->

    <echo>Unjaring sar file [${src.sar.file}] to work directory [${sar.work.dir}]</echo> <unjar src="${src.sar.file}" dest="${sar.work.dir}" />

    <echo>Updating [${sar.work.dir}/SARINF/lib/james.jar] by adding our custom mailet classes from [${compiled.dir}] </echo> <jar jarfile="${sar.work.dir}/SARINF/lib/james.jar" basedir="${compiled.dir}" update="true" />

    <echo>Re-adding [${sar.work.dir}/SARINF/lib/james.jar] into [${updated.sar.file}]</echo>

    <copy file="${src.sar.file}" todir="${dist}" />

    <jar jarfile="${updated.sar.file}" basedir="${sar.work.dir}" update="true" />

  </target> }}}