SK.gnome.dwarf.mail.smtp.proc
Class MailAgent

java.lang.Object
  extended bySK.gnome.dwarf.GenericService
      extended bySK.gnome.dwarf.GenericServer
          extended bySK.gnome.dwarf.thread.ThreadServer
              extended bySK.gnome.dwarf.mail.smtp.proc.MailAgent
All Implemented Interfaces:
SK.gnome.dwarf.Reportable, java.lang.Runnable, SK.gnome.dwarf.Server, SK.gnome.dwarf.Service
Direct Known Subclasses:
AutoReply, ConsoleCommand, Debug, ListServer, MailAgentServer, MessageCheck

public abstract class MailAgent
extends SK.gnome.dwarf.thread.ThreadServer

Provides mail agent service.

Mail agent is a special service which processes queued messages. It depends on mail filters, i.e. instances of the MailFilter class. The filters decide which agents will be the message passed to and for which recipients.

Each MailAgent must implement one or both of the Preprocessing and/or Postprocessing interfaces, as well as one or both of the preprocess(MailAgentMessage, Collection) and/or postprocess(MailAgentMessage, Collection) public methods. These methods throw an UnsupportedOperationException by default.

A MailAgentMessage processed by the agents is either a newly arrived message, or a fully or partially delivered message. New messages are passed only to agents which implement the Preprocessing interface (with the corresponding preprocessing method). Delivered messages are passed only to those agents, which implement the Postprocessing interface (with the corresponding postprocessing method).

A MailAgent instance may contain one or more MailFilter objects. These filters decide which recipients the agent will receive in the input collection. Filters work in a chain, in order they were added to the agent. An agent will never receive an empty input collection of recipients, therefore if all recipients are filtered out, the agent won't be invoked at all for that message.

A single queued message may be passed more than one time to the mail agents as it is successively delivered to its recipients. Each time such message is processed, the input collection contains only those recipients, for which the actual delivery process has succeeded (or failed).

Derived classes may override the init(MailAgentContext) and destroy() methods to easily initialize and destroy the mail agents, but they may not forget to call the inherited original methods in the overriden method body.


Field Summary
protected  MailAgentContext context
          The mail agent context associated with this agent.
protected  boolean required
          Whether the agent is reuired.
 
Fields inherited from class SK.gnome.dwarf.thread.ThreadServer
daemon, thread
 
Fields inherited from class SK.gnome.dwarf.GenericService
initParameters, parent
 
Fields inherited from interface SK.gnome.dwarf.Service
INITIALIZED, LOG_DEBUG, LOG_ERROR, LOG_FATAL, LOG_INFO, LOG_TRACE, LOG_WARN, LOG_XFER, SHUTDOWN, STARTED, STOPPED
 
Constructor Summary
MailAgent(java.lang.String name)
          Creates a new MailAgent.
 
Method Summary
protected  void destroy()
          Destroys the mail agent.
protected  java.util.Collection filter(MailAgentMessage message, java.util.Collection recipients)
          Filters the given message.
protected  void init(MailAgentContext context)
          Initializes the mail agent.
 void init(SK.gnome.dwarf.Server parent)
          Initializes the service.
 boolean isRequired()
          Whether the agent is reuired.
protected  void postprocess(MailAgentMessage message, java.util.Collection recipients)
          Processes the message.
protected  void preprocess(MailAgentMessage message, java.util.Collection recipients)
          Processes the message.
 void setRequired(boolean enable)
          Sets whether the agent is required.
protected  void storeMessage(java.lang.String user, java.lang.String folder, MailAgentMessage message)
          Stores the given message to the local mail store.
 
Methods inherited from class SK.gnome.dwarf.thread.ThreadServer
enableThread, finish, loop, run, setDaemon, shutdown, start, stop
 
Methods inherited from class SK.gnome.dwarf.GenericServer
addService, addService, getAuthenticator, getLogger, getParameters, getService, getServices, getServices, removeService, report
 
