org.gridgain.grid.spi.loadbalancing.coherence
Class GridCoherenceLoadBalancingSpi

java.lang.Object
  org.gridgain.grid.spi.GridSpiAdapter
      org.gridgain.grid.spi.loadbalancing.coherence.GridCoherenceLoadBalancingSpi

All Implemented Interfaces:

GridSpi, GridSpiManagementMBean, GridCoherenceLoadBalancingSpiMBean, GridLoadBalancingSpi

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

Load balancing SPI which uses data affinity for routing jobs to remote nodes. It provides ability to collocate computations with data. Coherence Cache provides partitioned cache feature which allows you to segment your cached data across cluster. This SPI delegates to Coherence Cache to find out which node is responsible for caching data and routes a job to it.

Note, that instead of regular GridJob, this SPI expects GridCoherenceAffinityJob which allows user to specify affinity key and cache name.

Coding Example

To use load balancers for your job routing, in your GridTask.map(List, Object) implementation use load balancer to find out the node this job should be routed to (see GridLoadBalancerResource documentation for information on how a load balancer can be injected into your task). However, the preferred way here is to use GridTaskSplitAdapter, as it will handle affinity assignment of jobs to nodes automatically. Node that when working with affinity load balancing, your task's map(..) or split(..) methods should return GridCoherenceAffinityJob instances instead of GridJob ones. GridCoherenceAffinityJob adds two additional methods to grid job: GridCoherenceAffinityJob.getAffinityKey() and GridCoherenceAffinityJob.getCacheName() which will allow GridGain to delegate routing to Coherence Cache, so jobs for the same cache with the same key will be always routed to the same node. In case if regular GridJob is returned, not the GridCoherenceAffinityJob, it will be routed to a randomly picked node.

Here is an example of a grid task that uses affinity load balancing. Note how load balancing jobs is absolutely transparent to the user and is simply a matter of proper grid configuration.

 public class MyFooBarCoherenceAffinityTask extends GridTaskSplitAdapter<List<Integer>,Object> {
     // For this example we receive a list of cache keys and for every key
     // create a job that accesses it.
     @Override
     protected Collection<? extends GridJob> split(int gridSize, List<Integer> cacheKeys) throws GridException {
         List<MyGridAffinityJob> jobs = new ArrayList<MyGridAffinityJob>(gridSize);

         for (Integer cacheKey : cacheKeys) {
             jobs.add(new MyFooBarCoherenceAffinityJob(cacheKey));
         }

         // Node assignment via load balancer
         // happens automatically.
         return jobs;
     }
     ...
 }
 

Here is the example of grid jobs created by the task above:

 public class MyFooBarCoherenceAffinityJob extends GridCoherenceAffinityJobAdapter<Integer, Serializable> {
    ...
    private static final String CACHE_NAME = "myDistributedCache";

    public MyFooBarCoherenceAffinityJob(Integer cacheKey) {
        super(CACHE_NAME, cacheKey);
    }

    public Serializable execute() throws GridException {
        ...
        // Access data by the same key returned in 'getAffinityKey()' method
        // and for cache with name returned in 'getCacheName()'.
        NamedCache mycache = CacheFactory.getCache(getCacheName);

        mycache.get(getAffinityKey());
        ...
    }
 }
 

Configuration

Mandatory

This SPI has no mandatory configuration parameters.

Optional

This SPI has no optional configuration parameters.

Below is a Java example of configuration for Coherence affinity load balancing SPI:

 GridCoherenceLoadBalancingSpi spi = new GridCoherenceLoadBalancingSpi();

 GridConfigurationAdapter cfg = new GridConfigurationAdapter();

 // Override default load balancing SPI.
 cfg.setLoadBalancingSpi(spi);

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

Here is Spring XML configuration example:

 <property name="loadBalancingSpi">
     <bean class="org.gridgain.grid.spi.loadbalancing.coherence.GridCoherenceLoadBalancingSpi"/>
 </property>
 

For more information, how to create and use Coherence distributed cache see Partitioned Cache Service

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

	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

Constructor Summary

GridCoherenceLoadBalancingSpi()

Method Summary

GridNode	getBalancedNode(GridTaskSession ses, List<GridNode> top, GridJob job) Gets balanced node for specified job within given task session.
void	onContextDestroyed() Callback invoked prior to stopping grid before SPI context is destroyed. Once this method is complete, grid will begin shutdown sequence. Use this callback for de-initialization logic that may involve SPI context. Note that invoking SPI context after this callback is complete is considered illegal and may produce unknown results. If GridSpiAdapter is used for SPI implementation, then it will replace actual context with dummy no-op context which is usually good-enough since grid is about to shut down.
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	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, getNodeAttributes, getSpiContext, getStartTimestamp, getStartTimestampFormatted, getUpTime, getUpTimeFormatted, getVendorEmail, getVendorUrl, getVersion, 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

getNodeAttributes

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

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

Constructor Detail

GridCoherenceLoadBalancingSpi

public GridCoherenceLoadBalancingSpi()

Method Detail

spiStart

public void spiStart(@Nullable
                     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.

onContextInitialized

public void onContextInitialized(GridSpiContext spiCtx)
                          throws GridSpiException

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

Specified by:

onContextInitialized in interface GridSpi

Overrides:

onContextInitialized in class GridSpiAdapter

Throws:

GridSpiException - If context initialization failed (grid will be stopped).

Parameters:

spiCtx - Spi context.

onContextDestroyed

public void onContextDestroyed()

Callback invoked prior to stopping grid before SPI context is destroyed. Once this method is complete, grid will begin shutdown sequence. Use this callback for de-initialization logic that may involve SPI context. Note that invoking SPI context after this callback is complete is considered illegal and may produce unknown results.

If GridSpiAdapter is used for SPI implementation, then it will replace actual context with dummy no-op context which is usually good-enough since grid is about to shut down.

Specified by:

onContextDestroyed in interface GridSpi

Overrides:

onContextDestroyed in class GridSpiAdapter

getBalancedNode

public GridNode getBalancedNode(GridTaskSession ses,
                                List<GridNode> top,
                                GridJob job)
                         throws GridException

Gets balanced node for specified job within given task session.

Specified by:

getBalancedNode in interface GridLoadBalancingSpi

Throws:

GridException - If failed to get next balanced node.

Parameters:

ses - Grid task session for currently executing task.

top - Topology of task nodes from which to pick the best balanced node for given job.

job - Job for which to pick the best balanced node.

Returns:

Best balanced node for the given job within given task session.

toString

public String toString()

Overrides:

toString in class Object