GridJmsCommunicationSpi (GridGain 2.1.0 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

GridGain™ 2.1.0
Java API Specification

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.gridgain.grid.spi.communication.jms
Class GridJmsCommunicationSpi

java.lang.Object
  org.gridgain.grid.spi.GridSpiAdapter
      org.gridgain.grid.spi.communication.jms.GridJmsCommunicationSpi

All Implemented Interfaces:: GridCommunicationSpi, GridJmsCommunicationSpiMBean, GridSpi, GridSpiManagementMBean

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

JMS implementation of GridCommunicationSpi. This implementation uses JMS topic and queue to send messages to an individual node or to a group of remote nodes.

Note that queue is optional. If provided, then queue will be used for sending messages to a single node (method GridJmsCommunicationSpi.sendMessage(GridNode, Serializable), otherwise topic will be used in which case messages will be sent to all nodes, but only destination node will process them and others will ignore them. Topic is always used for communication with more than one node (method GridJmsCommunicationSpi.sendMessage(Collection, Serializable). Both, topic and queue will be first obtained from JNDI lookup.

This SPI has no mandatory parameters. The following configuration parameters are optional:

JMS connection factory name (see GridJmsCommunicationSpi.setConnectionFactoryName(String))
JNDI environment (see GridJmsCommunicationSpi.setJndiEnvironment(Map))
JMS connection factory (see GridJmsCommunicationSpi.setConnectionFactory(ConnectionFactory))
Messages delivery mode (see GridJmsCommunicationSpi.setDeliveryMode(int))
Messages priority (see GridJmsCommunicationSpi.setPriority(int))
Time to live (see GridJmsCommunicationSpi.setTimeToLive(long))
Queue name (see GridJmsCommunicationSpi.setQueueName(String))
Queue (see GridJmsCommunicationSpi.setQueue(Queue))
Topic name (see GridJmsCommunicationSpi.setTopicName(String))
Topic (see GridJmsCommunicationSpi.setTopic(Topic))
Whether messages are transacted or not (see GridJmsCommunicationSpi.setTransacted(boolean))
User name (see GridJmsCommunicationSpi.setUser(String))
User password (see GridJmsCommunicationSpi.setPassword(String))

In order to use GridJmsCommunicationSpi it needs to be explicitely configured:

 GridJmsCommunicationSpi commSpi = new GridJmsCommunicationSpi();

 // JNDI connection factory name.
 commSpi.setConnectionFactoryName("java:ConnectionFactory");

 // JNDI environment mandatory parameter.
 Map<Object, Object> env = new Hashtable<Object, Object>(3);
 
 env.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");
 env.put(Context.PROVIDER_URL, "jnp://localhost:1099");
 env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming:org.jnp.interfaces");
 
 commSpi.setJndiEnvironment(env);
 
 // JNDI topic name.
 commSpi.setTopicName("topic/myjmstopic");
 
 GridConfigurationAdapter cfg = new GridConfigurationAdapter();

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

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

GridJmsCommunicationSpi 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.jms.GridJmsCommunicationSpi">
                 <property name="connectionFactoryName" value="java:ConnectionFactory"/>
                 <property name="topicName" value="topic/myjmstopic"/>
                 <property name="jndiEnvironment">
                     <map>
                         <entry>
                             <key><util:constant static-field="javax.naming.Context.INITIAL_CONTEXT_FACTORY"/></key>
                             <value>org.jnp.interfaces.NamingContextFactory</value>
                         </entry>
                         <entry>
                             <key><util:constant static-field="javax.naming.Context.PROVIDER_URL"/></key>
                             <value>jnp://localhost:1099</value>
                         </entry>
                         <entry>
                             <key><util:constant static-field="javax.naming.Context.URL_PKG_PREFIXES"/></key>
                             <value>org.jboss.naming:org.jnp.interfaces</value>
                         </entry>
                     </map>
                 </property>
             </bean>
         </property>
         ...
 </bean>

Note: JMS provider is not shipped with GridGain. If you don't have JMS, you need to download it separately. To download JMS provider see http://en.wikipedia.org/wiki/Java_Message_Service#JMS_Provider_Implementations for more details. Once installed, JMS provider should be available on the classpath for GridGain. If you use [GRIDGAIN_HOME]/bin/gridgain.{sh|bat} script to start a grid node you can simply add JMS JARs to [GRIDGAIN_HOME]/bin/setenv.{sh|bat} scripts that's used to set up class path for the main scripts.

This release of GridGain has been tested with:

JBossMQ 4.x
ActiveMQ 4.x
SunMQ 3.x

Note: When using JMS-based SPIs (communication or discovery) you cannot start multiple GridGain instances in the same VM due to possible limitations of JMS providers. GridGain runtime will detect this situation and prevent GridGain from starting in such case. See GridSpiMultipleInstancesSupport for details.

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_QUEUE_NAME` Name of the node attribute that refers to the queue name (value is `grid.jms.queue.GridJmsCommunicationSpi`).

Constructor Summary
`GridJmsCommunicationSpi()`

Method Summary
`javax.jms.ConnectionFactory`	`getConnectionFactory()` Returns JMS connection factory.
`String`	`getConnectionFactoryName()` Returns name of the JMS connection factory in JNDI tree.
`protected List<String>`	`getConsistentAttributeNames()` Returns back list of attributes that should be consistent for this SPI.
`int`	`getDeliveryMode()` Gets messages delivery mode.
`Map<Object,Object>`	`getJndiEnvironment()` Gets naming context variables which are used by node to establish JNDI tree connection.
`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`	`getPassword()` Gets JMS connection password for connectivity authentication.
`int`	`getPriority()` Gets messages delivery priority as defined in `Message`.
`javax.jms.Queue`	`getQueue()` Gets JMS queue.
`String`	`getQueueName()` Gets JNDI name for JMS queue.
`long`	`getTimeToLive()` Gets messages lifetime.
`javax.jms.Topic`	`getTopic()` Gets JMS topic.
`String`	`getTopicName()` Gets JNDI name of the JMS topic.
`String`	`getUser()` Gets JMS connection user name for connectivity authentication.
`boolean`	`isTransacted()` Indicates whether JMS messages are transacted or not.
`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`	`setConnectionFactory(javax.jms.ConnectionFactory factory)` Sets JMS connection factory.
`void`	`setConnectionFactoryName(String factoryName)` Sets the JNDI name of JMS connection factory.
`void`	`setDeliveryMode(int deliveryMode)` Sets message delivery mode.
`void`	`setJndiEnvironment(Map<Object,Object> jndiEnv)` Sets JNDI environment properties.
`void`	`setListener(GridMessageListener listener)` Set communication listener.
`void`	`setPassword(String pswd)` Sets password to establish connection with JMS server.
`void`	`setPriority(int priority)` Sets message delivery priority.
`void`	`setQueue(javax.jms.Queue queue)` Sets JMS queue.
`void`	`setQueueName(String qName)` Sets JNDI name for JMS queue.
`void`	`setTimeToLive(long ttl)` Sets message time-to-live (in milliseconds).
`void`	`setTopic(javax.jms.Topic topic)` Sets JMS topic.
`void`	`setTopicName(String tName)` Sets JNDI name for JMS topic.
`void`	`setTransacted(boolean transacted)` Indicates whether JMS messages are transacted or not.
`void`	`setUser(String user)` Sets user name which is used for connection establishing.
`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

ATTR_QUEUE_NAME

public static final String ATTR_QUEUE_NAME

Name of the node attribute that refers to the queue name (value is grid.jms.queue.GridJmsCommunicationSpi).

Constructor Detail

GridJmsCommunicationSpi

public GridJmsCommunicationSpi()

Method Detail

isTransacted

public boolean isTransacted()

Indicates whether JMS messages are transacted or not.

Specified by:: isTransacted in interface GridJmsCommunicationSpiMBean

Returns:: true if session supports transactions, otherwise false.

setTransacted

@GridSpiConfiguration(optional=true)
public void setTransacted(boolean transacted)

Indicates whether JMS messages are transacted or not. This configuration parameter is optional.

If not provided, default value is false.

Parameters:: transacted - If true then session will support transactions, otherwise it will not.

getDeliveryMode

public int getDeliveryMode()

Gets messages delivery mode.

Specified by:: getDeliveryMode in interface GridJmsCommunicationSpiMBean

Returns:: Either DeliveryMode.PERSISTENT or DeliveryMode.NON_PERSISTENT.

setDeliveryMode

@GridSpiConfiguration(optional=true)
public void setDeliveryMode(int deliveryMode)

Sets message delivery mode. This configuration parameter is optional.

If not provided, default value is Message.DEFAULT_DELIVERY_MODE.

Parameters:: deliveryMode - JMS delivery mode as defined in DeliveryMode.

getPriority

public int getPriority()

Gets messages delivery priority as defined in Message. The lower the faster.

Specified by:: getPriority in interface GridJmsCommunicationSpiMBean

Returns:: Message priority.

setPriority

@GridSpiConfiguration(optional=true)
public void setPriority(int priority)

Sets message delivery priority. This configuration parameter is optional.

If not provided, default value is Message.DEFAULT_PRIORITY.

Parameters:: priority - JMS message priority as defined in Message.

getTimeToLive

public long getTimeToLive()

Gets messages lifetime. Messages stays in the queue/topic until they run out of time.

Specified by:: getTimeToLive in interface GridJmsCommunicationSpiMBean

Returns:: Time-to-live value in milliseconds.

setTimeToLive

@GridSpiConfiguration(optional=true)
public void setTimeToLive(long ttl)

Sets message time-to-live (in milliseconds). This configuration parameter is optional.

If not provided, default value is Message.DEFAULT_TIME_TO_LIVE.

Parameters:: ttl - Message time-to-live value.

getQueueName

public String getQueueName()

Gets JNDI name for JMS queue. If provided, then queue will be used for node-to-node communication otherwise topic will be used.

Specified by:: getQueueName in interface GridJmsCommunicationSpiMBean

Returns:: Name of the queue in JNDI tree.

setQueueName

@GridSpiConfiguration(optional=true)
public void setQueueName(String qName)

Sets JNDI name for JMS queue. If provided, then queue will be used for node-to-node communication (method GridJmsCommunicationSpi.sendMessage(GridNode, Serializable)), otherwise topic will be used. This configuration parameter is optional.

If not provided, default value is null.

Parameters:: qName - Name of JMS queue.

getQueue

public javax.jms.Queue getQueue()

Gets JMS queue. If provided, then queue will be used for node-to-node communication otherwise topic will be used.

Specified by:: getQueue in interface GridJmsCommunicationSpiMBean

Returns:: JMS queue.

setQueue

@GridSpiConfiguration(optional=true)
public void setQueue(javax.jms.Queue queue)

Sets JMS queue. If provided, then queue will be used for node-to-node communication (method GridJmsCommunicationSpi.sendMessage(GridNode, Serializable)), otherwise topic will be used. This configuration parameter is optional.

If not provided, default value is null.

Parameters:: queue - JMS queue.

getTopicName

public String getTopicName()

Gets JNDI name of the JMS topic.

Specified by:: getTopicName in interface GridJmsCommunicationSpiMBean

Returns:: Name of JMS topic in JNDI tree.

setTopicName

@GridSpiConfiguration(optional=true)
public void setTopicName(String tName)

Sets JNDI name for JMS topic. This configuration parameter is optional but ether topic name or topic must be set.

There is no default value.

Parameters:: tName - JMS topic name.

getTopic

public javax.jms.Topic getTopic()

Gets JMS topic.

Specified by:: getTopic in interface GridJmsCommunicationSpiMBean

Returns:: JMS topic.

setTopic

@GridSpiConfiguration(optional=true)
public void setTopic(javax.jms.Topic topic)

Sets JMS topic. This configuration parameter is optional but ether topic name or topic must be set.

There is no default value.

Parameters:: topic - JMS topic name.

getConnectionFactoryName

public String getConnectionFactoryName()

Returns name of the JMS connection factory in JNDI tree.

Specified by:: getConnectionFactoryName in interface GridJmsCommunicationSpiMBean

Returns:: Connection factory name.

setConnectionFactoryName

@GridSpiConfiguration(optional=true)
public void setConnectionFactoryName(String factoryName)

Sets the JNDI name of JMS connection factory. This configuration parameter is optional but either connection factory name and JNDI environment or connection factory must be set.

There is no default value.

Parameters:: factoryName - JMS connection factory name.

getConnectionFactory

public javax.jms.ConnectionFactory getConnectionFactory()

Returns JMS connection factory.

Specified by:: getConnectionFactory in interface GridJmsCommunicationSpiMBean

Returns:: Connection factory.

setConnectionFactory

@GridSpiConfiguration(optional=true)
public void setConnectionFactory(javax.jms.ConnectionFactory factory)

Sets JMS connection factory. This configuration parameter is optional but either connection factory name and JNDI environment or connection factory must be set.

There is no default value.

Parameters:: factory - JMS connection factory.

getUser

public String getUser()

Gets JMS connection user name for connectivity authentication.

Specified by:: getUser in interface GridJmsCommunicationSpiMBean

Returns:: Name of the user.

setUser

@GridSpiConfiguration(optional=true)
public void setUser(String user)

Sets user name which is used for connection establishing. Username with null value means that no authentication will be used. This configuration parameter is optional.

If not provided, default value is null.

Parameters:: user - JMS connection username.

getJndiEnvironment

public Map<Object,Object> getJndiEnvironment()

Gets naming context variables which are used by node to establish JNDI tree connection.

Specified by:: getJndiEnvironment in interface GridJmsCommunicationSpiMBean

Returns:: Map of JNDI environment variables.

setJndiEnvironment

@GridSpiConfiguration(optional=true)
public void setJndiEnvironment(Map<Object,Object> jndiEnv)

Sets JNDI environment properties. For example for JBoss the following environment parameters are required:

There is no default value.

Parameters:: jndiEnv - Map of naming context variables.

getPassword

public String getPassword()

Gets JMS connection password for connectivity authentication.

Specified by:: getPassword in interface GridJmsCommunicationSpiMBean

Returns:: User password.

setPassword

@GridSpiConfiguration(optional=true)
public void setPassword(String pswd)

Sets password to establish connection with JMS server. This configuration parameter is optional.

If not provided, default value is null.

Parameters:: pswd - JMS connection password.

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.

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.

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.

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.

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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

GridGain™ 2.1.0
Java API Specification

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

	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.jms Class GridJmsCommunicationSpi

Configuration

Mandatory

Optional

Java Example

Spring Example

ATTR_QUEUE_NAME

GridJmsCommunicationSpi

isTransacted

setTransacted

getDeliveryMode

setDeliveryMode

getPriority

setPriority

getTimeToLive

setTimeToLive

getQueueName

setQueueName

getQueue

setQueue

getTopicName

setTopicName

getTopic

setTopic

getConnectionFactoryName

setConnectionFactoryName

getConnectionFactory

setConnectionFactory

getUser

setUser

getJndiEnvironment

setJndiEnvironment

getPassword

setPassword

getNodeAttributes

spiStart

spiStop

setListener

sendMessage

sendMessage

getConsistentAttributeNames

toString

org.gridgain.grid.spi.communication.jms
Class GridJmsCommunicationSpi