org.gridgain.grid.spi.discovery.jms
Class GridJmsDiscoverySpi

java.lang.Object
  org.gridgain.grid.spi.GridSpiAdapter
      org.gridgain.grid.spi.discovery.jms.GridJmsDiscoverySpi

All Implemented Interfaces:

GridDiscoverySpi, GridJmsDiscoverySpiMBean, GridSpi, GridSpiManagementMBean

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

JMS implementation of GridDiscoverySpi. This is a topic-based implementation. Each node periodically sends JOIN_GRID heartbeat message to notify the others that it's still alive. When node leaves cluster it sends LEAVE_GRID message.

Configuration

Mandatory

This SPI has no mandatory configuration parameters.

Optional

The following configuration parameters are optional:

• JNDI environment (see GridJmsDiscoverySpi.setJndiEnvironment(Map))
• JMS connection factory name (see GridJmsDiscoverySpi.setConnectionFactoryName(String))
• JMS connection factory (see GridJmsDiscoverySpi.setConnectionFactory(ConnectionFactory))
• User name (see GridJmsDiscoverySpi.setUser(String))
• User password (see GridJmsDiscoverySpi.setPassword(String))
• Heartbeat messages frequency (see GridJmsDiscoverySpi.setHeartbeatFrequency(long))
• Maximum number of handshake threads (see GridJmsDiscoverySpi.setMaximumHandshakeThreads(int))
• Number of missed heartbeat messages (see GridJmsDiscoverySpi.setMaximumMissedHeartbeats(long))
• Time to live (see GridJmsDiscoverySpi.setTimeToLive(long))
• Handshake timeout (see GridJmsDiscoverySpi.setHandshakeWaitTime(long))
• Ping timeout (see GridJmsDiscoverySpi.setPingWaitTime(long))
• Topic name (see GridJmsDiscoverySpi.setTopicName(String))
• Topic (see GridJmsDiscoverySpi.setTopic(Topic))

Java Example

GridJmsDiscoverySpi needs to be explicitly configured to override default Multicast discovery SPI.

 GridJmsDiscoverySpi spi = new GridJmsDiscoverySpi();

 // JNDI connection factory name.
 spi.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: * *");
 env.put(Context.URL_PKG_PREFIXES, "org.jboss.naming:org.jnp.interfaces");

 spi.setJndiEnvironment(env);

 // JNDI topic name.
 spi.setTopicName("topic/myjmstopic");

 GridConfigurationAdapter cfg = new GridConfigurationAdapter();

 // Override default discovery SPI.
 cfg.setDiscoverySpi(spi);

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

Spring Example

GridJmsDiscoverySpi can be configured from Spring XML configuration file:

 <bean id="grid.custom.cfg" class="org.gridgain.grid.GridConfigurationAdapter" singleton="true">
         ...
         <property name="discoverySpi">
             <bean class="org.gridgain.grid.spi.discovery.jms.GridJmsDiscoverySpi">
                 <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

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

	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

See Also:

GridDiscoverySpi

Field Summary

static String

NODE_SELECTOR Node selector to filter out messages for the others (value is node).

Constructor Summary

GridJmsDiscoverySpi()

Method Summary

