GridGain™ 2.1.0
Java API Specification

org.gridgain.grid.spi.communication.mail
Class GridMailCommunicationSpi

java.lang.Object
  extended by org.gridgain.grid.spi.GridSpiAdapter
      extended by org.gridgain.grid.spi.communication.mail.GridMailCommunicationSpi
All Implemented Interfaces:
GridCommunicationSpi, GridMailCommunicationSpiMBean, GridSpi, GridSpiManagementMBean

@GridSpiInfo(author="GridGain Systems",
             url="www.gridgain.org",
             email="support@gridgain.com",
             version="x.x")
@GridSpiMultipleInstancesSupport(value=true)
public class GridMailCommunicationSpi
extends GridSpiAdapter
implements GridCommunicationSpi, GridMailCommunicationSpiMBean

Email implementation of GridCommunicationSpi. Email communication is provided for cases where nodes from different networks (even different countries) need to participate in grid task execution together as it usually can penetrate through any firewall. It supports SMTP/POP and IMAP email access protocols and can be used to connect to any public or private email server out there.

When working with email communication, make sure that maximum send/receive limit set by mail server is not exceeded. Sometimes it is better to configure your own mail server to avoid such limitations.

Note, that due to its nature mail communication is much slower than other implementations of communication SPI's and measures communication delays in minutes rather than in seconds. This means that execution of some tasks can fail more often than with other SPI's due to nodes leaving grid topology. In most cases user should implement a custom failover resolution in GridTask implementation, which should check if a node is still alive using Grid.pingNode(UUID) method. Use this SPI whenever it is acceptable to react to node topology changes with substantial delay.

Configuration

Mandatory

The following configuration parameters are mandatory:

Optional

The following configuration parameters are optional.

Java Example

GridMailCommunicationSpi needs to be explicitely configured:
 GridMailCommuncationSpi commSpi = new GridMailCommuncationSpi();

 // Inbox configuration.
 commSpi.setInHost("pop.google.com");

 // Outbox configuration.
 commSpi.setOutHost("smtp.google.com");

 // Incoming/outgoing e-mail address configuration.
 commSpi.setFromAddress("grid@google.com");

 GridConfigurationAdapter cfg = new GridConfigurationAdapter();

 // Override default communication SPI.
 cfg.setCommunicationSpi(commSpi);

 // Start grid.
 GridFactory.start(cfg);
 

Spring Example

GridMailCommunicationSpi can be configured from Spring XML configuration file:
 <bean id="grid.custom.cfg" class="org.gridgain.grid.GridConfigurationAdapter" singleton="true">
         ...
         <property name="communicationSpi">
             <bean class="org.gridgain.grid.spi.communication.mail.GridMailCommunicationSpi">
                 <property name="outHost" value="smtp.google.com"/>
                 <property name="inHost" value="pop.google.com"/>
                 <property name="fromAddress" value="grid@google.com"/>
             </bean>
         </property>
         ...
 </bean>
 


For information about Spring framework visit www.springframework.org



See Also:

  Documentation
  Email Support
  Online Forums
  Issue Tracking

Author:   2005-2008 Copyright © GridGain Systems. All Rights Reserved. ver. 2.1.0

See Also:
GridCommunicationSpi
 

Field Summary
static String ATTR_EMAIL_ADDR
          Node email address attribute name (value is comm.email.address).
static long DFLT_LEAVE_MSGS_ON_SERVER
          Leave messages on server in milliseconds (value is 86400000).
static long DFLT_RECEIVER_DELAY
          Delay in milliseconds between receiving email (value is 10000).
static String DFLT_STORE_FILE_NAME
          Default local storage file name (value is grid-email-comm-msgs.dat).
static String DFLT_SUBJ
          Default subject of email (value is grid.email.comm.msg).
 
Constructor Summary
GridMailCommunicationSpi()
          Set SPI default values for mailboxes configurations.
 
