de.aristaflow.adept2.core.eventmanager.mailevents

Class MailEventSource

java.lang.Object

de.aristaflow.adept2.core.eventmanager.common.AbstractEventSource<MailEvent>

de.aristaflow.adept2.core.eventmanager.mailevents.MailEventSource

All Implemented Interfaces:

EventSource<MailEvent>, MailSource, PollingMailSource, PollingSource<MailEvent>, java.lang.Runnable

Direct Known Subclasses:

FilteredMailEventSource, MailEventActivitySource

public class MailEventSource
extends AbstractEventSource<MailEvent>
implements PollingMailSource

A source for events based on mails in a specific folder (usually the INBOX). This folder is checked regularly and any mail found is notified as event to the corresponding event handler.

Author:

Ulrich Kreher

Field Summary

Fields

Modifier and Type	Field and Description
protected java.net.URI[]	eventManagerURIs The event manager URIs to provide to the created events.
protected java.lang.String	folderName The name of the folder which causes an event when a new mail is received.
protected java.lang.String	host The host to connect to and from which to use as mail source.
protected boolean	keepConnection Whether the mail storage should not be disconnected between polls.
protected java.lang.String	password The password to connect to the host with.
protected java.lang.Long	pollTime The time in milliseconds this event source polls its data source.
protected int	port The port of the host to which to connect to.
protected java.lang.String	protocol The protocol to use for this mail events, for instance pop3, imap, ...
protected java.lang.Long	startPoint The start point (in milliseconds) this event should start polling.
protected javax.mail.Store	store The mail server which to check for mails.
protected long	timeout The timeout in milliseconds this event source uses for the mail server.
protected java.lang.String	userName The user name to connect to the host with.

Fields inherited from class de.aristaflow.adept2.core.eventmanager.common.AbstractEventSource

eventType, handlerList, id, lock, logger, sourceType, thread, threadLock

Fields inherited from interface de.aristaflow.adept2.model.events.sources.PollingMailSource

CONF_KEEP_CONNECTION

Fields inherited from interface de.aristaflow.adept2.model.events.sources.PollingSource

CONF_POLL_TIME, CONF_START_TIME

Fields inherited from interface de.aristaflow.adept2.model.events.sources.MailSource

CONF_FOLDER, CONF_HOST, CONF_PASSWORD, CONF_PORT, CONF_PROTOCOL, CONF_TIMEOUT, CONF_USER_NAME

Constructor Summary

Constructors

Modifier	Constructor and Description
	MailEventSource(Configuration conf, EventManager eventManager, Registry registry) Default constructor for a plugin of an EventManager called by a service registry.
protected	MailEventSource(Configuration conf, EventManager eventManager, Registry registry, java.lang.Class<?> confDesc) Constructor for subclasses allowing to set a separate class for the configuration description.

Method Summary

Modifier and Type	Method and Description
void	checkForAndHandleEvent() Checks for an event and handles it (usually by using AbstractEventSource.forwardEvent(Event, boolean, boolean)).
protected void	close(javax.mail.Folder folder) Closes and expunges the designated folder if it is open.
protected void	closeStore() Closes the message store of this event source.
protected void	connectToStore() Connects to the configured store of this event source.
protected MailEvent	createMailEvent(javax.mail.Message message) Creates a MailEvent for the designated message.
long	getPollTime() Gets the time in milliseconds this event source polls, more precisely, the time span between two polls.
long	getStartTime() Gets the absolute time in milliseconds since midnight, January 1, 1970 UTC when this polling source should start polling.
void	init() Initialises this polling source.
protected boolean	nextHandler(MailEvent event, boolean consumed, boolean concurrent) This method is called right before an event is offered to the next handler.
protected javax.mail.Folder	openFolder() Opens and returns the folder configured for the message store in read/write mode.
protected void	setConfiguration(Configuration conf, boolean completed) Sets the internal fields according to the values of the designated configuration.
void	setConfiguration(Configuration conf, java.lang.String id) Sets the (additional) configuration of this event source and its ID.
void	terminate() Terminates this polling source.
protected boolean	timedOut(java.lang.Throwable t) Gets whether the designated throwable indicates a timeout.
protected void	verifyConfigurationValues() This method verifies the configuration values that have been set yet.

Methods inherited from class de.aristaflow.adept2.core.eventmanager.common.AbstractEventSource