Methods inherited from class SK.gnome.dwarf.GenericService
getAuthFacility, getFullName, getInitParameter, getInitParameterNames, getLogFacility, getName, getPrincipal, getShutdownTimeout, getState, log, log, login, logout, setAuthFacility, setInitParameters, setLogFacility, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface SK.gnome.dwarf.Service
getFullName, getName, getState, log, log, login, logout
 

Field Detail

required

protected boolean required
Whether the agent is reuired.

If the agent is required and an exception is thrown during the mail processing, no other agents in the chain will receive the message on the input as it is immediatelly returned back to the mail queue.


context

protected MailAgentContext context
The mail agent context associated with this agent.

Constructor Detail

MailAgent

public MailAgent(java.lang.String name)
Creates a new MailAgent.

Parameters:
name - the agent name
Method Detail

isRequired

public boolean isRequired()
Whether the agent is reuired.

If the agent is required and an exception is thrown during the mail processing, no other agents in the chain will receive the message on the input as it is immediatelly returned back to the mail queue.

Returns:
true if the agent is required, false otherwise

setRequired

public void setRequired(boolean enable)
Sets whether the agent is required.

If the agent is required and an exception is thrown during the mail processing, no other agents in the chain will receive the message on the input as it is immediatelly returned back to the mail queue.

Parameters:
enable - true if the agent is required, false otherwise

init

public void init(SK.gnome.dwarf.Server parent)
          throws SK.gnome.dwarf.ServiceException
Initializes the service.

Throws:
SK.gnome.dwarf.ServiceException

init

protected void init(MailAgentContext context)
             throws MailException
Initializes the mail agent.

Initializes the contained MailFilter instances.

Parameters:
context - the mail context associated with this agent
Throws:
MailException - if an error occured

destroy

protected void destroy()
                throws MailException
Destroys the mail agent.

Destroys the contained MailFilter instances.

Throws:
MailException - if an error occured

preprocess

protected void preprocess(MailAgentMessage message,
                          java.util.Collection recipients)
                   throws java.io.IOException,
                          MailException
Processes the message.

This method is called on the agent only once for each message, just after it has arrived to the mail queue. In order to let this happen, the agent must implement the Preprocessing interface.

The recipients argument is a collection of Recipient objects representing the message recipients, as returned after processing by the mail filter chain. This collection is always non-empty.

Parameters:
message - the queued message
recipients - collection of recipients
Throws:
java.io.IOException - if an I/O error occured
MailException - if an error occured

postprocess

protected void postprocess(MailAgentMessage message,
                           java.util.Collection recipients)
                    throws java.io.IOException,
                           MailException
Processes the message.

This method is called on the agent several times for each message, as it is successively delivered to the particular recipients. In order to let this happen, the agent must implement the Postprocessing interface.

The recipients argument is a collection of Recipient objects representing the message recipients, as returned after processing by the mail filter chain. This collection is always non-empty, and contains only those recipients, for which the actual delivery process succeded (or failed).

Parameters:
message - the queued message
recipients - collection of recipients
Throws:
java.io.IOException - if an I/O error occured
MailException - if an error occured

filter

protected java.util.Collection filter(MailAgentMessage message,
                                      java.util.Collection recipients)
                               throws MailException
Filters the given message.

This method is called on the agent before the message is passed to its processing method. By default, it passes the message to the contained MailFilter objects in order they were added to the agent.

Parameters:
message - the queued message
recipients - the recipients
Returns:
the filtered collection of recipients
Throws:
MailException - if an error occured

storeMessage

protected void storeMessage(java.lang.String user,
                            java.lang.String folder,
                            MailAgentMessage message)
                     throws java.io.IOException,
                            MailException
Stores the given message to the local mail store.

This is a template method which calls context's storeMessage method to actually store the message.

Parameters:
user - the user identification
folder - the full folder name
message - the queued message
Throws:
java.io.IOException - if an I/O error occured
MailException - if an error occured


Copyright (c) 2004-2005, Gnome Ltd. All rights reserved.