GridMailCommunicationSpi (GridGain 2.0.3 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

GridGain™ 2.0.3
Java API Specification

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

java.lang.Object
  org.gridgain.grid.spi.GridSpiAdapter
      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
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.

The following configuration parameters are mandatory:

Outgoing host (see GridMailCommunicationSpi.setOutHost(String)).
Ingoing host (see GridMailCommunicationSpi.setInHost(String)).
Address from (see GridMailCommunicationSpi.setFromAddress(String)).

The following configuration parameters are optional.

Outgoing connection type (see GridMailCommunicationSpi.setOutConnectionType(GridMailCommunicationType))
Outgoing port (see GridMailCommunicationSpi.setOutPort(int)
Outgoing user name (see GridMailCommunicationSpi.setOutUsername(String)
Outgoing user password (see GridMailCommunicationSpi.setOutPassword(String)
Outgoing additional JavaMail properties (see GridMailCommunicationSpi.setOutCustomProperties(Properties)
Outgoing protocol (see GridMailCommunicationSpi.setOutProtocol(GridMailCommunicationOutProtocol)
Ingoing connection type (see GridMailCommunicationSpi.setInConnectionType(GridMailCommunicationType)
Ingoing port (see GridMailCommunicationSpi.setInPort(int)
Ingoing user name (see GridMailCommunicationSpi.setInUsername(String)
Ingoing user password (see GridMailCommunicationSpi.setInPassword(String)
Ingoing additional JavaMail properties (see GridMailCommunicationSpi.setInCustomProperties(Properties)
Ingoing protocol (see GridMailCommunicationSpi.setInProtocol(GridMailCommunicationInProtocol)
Mail subject (see GridMailCommunicationSpi.setSubject(String)
Mail folder name (see GridMailCommunicationSpi.setFolderName(String)
Locally stored file name (see GridMailCommunicationSpi.setStoreFileName(String)
Read messages batch size (see GridMailCommunicationSpi.setReadBatchSize(int)
Delay between messages read (see GridMailCommunicationSpi.setReceiverDelay(long)
Number of milliseconds to leave messages on server (see GridMailCommunicationSpi.setLeaveMessagesOnServer(long)

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);

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

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
`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`	`onContextInitialized(GridSpiContext spiCtx)` Callback invoked when SPI context is initialized. SPI implementation may store SPI context for future access. This method is invoked after `GridSpi.spiStart(String)` method is completed, so SPI should be fully functional at this point. Use this method for post-start initialization, such as subscribing a discovery listener, sending a message to remote node, etc...
`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, checkConfigurationConsistency, configInfo, getAuthor, getGridGainHome, getLocalNodeId, getSpiContext, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, getVendorEmail, getVendorUrl, getVersion, onContextDestroyed, registerMBean, setSpiContext, startInfo, startStopwatch, stopInfo, unregisterMBean, warnSpi, warnSpiParameter`

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
`onContextDestroyed`

Methods inherited from interface org.gridgain.grid.spi.GridSpiManagementMBean
`getAuthor, getGridGainHome, getLocalNodeId, 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:

NONE
SSL
STARTTLS
null

Specified by:: getOutConnectionTypeFormatted in interface GridMailCommunicationSpiMBean

Returns:: Connection type.

getOutProtocolFormatted

public String getOutProtocolFormatted()

Gets outgoing mail protocol. Could be one of the following:

SMTP
SMTPS
null

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:

	Nikita Ivanov, GridGain Systems nivanov@gridgain.com
	Dmitriy Setrakyan, GridGain Systems dsetrakyan@gridgain.com
	Alexander Magdenko, GridGain Systems amagdenko@gridgain.com
	Boris Suchodoev, GridGain Systems bsuchodoev@gridgain.com
	Denis Kharlamov, GridGain Systems dkharlamov@gridgain.com
	close

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

Configuration

Mandatory

Optional

Java Example

Spring Example

DFLT_SUBJ

DFLT_STORE_FILE_NAME

DFLT_RECEIVER_DELAY

DFLT_LEAVE_MSGS_ON_SERVER

ATTR_EMAIL_ADDR

GridMailCommunicationSpi

getNodeAttributes

setOutHost

setOutConnectionType

setOutPort

setOutUsername

setOutPassword

setInHost

setInConnectionType

setInPort

setInUsername

setInPassword

setSubject

setFolderName

setFromAddress

setInCustomProperties

setOutCustomProperties

setReadBatchSize

setReceiverDelay

setOutProtocol

setInProtocol

setStoreFileName

setLeaveMessagesOnServer

getReceiverDelay

getLeaveMessagesOnServer

getOutConnectionTypeFormatted

getOutProtocolFormatted

getOutHost

getOutPort

getOutUsername

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