addAll, addedHandlerLocked, addedHandlerLocked, addHandler, createPattern, forwardEvent, getEventHandler, getHierarchicalSourceName, getID, getType, maskedInterrupt, maskInterrupt, removeHandler, removingHandlerLocked, replaceValueParams, run, unmaskInterrupt

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface de.aristaflow.adept2.model.events.sources.EventSource

addAll, addHandler, getEventHandler, getHierarchicalSourceName, getID, getType, removeHandler

Methods inherited from interface java.lang.Runnable

run

Field Detail

pollTime

protected java.lang.Long pollTime

The time in milliseconds this event source polls its data source.

startPoint

protected java.lang.Long startPoint

The start point (in milliseconds) this event should start polling.

keepConnection

protected boolean keepConnection

Whether the mail storage should not be disconnected between polls.

protocol

protected java.lang.String protocol

The protocol to use for this mail events, for instance pop3, imap, ...

host

protected java.lang.String host

The host to connect to and from which to use as mail source.

port

protected int port

The port of the host to which to connect to.

userName

protected java.lang.String userName

The user name to connect to the host with.

password

protected java.lang.String password

The password to connect to the host with.

folderName

protected java.lang.String folderName

The name of the folder which causes an event when a new mail is received. If not specified the usual INBOX will be used.

timeout

protected long timeout

The timeout in milliseconds this event source uses for the mail server.

eventManagerURIs

protected final java.net.URI[] eventManagerURIs

The event manager URIs to provide to the created events.

store

protected javax.mail.Store store

The mail server which to check for mails. This will be null in case this source is not connected.

Constructor Detail

MailEventSource

public MailEventSource(Configuration conf,
                       EventManager eventManager,
                       Registry registry)
                throws ConfigurationException

Default constructor for a plugin of an EventManager called by a service registry.

Note that this constructor calls setConfiguration(Configuration, boolean); subclasses may not be fully initialised at this point.

Parameters:

conf - The configuration as provided from the registry.

eventManager - The event manager this event source is a plugin of.

registry - The registry of this plugin.

Throws:

ConfigurationException - If the configuration is not valid for a PollingMailSource, a ConfigurationException will be thrown.

MailEventSource

protected MailEventSource(Configuration conf,
                          EventManager eventManager,
                          Registry registry,
                          java.lang.Class<?> confDesc)
                   throws ConfigurationException

Constructor for subclasses allowing to set a separate class for the configuration description.

Note that this constructor calls setConfiguration(Configuration, boolean); subclasses may not be fully initialised at this point.

Parameters:

conf - The configuration as provided from the registry.

eventManager - The event manager this event source is a plugin of.

registry - The registry of this plugin.

confDesc - The class (or interface) providing the configuration description to validate.

Throws:

ConfigurationException - If the configuration is not valid for a PollingMailSource, a ConfigurationException will be thrown.

Method Detail

setConfiguration

protected void setConfiguration(Configuration conf,
                                boolean completed)
                         throws ConfigurationException

Sets the internal fields according to the values of the designated configuration. Note that this method is called from the constructor and therefore this object may not be fully initialised!

Parameters:

conf - The configuration from which to get the configuration values.

completed - Whether the configuration is complete after this setting and therefore the values should be verified.

Throws:

ConfigurationException - If there are problems with the configuration, for instance the configuration does not provide required values, a ConfigurationException may be thrown.

verifyConfigurationValues

protected void verifyConfigurationValues()
                                  throws ConfigurationException

This method verifies the configuration values that have been set yet. If a configuration value is missing or inappropriate, a ConfigurationException will be thrown.

Throws:

ConfigurationException - If there are problems with the configuration, for instance the configuration does not provide required values, a ConfigurationException may be thrown.

setConfiguration

public void setConfiguration(Configuration conf,
                             java.lang.String id)
                      throws ConfigurationException

Description copied from interface: EventSource

Sets the (additional) configuration of this event source and its ID. The configuration is additional with respect to the configuration provided by the plugin load mechanism, if the event source is loaded as plugin.
It is ensured that this method will be called before Runnable.run().

Specified by:

setConfiguration in interface EventSource<MailEvent>

Overrides:

setConfiguration in class AbstractEventSource<MailEvent>

Parameters:

conf - The configuration of this event source. This adheres (and overwrites) the configuration provided by the plugin loading, if this event source has been loaded as plugin. Whether this is allowed to be null depends on the implementation of the event source.

