org.jumpi.impl.connector.email
Class EmailConnector

java.lang.Object
  |
  +--org.jumpi.impl.AbstractConnector
        |
        +--org.jumpi.impl.connector.email.EmailConnector

All Implemented Interfaces:

Component, Configurable, Connector, Manageable, java.lang.Runnable, Task

public class EmailConnector

extends AbstractConnector

The EmailConnector allows to send and receive E-mail messages.

Field Summary

static java.lang.String

PROPERTY_EMAIL_SUBJECT Property for setting the subject of an email when sending.

Fields inherited from class org.jumpi.impl.AbstractConnector

cancelledRecvs_, cancelledSends_, controller_, joinFailInterval_, joinTestInterval_, jumpi_, maxRecvBacklog_, maxSendBacklog_, name_, protocol_, recvQueue_, recvTransformer_, sendQueue_, sendTransformer_, started_, stopping_, taskId_, url_format_, url_prefix_

Constructor Summary

EmailConnector()

Method Summary

void	cancelRecv(Envelope env) Does nothing.
void	cancelSend(Envelope env) Does nothing.
protected boolean	checkJoinCondition() The shutdown join condition is true if there are no pending send or receive operations.
void	configure(java.lang.String name, Properties props) Configure the EmailConnector.
Destination	getDestination(java.lang.String url, java.util.Hashtable clientProps) Get the Destination corresponding to the Url provided.
void	manage(Component root, Component parent, java.lang.String operation, java.util.Hashtable parameters) Perform a recursive management operation through the Jumpi component tree, using the parameters provided.
protected boolean	onRecv(Envelope env) Receive an email Message from an Email account.
protected boolean	onSend(Envelope env) Send an email Message.
void	recv(Envelope env) Perform the recv synchronously.
void	send(Envelope env) Perform the send synchronously.
protected void	shutdownState() Clear the pending send and receive operations.

Methods inherited from class org.jumpi.impl.AbstractConnector

getName, getTaskId, isLongRunning, isSchedulable, run

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_EMAIL_SUBJECT

public static final java.lang.String PROPERTY_EMAIL_SUBJECT

Property for setting the subject of an email when sending. Value email.subject.

See Also:

Constant Field Values

Constructor Detail

EmailConnector

public EmailConnector()

Method Detail

configure

public void configure(java.lang.String name,
                      Properties props)
               throws java.lang.Exception

Configure the EmailConnector.

The following configuration attributes are defined in addition to those of the superclass:

• smtphost - string - optional[localhost].

  The SMTP hostname where there the SMTP server resides for sending messages.

• defaultfrom - string - optional[nooneCnowhere].

  The default from email address if none is provided on send.

• accessprotocol - string - optional[none].

  The protocol to use in accessing an email account - none, imap or pop3. If none is chosen, then no email reception is possible, and the host, username and password parameters are not used.

• accesshost - string - optional[none].

  The host to access via the accessprotocol. Only required if accessprotocol is not none.

• username - string - optional[none].

  The imap or pop3 account username. Only required if accessprotocol is not none.

• password - string - optional[none].

  The imap or pop3 account password. Only required if accessprotocol is not none.

• inboxname - string - optional[Inbox].

  The folder name of the imap or pop3 account folder from which to receive email messages. Only required if accessprotocol is not none.

• autodelete - boolean - optional[true].

  Whether to automatically delete messages which have been passed up to the client layer and retrieved from the email account. If false, the client layer itself must call javax.mail.Message.setFlag(Flags.Flag.DELETED,true) on the message received, so that it is not received multiple times on subsequent polls from the email account. Setting to false gives additional robustness, such that the client can guarrantee that the mail is only deleted AFTER it is processed, but at the expense of additional client layer coding.

• pollinterval - integer[10000..MAX-INT] - optional[10000].

  The time in milliseconds to between successive polls of the email account for new messages. Polling takes place only when all received messages have been read.

Specified by:

configure in interface Configurable

Overrides:

configure in class AbstractConnector

Parameters:

name - the fully qualified instance name.

props - the read-only properties to configure the instance with.

Throws:

java.lang.Exception - when configuration is unsuccessful.

manage