javax.jms.ConnectionFactory	getConnectionFactory() Returns JMS connection factory.
String	getConnectionFactoryName() Returns name of the JMS connection factory in JNDI tree that is used for establishing connections by discovery SPI.
int	getHandshakeActiveThreadCount() Returns the approximate number of threads that are actively processing handshake tasks.
int	getHandshakeCorePoolSize() Returns the core number of handshake threads.
int	getHandshakeLargestPoolSize() Returns the largest number of handshake threads that have ever simultaneously been in the pool.
int	getHandshakeMaximumPoolSize() Returns the maximum allowed number of handshake threads.
int	getHandshakePoolSize() Returns the current number of handshake threads in the pool.
int	getHandshakeQueueSize() Gets current size of the handshake queue size.
long	getHandshakeTotalCompletedCount() Returns the approximate total number of handshakes that have completed execution.
long	getHandshakeTotalScheduledCount() Returns the approximate total number of handshake tasks that have been scheduled for execution.
long	getHandshakeWaitTime() Returns timeout value for attributes handshake.
long	getHeartbeatFrequency() Returns interval for heartbeat messages.
Map<Object,Object>	getJndiEnvironment() Returns naming context variables which are used by node to establish JNDI tree connection.
GridNode	getLocalNode() Gets local node.
int	getMaximumHandshakeThreads() Returns maximum number of handshake threads.
long	getMaximumMissedHeartbeats() Returns numbers of heartbeat messages that could be missed before node is considered to be failed.
GridNode	getNode(UUID nodeId) Gets node by ID.
long	getPingWaitTime() Returns timeout value for ping request.
int	getRemoteNodeCount() Returns number of remote nodes.
Collection<UUID>	getRemoteNodeIds() Returns set of discovered remote nodes IDs.
List<GridNode>	getRemoteNodes() Gets collection of remote nodes in grid or empty collection if no remote nodes found.
long	getTimeToLive() Returns JMS time to live value for messages.
javax.jms.Topic	getTopic() Returns JMS topic for broadcasting messages to all discovered nodes.
String	getTopicName() Returns JMS topic name for broadcasting messages to all discovered nodes.
String	getUser() Returns username to connect to JNDI.
boolean	pingNode(UUID nodeId) Pings the remote node to see if it's alive.
void	setConnectionFactory(javax.jms.ConnectionFactory factory) Sets JMS connection factory.
void	setConnectionFactoryName(String factoryName) Sets name of the connection factory in the JNDI tree of application server which node will use to create new JMS connection.
void	setHandshakeWaitTime(long handshakeWaitTime) Sets handshake timeout.
void	setHeartbeatFrequency(long beatFreq) Sets interval for sending heartbeat requests.
void	setJndiEnvironment(Map<Object,Object> jndiEnv) Sets JNDI environment.
void	setListener(GridDiscoveryListener listener) Sets a listener for discovery events.
void	setMaximumHandshakeThreads(int maxHandshakeThreads) Sets maximum number of handshake threads.
void	setMaximumMissedHeartbeats(long maxMissedHeartbeats) Sets number of heartbeat requests that could be missed until remote node becomes unavailable.
void	setMetricsProvider(GridDiscoveryMetricsProvider metricsProvider) Sets discovery metrics provider.
void	setNodeAttributes(Map<String,Serializable> attrs) Sets node attributes which will be distributed in grid during join process.
void	setPassword(String pswd) Sets password to establish connection with JMS server.
void	setPingWaitTime(long pingWaitTime) Sets ping request timeout.
void	setTimeToLive(long ttl) Sets message's lifetime (in milliseconds).
void	setTopic(javax.jms.Topic topic) Sets JMS topic.
void	setTopicName(String topicName) Sets name of the topic.
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, getConsistentAttributeNames, getGridGainHome, getLocalNodeId, getName, getNodeAttributes, 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, getNodeAttributes, onContextDestroyed, onContextInitialized

Methods inherited from interface org.gridgain.grid.spi.GridSpiManagementMBean

getAuthor, getGridGainHome, getLocalNodeId, getName, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, getVendorEmail, getVendorUrl, getVersion

Field Detail

NODE_SELECTOR

public static final String NODE_SELECTOR

Node selector to filter out messages for the others (value is node).

See Also:

Constant Field Values

Constructor Detail

GridJmsDiscoverySpi

public GridJmsDiscoverySpi()

Method Detail

getUser

public String getUser()

Returns username to connect to JNDI.

Specified by:

getUser in interface GridJmsDiscoverySpiMBean

Returns:

Name of the user. If not set, null is returned.

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 - Name of the user.

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 - Password.

getHeartbeatFrequency

public long getHeartbeatFrequency()

Returns interval for heartbeat messages.

Specified by:

getHeartbeatFrequency in interface GridJmsDiscoverySpiMBean

Returns:

Time in milliseconds.

setHeartbeatFrequency

@GridSpiConfiguration(optional=true)
public void setHeartbeatFrequency(long beatFreq)

Sets interval for sending heartbeat requests. This configuration parameter is optional.

If not provided, default value is GridJmsDiscoveryConfiguration.DFLT_HEARTBEAT_FREQ.

Parameters:

beatFreq - time in milliseconds.

getMaximumMissedHeartbeats

public long getMaximumMissedHeartbeats()

Returns numbers of heartbeat messages that could be missed before node is considered to be failed.

Specified by:

getMaximumMissedHeartbeats in interface GridJmsDiscoverySpiMBean

Returns:

Number of heartbeat messages.

setMaximumMissedHeartbeats

@GridSpiConfiguration(optional=true)
public void setMaximumMissedHeartbeats(long maxMissedHeartbeats)

Sets number of heartbeat requests that could be missed until remote node becomes unavailable. This configuration parameter is optional.

If not provided, default value is GridJmsDiscoveryConfiguration.DFLT_MAX_MISSED_HEARTBEATS.

Parameters:

maxMissedHeartbeats - number of requests.

getTimeToLive

public long getTimeToLive()

Returns JMS time to live value for messages.

Specified by:

getTimeToLive in interface GridJmsDiscoverySpiMBean

Returns:

Time-to-live value in milliseconds.

setTimeToLive

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

Sets message's lifetime (in milliseconds). This configuration parameter is optional.

If not provided, default value is GridJmsDiscoveryConfiguration.DFLT_TIME_TO_LIVE.