id - The ID of this event source. This must not be null nor the empty string.

Throws:

ConfigurationException - If there are problems with the designated configuration (configuration is null although this is not allowed, a required configuration value is missing, ...), a ConfigurationException will be thrown.

getPollTime

public long getPollTime()

Description copied from interface: PollingSource

Gets the time in milliseconds this event source polls, more precisely, the time span between two polls. If this is 0 or negative, no polling will apply. However, PollingSource.init() and PollingSource.terminate() will be called.

Specified by:

getPollTime in interface PollingSource<MailEvent>

Returns:

The time in milliseconds this event source polls (> 0).

getStartTime

public long getStartTime()

Description copied from interface: PollingSource

Gets the absolute time in milliseconds since midnight, January 1, 1970 UTC when this polling source should start polling. This is used for calculating the first poll time by adding the time span defined in PollingSource.getPollTime().

Specified by:

getStartTime in interface PollingSource<MailEvent>

Returns:

The absolute time in milliseconds since midnight, January 1, 1970 UTC when this polling source should start polling.

init

public void init()

Description copied from interface: PollingSource

Initialises this polling source. This is called once before polling is started the first time.

Specified by:

init in interface PollingSource<MailEvent>

checkForAndHandleEvent

public void checkForAndHandleEvent()

Description copied from class: AbstractEventSource

Checks for an event and handles it (usually by using AbstractEventSource.forwardEvent(Event, boolean, boolean)).

Specified by:

checkForAndHandleEvent in class AbstractEventSource<MailEvent>

terminate

public void terminate()

Description copied from interface: PollingSource

Terminates this polling source. This is called once after polling has terminated and this source is removed.
Note that this may be called any time, even when creating or handling an event. So take care to synchronise the implementation appropriately!

Specified by:

terminate in interface PollingSource<MailEvent>

createMailEvent

protected MailEvent createMailEvent(javax.mail.Message message)
                             throws javax.mail.MessagingException,
                                    java.io.IOException

Creates a MailEvent for the designated message.

Parameters:

message - The message for which to create a MailEvent.

Returns:

The MailEvent created for the designated message.

Throws:

javax.mail.MessagingException - If retrieving the required data from the message fails, a MessagingException will be thrown.

java.io.IOException - Retrieving the (complex) content of the message may thrown an IOException.

nextHandler

protected boolean nextHandler(MailEvent event,
                              boolean consumed,
                              boolean concurrent)

Description copied from class: AbstractEventSource

This method is called right before an event is offered to the next handler. In case of concurrent handling, this method will only be called once for all concurrent handling but this will be indicated by the corresponding parameter.

Specified by:

nextHandler in class AbstractEventSource<MailEvent>

Parameters:

event - The event which is about to be handled by the next registered handler.

consumed - Whether the event has been consumed yet.

concurrent - Whether the next event handling is concurrent and thus the event will be offered to several event handler concurrently.

Returns:

Whether the event handling may continue. In case of serious problems preventing further event handling, return false here.

connectToStore

protected void connectToStore()
                       throws javax.mail.MessagingException

Connects to the configured store of this event source.

Throws:

javax.mail.MessagingException - If there are problems connecting to the store, a MessagingException will be thrown.

closeStore

protected void closeStore()
                   throws javax.mail.MessagingException

Closes the message store of this event source.

Throws:

javax.mail.MessagingException - If there are problems closing the store, a MessagingException will be thrown.

openFolder

protected javax.mail.Folder openFolder()
                                throws javax.mail.MessagingException

Opens and returns the folder configured for the message store in read/write mode.

Returns:

The opened folder configured for the message store.

Throws:

javax.mail.MessagingException - If there are problems retrieving or opening the folder, a MessagingException will be thrown.

close

protected void close(javax.mail.Folder folder)
              throws javax.mail.MessagingException

Closes and expunges the designated folder if it is open.

Parameters:

folder - The folder to close and expunge.

Throws:

javax.mail.MessagingException - If there are problems closing the designated folder, a MessagingException will be thrown.

timedOut

protected boolean timedOut(java.lang.Throwable t)

Gets whether the designated throwable indicates a timeout. Depending on the protocol provider, a timeout can be signalled differently.

Parameters:

t - The throwable which to check for whether it indicates a timeout.

Returns:

Whether the designated throwable indicates a timeout.