Method Summary
protected  List<String> getConsistentAttributeNames()
          Returns back list of attributes that should be consistent for this SPI.
 String getFolderName()
          Gets folder name of email folder on mail server.
 String getFromAddress()
          Gets message field 'From' all email messages.
 String getInConnectionTypeFormatted()
          Gets type of incoming mail connection.
 Properties getInCustomProperties()
          Gets custom properties required for receiving connection.
 String getInHost()
          Gets incoming host name for receiving email (usually either POP or IMAP).
 int getInPort()
          Gets incoming host port number for receiving email.
 String getInProtocolFormatted()
          Sets incoming mail protocol.
 String getInUsername()
          Gets incoming host username for receiving email.
 long getLeaveMessagesOnServer()
          Gets incoming messages life-time on mail server in milliseconds.
 Map<String,Serializable> getNodeAttributes()
          This method is called before SPI starts (before method GridSpi.spiStart(String) is called). It allows SPI implementation to add attributes to a local node. Kernel collects these attributes from all SPI implementations loaded up and then passes it to discovery SPI so that they can be exchanged with other nodes.
 String getOutConnectionTypeFormatted()
          Gets type of outgoing mail connection.
 Properties getOutCustomProperties()
          Gets custom properties required for outgoing connection.
 String getOutHost()
          Gets outgoing host name for sending email (usually either SMTP or IMAP).
 int getOutPort()
          Gets port number for outgoing mail.
 String getOutProtocolFormatted()
          Gets outgoing mail protocol.
 String getOutUsername()
          Gets username for outgoing mail authentication.
 int getReadBatchSize()
          Gets number of messages fetched from mail server at a time.
 long getReceiverDelay()
          Gets interval in milliseconds between checking for new messages.
 String getStoreFileName()
          Gets locally stored full file name for all read messages.
 String getSubject()
          Gets email message subject.
 void sendMessage(Collection<GridNode> destNodes, Serializable msg)
          Sends given message to destination nodes.
 void sendMessage(GridNode destNode, Serializable msg)
          Sends given message to destination node.
 void setFolderName(String folderName)
          Sets name of email folder on mail server.
 void setFromAddress(String addr)
          Sets 'From' address for all email messages.
 void setInConnectionType(GridMailCommunicationType type)
          Sets type of incoming mail connection which should be one of the following: GridMailCommunicationType.NONE GridMailCommunicationType.SSL GridMailCommunicationType.STARTTLS If not provided, default value is GridMailCommunicationType.NONE.
 void setInCustomProperties(Properties props)
          Sets any custom properties required for receiving connection.
 void setInHost(String host)
          Sets incoming host name for receiving emails (usually either POP or IMAP).
 void setInPassword(String pswd)
          Sets password for incoming mail authentication.
 void setInPort(int port)
          Sets port number for incoming mail.
 void setInProtocol(GridMailCommunicationInProtocol proto)
          Sets incoming mail protocol.
 void setInUsername(String username)
          Sets username for incoming mail authentication.
 void setLeaveMessagesOnServer(long leaveMsgsOnServer)
          Sets incoming messages life-time on mail server in milliseconds.
 void setListener(GridMessageListener listener)
          Set communication listener.
 void setOutConnectionType(GridMailCommunicationType type)
          Sets type of outgoing mail connection which should be one of the following: GridMailCommunicationType.NONE GridMailCommunicationType.SSL GridMailCommunicationType.STARTTLS If not provided, default value is GridMailCommunicationType.NONE.
 void setOutCustomProperties(Properties props)
          Sets any custom properties required for outgoing connection.
 void setOutHost(String host)
          Sets outgoing host name for sending emails (usually either SMTP or IMAP).
 void setOutPassword(String pswd)
          Sets password for outgoing mail authentication.
 void setOutPort(int port)
          Sets port number for outgoing mail.
 void setOutProtocol(GridMailCommunicationOutProtocol proto)
          Sets outgoing mail protocol.
 void setOutUsername(String username)
          Sets username for outgoing mail authentication.
 void setReadBatchSize(int size)
          Sets number of messages fetched from mail server at a time.
 void setReceiverDelay(long recvDelay)
          Sets interval in milliseconds between checking for new messages.
 void setStoreFileName(String fileName)
          Sets locally stored full file name for all read messages.
 void setSubject(String subj)
          Sets email message subject.
 void spiStart(String gridName)
          This method is called to start SPI.
 void spiStop()
          This method is called to stop SPI.
 String toString()
          
 
Methods inherited from class org.gridgain.grid.spi.GridSpiAdapter
assertParameter, configInfo, createSpiAttributeName, getAuthor, getGridGainHome, getLocalNodeId, getName, getSpiContext, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, getVendorEmail, getVendorUrl, getVersion, onContextDestroyed, onContextInitialized, registerMBean, setName, setSpiContext, startInfo, startStopwatch, stopInfo, unregisterMBean
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.gridgain.grid.spi.GridSpi
getName, onContextDestroyed, onContextInitialized
 
Methods inherited from interface org.gridgain.grid.spi.GridSpiManagementMBean
getAuthor, getGridGainHome, getLocalNodeId, getName, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, getVendorEmail, getVendorUrl, getVersion
 

Field Detail

DFLT_SUBJ

public static final String DFLT_SUBJ
Default subject of email (value is grid.email.comm.msg).