Parameters:

ttl - New time-to-live value.

getPingWaitTime

public long getPingWaitTime()

Returns timeout value for ping request.

Specified by:

getPingWaitTime in interface GridJmsDiscoverySpiMBean

Returns:

Time in milliseconds.

setHandshakeWaitTime

@GridSpiConfiguration(optional=true)
public void setHandshakeWaitTime(long handshakeWaitTime)

Sets handshake timeout. When node gets heartbeat from remote node it asks for the attributes. If remote node does not send them back and this time is out remote node would not be added in grid. This configuration parameter is optional.

If not provided, default value is GridJmsDiscoveryConfiguration.DFLT_HANDSHAKE_WAIT_TIME.

Parameters:

handshakeWaitTime - time in milliseconds.

getHandshakeWaitTime

public long getHandshakeWaitTime()

Returns timeout value for attributes handshake.

Specified by:

getHandshakeWaitTime in interface GridJmsDiscoverySpiMBean

Returns:

Time in milliseconds.

setMaximumHandshakeThreads

@GridSpiConfiguration(optional=true)
public void setMaximumHandshakeThreads(int maxHandshakeThreads)

Sets maximum number of handshake threads. This means maximum number of handshakes that can be executed in parallel. This configuration parameter is optional.

Note that if you expect a lot of nodes discovered each other in parallel you should better set higher value. After discovery number of unused threads will be shrank to 1. Typically two nodes that discover each other require one thread.

If not provided, default value is GridJmsDiscoveryConfiguration.DFLT_MAX_HANDSHAKE_THREADS.

Parameters:

maxHandshakeThreads - maximum number of handshake threads.

getMaximumHandshakeThreads

public int getMaximumHandshakeThreads()

Returns maximum number of handshake threads. This means maximum number of handshakes that can be executed in parallel.

Note that if you expect a lot of nodes discovered each other in parallel you should better set higher value. After discovery number of unused threads will be shrank to 1. Typically two nodes that discover each other require one thread.

Specified by:

getMaximumHandshakeThreads in interface GridJmsDiscoverySpiMBean

Returns:

Maximum number of handshake threads.

getHandshakeActiveThreadCount

public int getHandshakeActiveThreadCount()

Returns the approximate number of threads that are actively processing handshake tasks.

Specified by:

getHandshakeActiveThreadCount in interface GridJmsDiscoverySpiMBean

Returns:

Approximate number of threads that are actively processing handshake tasks.

getHandshakeTotalCompletedCount

public long getHandshakeTotalCompletedCount()

Returns the approximate total number of handshakes that have completed execution.

Specified by:

getHandshakeTotalCompletedCount in interface GridJmsDiscoverySpiMBean

Returns:

Approximate total number of handshakes that have completed execution.

getHandshakeQueueSize

public int getHandshakeQueueSize()

Gets current size of the handshake queue size. Handshake queue keeps handshake tasks when there are not threads available for processing in the pool.

Specified by:

getHandshakeQueueSize in interface GridJmsDiscoverySpiMBean

Returns:

Current size of the handshake queue size.

getHandshakeCorePoolSize

public int getHandshakeCorePoolSize()

Returns the core number of handshake threads.

Specified by:

getHandshakeCorePoolSize in interface GridJmsDiscoverySpiMBean

Returns:

Core number of handshake threads.

getHandshakeLargestPoolSize

public int getHandshakeLargestPoolSize()

Returns the largest number of handshake threads that have ever simultaneously been in the pool.

Specified by:

getHandshakeLargestPoolSize in interface GridJmsDiscoverySpiMBean

Returns:

Largest number of handshake threads that have ever simultaneously been in the pool.

getHandshakeMaximumPoolSize

public int getHandshakeMaximumPoolSize()

Returns the maximum allowed number of handshake threads.

Specified by:

getHandshakeMaximumPoolSize in interface GridJmsDiscoverySpiMBean

Returns:

Maximum allowed number of handshake threads.

getHandshakePoolSize

public int getHandshakePoolSize()

Returns the current number of handshake threads in the pool.

Specified by:

getHandshakePoolSize in interface GridJmsDiscoverySpiMBean

Returns:

Current number of handshake threads in the pool.

getHandshakeTotalScheduledCount

public long getHandshakeTotalScheduledCount()

Returns the approximate total number of handshake tasks that have been scheduled for execution.

Specified by:

getHandshakeTotalScheduledCount in interface GridJmsDiscoverySpiMBean

Returns:

Approximate total number of handshake tasks that have been scheduled for execution.

setPingWaitTime

@GridSpiConfiguration(optional=true)
public void setPingWaitTime(long pingWaitTime)

Sets ping request timeout. When ping request is run out of this time remote node is considered to be failed. This configuration parameter is optional.