public void manage(Component root,
                   Component parent,
                   java.lang.String operation,
                   java.util.Hashtable parameters)
            throws java.lang.Exception

Perform a recursive management operation through the Jumpi component tree, using the parameters provided.

• STARTUP. Establish the java mail Session.
• JOIN. Close the java mail Session.

Specified by:

manage in interface Manageable

Overrides:

manage in class AbstractConnector

Parameters:

root - the Jumpi instance at the root of the component tree.

parent - the immediate parent of the component.

operation - the operation.

parameters - the operation parameters.

Throws:

java.lang.Exception - if any failure to perform management occurs.

checkJoinCondition

protected boolean checkJoinCondition()

The shutdown join condition is true if there are no pending send or receive operations.

Specified by:

checkJoinCondition in class AbstractConnector

Returns:

true if there are no pending send or receive operations.

shutdownState

protected void shutdownState()

Clear the pending send and receive operations.

Specified by:

shutdownState in class AbstractConnector

getDestination

public Destination getDestination(java.lang.String url,
                                  java.util.Hashtable clientProps)

Get the Destination corresponding to the Url provided.

Specified by:

getDestination in interface Connector

Overrides:

getDestination in class AbstractConnector

Parameters:

url - the Url of the EmailConnector.

clientProps - not used.

Returns:

a Destination if the Url corresponds to an email address, otherwise null.

Throws:

java.lang.IllegalArgumentException - when url is null.

onSend

protected boolean onSend(Envelope env)
                  throws java.lang.Exception

Send an email Message.

The message format required at the EmailConnector layer is either a MimeMessage or simply a String. If a send transformer is configured, then the transformer must transform the message Object into a MimeMessage or a String, and place onto the envelope's context stack.

Allows only a single send at a time, blocking if multiple sends are performed concurrently.

This operation may block if the underlying java mail send blocks.

The PROPERTY_EMAIL_SUBJECT is the subject text, overriding any MimeMessage subject if sending with a MimeMessage.

Specified by:

onSend in class AbstractConnector

Parameters:

env - the Envelope containing the MimeMessage to send.

Returns:

true on success or false for a manged failure.

Throws:

java.lang.Exception - if a failure condition occurs.

send

public void send(Envelope env)
          throws java.lang.Exception

Perform the send synchronously.

Specified by:

send in interface Connector

Overrides:

send in class AbstractConnector

Parameters:

env - the Envelope which gives the Destination to send to and the message itself.

Throws:

java.lang.Exception - if any failure condition occurs during the send method.

java.lang.IllegalArgumentException - when env is null.

java.lang.IllegalStateException - when not started or stopping.

See Also:

Controller.callbackSend(org.jumpi.spi.Envelope, boolean, java.lang.String)

cancelSend

public void cancelSend(Envelope env)

Does nothing.

Specified by:

cancelSend in interface Connector

Overrides:

cancelSend in class AbstractConnector

Parameters:

env - the send operation's Envelope to cancel.

onRecv

protected boolean onRecv(Envelope env)
                  throws java.lang.Exception

Receive an email Message from an Email account.

The receive operation delivers a javax.mail.Message object.

Allows only a single receive at a time, blocking if multiple receives are performed concurrently.

Blocks until an unread email is received from the email account.

Specified by:

onRecv in class AbstractConnector

Parameters:

env - the Envelope containing the Destination to receive from.

Returns:

true on success, else false for managed failure.

Throws:

java.lang.Exception - if a failure condition occurs.

recv

public void recv(Envelope env)
          throws java.lang.Exception

Perform the recv synchronously.

Specified by:

recv in interface Connector

Overrides:

recv in class AbstractConnector

Parameters:

env - the Envelope which gives the Destination to receive from and where the received message is eventually placed with the sender.

Throws:

java.lang.Exception - if any failure condition occurs during the recv method.

java.lang.IllegalArgumentException - when env is null.

java.lang.IllegalStateException - when not started or stopping.

See Also:

Controller.callbackRecv(org.jumpi.spi.Envelope, boolean, java.lang.String)

cancelRecv

public void cancelRecv(Envelope env)

Does nothing.

Specified by:

cancelRecv in interface Connector

Overrides:

cancelRecv in class AbstractConnector

Parameters:

env - the recv operation's Envelope to cancel.