See Also:
Constant Field Values

DFLT_STORE_FILE_NAME

public static final String DFLT_STORE_FILE_NAME
Default local storage file name (value is grid-email-comm-msgs.dat).

See Also:
Constant Field Values

DFLT_RECEIVER_DELAY

public static final long DFLT_RECEIVER_DELAY
Delay in milliseconds between receiving email (value is 10000).

See Also:
Constant Field Values

DFLT_LEAVE_MSGS_ON_SERVER

public static final long DFLT_LEAVE_MSGS_ON_SERVER
Leave messages on server in milliseconds (value is 86400000).

See Also:
Constant Field Values

ATTR_EMAIL_ADDR

public static final String ATTR_EMAIL_ADDR
Node email address attribute name (value is comm.email.address).

See Also:
Constant Field Values
Constructor Detail

GridMailCommunicationSpi

public GridMailCommunicationSpi()
Set SPI default values for mailboxes configurations.

Method Detail

getNodeAttributes

public Map<String,Serializable> getNodeAttributes()
                                           throws GridSpiException
This method is called before SPI starts (before method GridSpi.spiStart(String) is called). It allows SPI implementation to add attributes to a local node. Kernel collects these attributes from all SPI implementations loaded up and then passes it to discovery SPI so that they can be exchanged with other nodes.

Specified by:
getNodeAttributes in interface GridSpi
Overrides:
getNodeAttributes in class GridSpiAdapter
Throws:
GridSpiException - Throws in case of any error.
Returns:
Map of local node attributes this SPI wants to add.

setOutHost

@GridSpiConfiguration(optional=false)
public void setOutHost(String host)
Sets outgoing host name for sending emails (usually either SMTP or IMAP).

There is no default value for the parameter.

Parameters:
host - Outgoing email host name.

setOutConnectionType

@GridSpiConfiguration(optional=true)
public void setOutConnectionType(GridMailCommunicationType type)
Sets type of outgoing mail connection which should be one of the following:

If not provided, default value is GridMailCommunicationType.NONE.

Parameters:
type - Connection type.

setOutPort

@GridSpiConfiguration(optional=true)
public void setOutPort(int port)
Sets port number for outgoing mail.

If not provided, default value is 25.

Parameters:
port - Outgoing email port number.

setOutUsername

@GridSpiConfiguration(optional=true)
public void setOutUsername(String username)
Sets username for outgoing mail authentication. If provided, then password should also be provided. Username with null value means that no authentication will be used.

If not provided, default value is null.

Parameters:
username - Outbox username.

setOutPassword

@GridSpiConfiguration(optional=true)
public void setOutPassword(String pswd)
Sets password for outgoing mail authentication. If provided, then username should also be provided.

If not provided, default value is null.

Parameters:
pswd - Outbox password.

setInHost

@GridSpiConfiguration(optional=false)
public void setInHost(String host)
Sets incoming host name for receiving emails (usually either POP or IMAP).

There is no default value.

Parameters:
host - Incoming email host name.

setInConnectionType

@GridSpiConfiguration(optional=true)
public void setInConnectionType(GridMailCommunicationType type)
Sets type of incoming mail connection which should be one of the following:

If not provided, default value is GridMailCommunicationType.NONE.

Parameters:
type - Connection type.

setInPort

@GridSpiConfiguration(optional=true)
public void setInPort(int port)
Sets port number for incoming mail.

If not provided, default value is 110.

Parameters:
port - Incoming email server port number.

setInUsername

@GridSpiConfiguration(optional=true)
public void setInUsername(String username)
Sets username for incoming mail authentication. If provided, then password should also be provided. Username with null value means that no authentication will be used.

If not provided, default value is null.

Parameters:
username - Incoming mailbox username.

setInPassword

@GridSpiConfiguration(optional=true)
public void setInPassword(String pswd)
Sets password for incoming mail authentication. If provided, then username should also be provided.

If not provided, default value is null.

Parameters:
pswd - Incoming mailbox password.

setSubject

@GridSpiConfiguration(optional=true)
public void setSubject(String subj)
Sets email message subject.

If not provided, default value is grid.email.comm.msg.

Parameters:
subj - Email message subject.

setFolderName

@GridSpiConfiguration(optional=true)
public void setFolderName(String folderName)
Sets name of email folder on mail server.

If not provided, default value is Inbox.

Parameters:
folderName - Mail server folder name.

setFromAddress

@GridSpiConfiguration(optional=false)
public void setFromAddress(String addr)
Sets 'From' address for all email messages. It is added as GridMailCommunicationSpi.ATTR_EMAIL_ADDR node attribute so it can be accessed on remote nodes. This address is used by other nodes to send email to this node.

