Sample Tracking Log Service for Pierre Scherer

[Steve Short <ss...@postx.com>]

Here's are the notes and steps required to create a simple demo tracking
service.

Attached diff file (from top level James directory) was created against
a CVS checkout of tag
'build_2_1_fcs' this morning.  I have implemented this service in the
James source tree and 
using James package names etc, this is because it was much easier and
quicker for me to do it 
this way - you may want to create your own packages etc.  Despite this I
do not think this
feature is suitable for inclusion in James as is.

Some notes and issues:

	- I just added a call to the tracking service from within the
RemoteDelivery mailet, 
	  but I have not taken into account the possility of partial
deliveries, i.e. I have
	  not added appropriate handling for
javax.mail.SendFailedException.
	  
	- Although the tracking service supports multiple detail levels,
the log level for 
	  'tracking' must be set to INFO or greater for any logging to
occur.

	- the only difference between minimum and maximum tracking
levels is that the latter
              includes the message subject.
	  
	- tracking messages and other log messages and errors from the
tracking service are
	  all contained in one file, tracking.log.

	- having used the service interface approach - it would now be
easy to create
	  a service implementation class that logged to a database with
no code changes
              required anywhere else - just change the config files.  In
which case the maximum
              tracking level could store the actual message itself as a
blob in the database.

And now the steps (note lots of lines missed out for brevity).

1.  Create a new service interface for tracking, Tracking.java

	package org.apache.james.services;
	...
	public interface Tracking {
	    /**
	     * The component role used by components implementing this
service
	     */
	    String ROLE = "org.apache.james.services.Tracking";

	    public static final int TRACKING_OFF        = 0;
	    public static final int TRACKING_MINIMUM    = 1;
	    public static final int TRACKING_MAXIMUM    = 2;

	    public void trackMessage(Collection recipients, Mail mail);
	}

2.  Create a tracking class that implements the tracking service
interface, LogTracker.java.

	package org.apache.james.tracking;
	...
	public class LogTracker
	    extends AbstractLogEnabled
	    implements Configurable, Initializable,
	    org.apache.james.services.Tracking {
	
	    private int trackingLevel = TRACKING_OFF;
	    
	    public void configure( final Configuration configuration ) {
... }

	    public void initialize() { ... }

	    public int getTrackingLevel() { ... }

	    public void trackMessage(Collection recipients, Mail mail) {
... }
	}
	
3.  Create a block info file for the tracking service, LogTracker.xinfo,
in same source directory
    as LogTracker.java.

	<?xml version="1.0"?>
	
	<blockinfo>
	
	  <!-- section to describe block -->
	  <block>
	    <version>1.0</version>
	  </block>
	
	  <!-- services that are offered by this block -->
	  <services>
	    <service name="org.apache.james.services.Tracking"
version="1.0"/>
	  </services>
	
	</blockinfo>
	
4.  Update James block info, james.xinfo,  file to declare new
dependency on Tracking service:
	
	...
	<dependency>
	    <service name="org.apache.james.services.Tracking"
version="1.0"/>
	</dependency>
	...
5.  Update James assembly config file to define a LogTracker instance to

   satisfy James dependency on a Tracking service:
   
	<assembly>
	...
	  <!-- The James block  -->
	  <block name="James" class="org.apache.james.James" >
	  	...
	    <provide name="tracking"
role="org.apache.james.services.Tracking"/>
	  </block>
	...
	</assembly>

6.  Update James config file to configure tracking service:

	...
	<!-- Tracking Service Block -->
	<tracking>
	    <trackingLevel>1</trackingLevel>
	</tracking>
	...

7.  Update James server config file to configure a logger:

	...
	<categories>
	...
    	    <category name="tracking" log-level="INFO">
		<log-target id-ref="tracking-target"/>
	    </category>
	</categories>
	...
	<targets>
	    ...
	    <file id="tracking-target">
                <filename>${app.home}/logs/tracking.log</filename>
                <format>%{time:dd/MM/yy HH:mm:ss} %5.5{priority}
%{category}: %{message}\n%{throwable}</format>
                <append>true</append>
            </file>
      </targets>
...

8.  Write your mailet to invoke the tracking service.  For testing
purposes I just threw it into RemoteDelivery:

    Look up the service in the init() method:
    
        try {
            // Instantiate the a tracking service
            tracking = (Tracking)
compMgr.lookup("org.apache.james.services.Tracking");
        } catch (ComponentException cnfe) {
            log("Failed to retrieve Tracking component:" +
cnfe.getMessage());
        } catch (Exception e) {
            log("Failed to retrieve Tracking component:" +
e.getMessage());
        }

    And call the tracking service at the appropriate point (right after
transport.sendMessage()
    in my case:
    
	// Update tracking service
	tracking.trackMessage(recipients, mail);

9.  Build James and test.

I did and it worked - amazing after all that!

Cheers
Steve


 <<tracking.diff>>