If not provided, default value is GridJmsDiscoveryConfiguration.DFLT_PING_WAIT_TIME.

Parameters:

pingWaitTime - time in milliseconds.

getJndiEnvironment

public Map<Object,Object> getJndiEnvironment()

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

Specified by:

getJndiEnvironment in interface GridJmsDiscoverySpiMBean

Returns:

Map of JNDI environment variables.

See Also:

Context

setJndiEnvironment

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

Sets JNDI environment. Various JMS providers will require different JMS environment properties. Refer to corresponding JMS provider documentation for more information. This configuration parameter is mandatory.

Parameters:

jndiEnv - map of naming context variables.

getConnectionFactoryName

public String getConnectionFactoryName()

Returns name of the JMS connection factory in JNDI tree that is used for establishing connections by discovery SPI.

Specified by:

getConnectionFactoryName in interface GridJmsDiscoverySpiMBean

Returns:

Connection factory name. If not set, null is returned.

setConnectionFactoryName

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

Sets name of the connection factory in the JNDI tree of application server which node will use to create new JMS connection. This configuration parameter is optional but either connection factory name and JNDI environment or connection factory must be set.

Parameters:

factoryName - Connection factory name.

getConnectionFactory

public javax.jms.ConnectionFactory getConnectionFactory()

Returns JMS connection factory.

Specified by:

getConnectionFactory in interface GridJmsDiscoverySpiMBean

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.

getTopicName

public String getTopicName()

Returns JMS topic name for broadcasting messages to all discovered nodes.

Specified by:

getTopicName in interface GridJmsDiscoverySpiMBean

Returns:

Name of the topic in JNDI tree.

setTopicName

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

Sets name of the topic. Node uses this topic to communicate with other nodes by sending broadcast/private messages. This configuration parameter is optional.

If not provided, default value is GridJmsDiscoveryConfiguration.DFLT_TOPIC_NAME.

Parameters:

topicName - Name of the topic.

getTopic

public javax.jms.Topic getTopic()

Returns JMS topic for broadcasting messages to all discovered nodes.

Specified by:

getTopic in interface GridJmsDiscoverySpiMBean

Returns:

JMS topic.

setTopic

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

Sets JMS topic. This configuration parameter is optional.

There is no default value.

Parameters:

topic - JMS topic name.

setNodeAttributes

public void setNodeAttributes(Map<String,Serializable> attrs)

Sets node attributes which will be distributed in grid during join process. Note that these attributes cannot be changed and set only once.

Specified by:

setNodeAttributes in interface GridDiscoverySpi

Parameters:

attrs - Map of node attributes.

setListener

public void setListener(GridDiscoveryListener listener)

Sets a listener for discovery events. Refer to GridDiscoveryEventType for a set of all possible discovery events.

Specified by:

setListener in interface GridDiscoverySpi

Parameters:

listener - Listener to discovery events.

setMetricsProvider

public void setMetricsProvider(GridDiscoveryMetricsProvider metricsProvider)

Sets discovery metrics provider. Use metrics provided by GridDiscoveryMetricsProvider.getMetrics() method to exchange dynamic metrics between nodes.

Specified by:

setMetricsProvider in interface GridDiscoverySpi

Parameters:

metricsProvider - Provider of metrics data.

getLocalNode

public GridNode getLocalNode()

Gets local node.

Specified by:

getLocalNode in interface GridDiscoverySpi

Returns:

Local node.

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

Description copied from interface: GridSpi

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 if management bean could not be unregistered.

getRemoteNodes

public List<GridNode> getRemoteNodes()

Gets collection of remote nodes in grid or empty collection if no remote nodes found.

Specified by:

getRemoteNodes in interface GridDiscoverySpi

Returns:

Collection of remote nodes.

getNode

public GridNode getNode(UUID nodeId)

Gets node by ID.

Specified by:

getNode in interface GridDiscoverySpi

Parameters:

nodeId - Node ID.

Returns:

Node with given ID or null if node is not found.

getRemoteNodeIds

public Collection<UUID> getRemoteNodeIds()

Returns set of discovered remote nodes IDs.

Specified by:

getRemoteNodeIds in interface GridJmsDiscoverySpiMBean

Returns:

Set of remote nodes IDs.

getRemoteNodeCount

public int getRemoteNodeCount()

Returns number of remote nodes.

Specified by:

getRemoteNodeCount in interface GridJmsDiscoverySpiMBean

Returns:

Number of remote nodes.

pingNode

public boolean pingNode(UUID nodeId)

Pings the remote node to see if it's alive.

Specified by:

pingNode in interface GridDiscoverySpi

Parameters:

nodeId - Node Id.

Returns:

true if node alive, false otherwise.

toString

public String toString()

Overrides:

toString in class Object