There is no default value.

Parameters:
addr - Email address for data exchange.

setInCustomProperties

@GridSpiConfiguration(optional=true)
public void setInCustomProperties(Properties props)
Sets any custom properties required for receiving connection.

If not provided, default value is null.

Parameters:
props - Custom properties.

setOutCustomProperties

@GridSpiConfiguration(optional=true)
public void setOutCustomProperties(Properties props)
Sets any custom properties required for outgoing connection.

If not provided, default value is null.

Parameters:
props - Custom parameter.

setReadBatchSize

@GridSpiConfiguration(optional=true)
public void setReadBatchSize(int size)
Sets number of messages fetched from mail server at a time.

If not provided, default value is 100.

Parameters:
size - Number of fetched messages.

setReceiverDelay

@GridSpiConfiguration(optional=true)
public void setReceiverDelay(long recvDelay)
Sets interval in milliseconds between checking for new messages.

If not provided, default value is GridMailCommunicationSpi.DFLT_RECEIVER_DELAY.

Parameters:
recvDelay - Inverval between receiving messages.

setOutProtocol

@GridSpiConfiguration(optional=true)
public void setOutProtocol(GridMailCommunicationOutProtocol proto)
Sets outgoing mail protocol. Should be one of the following:

If not provided, default value is GridMailCommunicationOutProtocol.SMTP.

Parameters:
proto - Outgoing mail protocol.

setInProtocol

@GridSpiConfiguration(optional=true)
public void setInProtocol(GridMailCommunicationInProtocol proto)
Sets incoming mail protocol. Should be one of the following:

If not provided, default value is GridMailCommunicationInProtocol.POP3.

Parameters:
proto - Incoming protocol.

setStoreFileName

@GridSpiConfiguration(optional=true)
public void setStoreFileName(String fileName)
Sets locally stored full file name for all read messages. Can be either full path or a path relative to GridGain installation home folder.

If not provided, default value is GridMailCommunicationSpi.DFLT_STORE_FILE_NAME.

Parameters:
fileName - Local storage file name.

setLeaveMessagesOnServer

@GridSpiConfiguration(optional=true)
public void setLeaveMessagesOnServer(long leaveMsgsOnServer)
Sets incoming messages life-time on mail server in milliseconds.

If not provided, default value is GridMailCommunicationSpi.DFLT_LEAVE_MSGS_ON_SERVER.

Parameters:
leaveMsgsOnServer - Time to live for incoming messages.

getReceiverDelay

public long getReceiverDelay()
Gets interval in milliseconds between checking for new messages.

Specified by:
getReceiverDelay in interface GridMailCommunicationSpiMBean
Returns:
Interval between receiving messages.

getLeaveMessagesOnServer

public long getLeaveMessagesOnServer()
Gets incoming messages life-time on mail server in milliseconds.

Specified by:
getLeaveMessagesOnServer in interface GridMailCommunicationSpiMBean
Returns:
Time to live for incoming messages.

getOutConnectionTypeFormatted

public String getOutConnectionTypeFormatted()
Gets type of outgoing mail connection. Should be one of the following:

Specified by:
getOutConnectionTypeFormatted in interface GridMailCommunicationSpiMBean
Returns:
Connection type.

getOutProtocolFormatted

public String getOutProtocolFormatted()
Gets outgoing mail protocol. Could be one of the following:

Specified by:
getOutProtocolFormatted in interface GridMailCommunicationSpiMBean
Returns:
Outgoing mail protocol.

getOutHost

public String getOutHost()
Gets outgoing host name for sending email (usually either SMTP or IMAP).

Specified by:
getOutHost in interface GridMailCommunicationSpiMBean
Returns:
Outgoing email host name.

getOutPort

public int getOutPort()
Gets port number for outgoing mail.

Specified by:
getOutPort in interface GridMailCommunicationSpiMBean
Returns:
Outgoing email port number.

getOutUsername

public String getOutUsername()
Gets username for outgoing mail authentication.

Specified by:
getOutUsername in interface GridMailCommunicationSpiMBean
Returns:
Outbox username.

getInConnectionTypeFormatted

public String getInConnectionTypeFormatted()
Gets type of incoming mail connection. Should be one of the following:

Specified by:
getInConnectionTypeFormatted in interface GridMailCommunicationSpiMBean
Returns:
Connection type.

getReadBatchSize

public int getReadBatchSize()
Gets number of messages fetched from mail server at a time.

Specified by:
getReadBatchSize in interface GridMailCommunicationSpiMBean
Returns:
Number of fetched messages.

getInProtocolFormatted

public String getInProtocolFormatted()
Sets incoming mail protocol. Could be one of the following:

Specified by:
getInProtocolFormatted in interface GridMailCommunicationSpiMBean
Returns:
Incoming protocol.

getInHost

public String getInHost()
Gets incoming host name for receiving email (usually either POP or IMAP).

Specified by:
getInHost in interface GridMailCommunicationSpiMBean
Returns:
Incoming email host name.

getInPort

public int getInPort()
Gets incoming host port number for receiving email.

Specified by:
getInPort in interface GridMailCommunicationSpiMBean
Returns:
Incoming email host name.

getInUsername

public String getInUsername()
Gets incoming host username for receiving email.

Specified by:
getInUsername in interface GridMailCommunicationSpiMBean
Returns:
Incoming email host name.

getFolderName

public String getFolderName()
Gets folder name of email folder on mail server.

Specified by:
getFolderName in interface GridMailCommunicationSpiMBean
Returns:
Email folder name.

getSubject

public String getSubject()
Gets email message subject.

Specified by:
getSubject in interface GridMailCommunicationSpiMBean
Returns:
Email message subject.

getOutCustomProperties

public Properties getOutCustomProperties()
Gets custom properties required for outgoing connection.

Specified by:
getOutCustomProperties in interface GridMailCommunicationSpiMBean
Returns:
Outgoing connection properties.

getInCustomProperties

public Properties getInCustomProperties()
Gets custom properties required for receiving connection.

Specified by:
getInCustomProperties in interface GridMailCommunicationSpiMBean
Returns:
Properties.

getFromAddress

public String getFromAddress()
Gets message field 'From' all email messages.

Specified by:
getFromAddress in interface GridMailCommunicationSpiMBean
Returns:
Message field 'From'.

getStoreFileName

public String getStoreFileName()
Gets locally stored full file name for all read messages. Can be either full path or a path relative to GridGain installation home folder.

Specified by:
getStoreFileName in interface GridMailCommunicationSpiMBean
Returns:
Store file path.

sendMessage

public void sendMessage(GridNode destNode,
                        Serializable msg)
                 throws GridSpiException
Sends given message to destination node. Note that characteristics of the exchange such as durability, guaranteed delivery or error notification is dependant on SPI implementation.

Specified by:
sendMessage in interface GridCommunicationSpi
Throws:
GridSpiException - Thrown in case of any error during sending the message. Note that this is not guaranteed that failed communication will result in thrown exception as this is dependant on SPI implementation.
Parameters:
destNode - Destination node.
msg - Message to send.

sendMessage

public void sendMessage(Collection<GridNode> destNodes,
                        Serializable msg)
                 throws GridSpiException
Sends given message to destination nodes. Note that characteristics of the exchange such as durability, guaranteed delivery or error notification is dependant on SPI implementation.

Specified by:
sendMessage in interface GridCommunicationSpi
Throws:
GridSpiException - Thrown in case of any error during sending the message. Note that this is not guaranteed that failed communication will result in thrown exception as this is dependant on SPI implementation.
Parameters:
destNodes - Destination nodes.
msg - Message to send.

setListener

public void setListener(GridMessageListener listener)
Set communication listener.

Specified by:
setListener in interface GridCommunicationSpi
Parameters:
listener - Listener to set or null to unset the listener.

spiStart

public void spiStart(String gridName)
              throws GridSpiException
This method is called to start SPI. After this method returns successfully kernel assumes that SPI is fully operational.

Specified by:
spiStart in interface GridSpi
Throws:
GridSpiException - Throws in case of any error during SPI start.
Parameters:
gridName - Name of grid instance this SPI is being started for (null for default grid).

spiStop

public void spiStop()
             throws GridSpiException
This method is called to stop SPI. After this method returns kernel assumes that this SPI is finished and all resources acquired by it are released. Note that this method can be called at any point including during recovery of failed start. It should make no assumptions on what state SPI will be in when this method is called.

Specified by:
spiStop in interface GridSpi
Throws:
GridSpiException - Thrown in case of any error during SPI stop.

getConsistentAttributeNames

protected List<String> getConsistentAttributeNames()
Returns back list of attributes that should be consistent for this SPI. Consistency means that remote node has to have the same attribute with the same value.

Overrides:
getConsistentAttributeNames in class GridSpiAdapter
Returns:
List or attribute names.

toString

public String toString()

Overrides:
toString in class Object

GridGain™ 2.1.0
Java API Specification

GridGain™ - Grid Computing Made Simple, ver. 2.1.0.19122008
2005-2008 Copyright © GridGain Systems. All Rights Reserved.