Dashboard > GridGain User Guide > Table Of Contents > Configuration And Startup > Grid Configuration
GridGain User Guide
Grid Configuration
Added by link, last edited by morpheus on Oct 08, 2009  (view change)
Labels: 
(None)


Click on Javadoc link to open Javadoc documentation.

Package

org.gridgain.grid Javadoc

Description

GridConfiguration Javadoc interface defines grid runtime configuration. This configuration is passed to GridFactory.start(GridConfiguration) Javadoc method. It defines all configuration parameters required to start a grid instance. Usually, a special class called "loader" will create an instance of this interface and call GridFactory.start(GridConfiguration) Javadoc method to initialize GridGain instance.

Note, that absolutely every configuration property in GridConfiguration Javadoc is optional. You can simply create a new instance of GridConfigurationAdapter Javadoc , for example, and pass it to GridFactory.start(GridConfiguration) Javadoc as is to start grid with default configuration. See GridFactory Javadoc documentation for information about default configuration properties used and more information on how to start grid.

The following configuration parameters can be used to configure grid node with GridConfigurationAdapter:

Setter Method Description Optional Default
setGridName(String) Javadoc Grid name. Yes null
setUserAttributes(Map<String,? extends Serializable>) Javadoc User specific attributes to attach to this node. Available via GridNode.getAttribute(String) Javadoc method. Very useful for segmenting grid nodes into subgroups or identifying nodes based on certain property. Yes All System Properties and Environment Variables are set as node attributes automatically by GridGain.
setGridLogger(GridLogger) Javadoc Logger to use within grid. Yes GridLog4jLogger Javadoc
setMarshaller(GridMarshaller) Javadoc Marshaller to use for serialization/deserialization of objects.
(available from ver. 2.1)		 Yes GridJbossMarshaller Javadoc
setDeploymentMode(GridDeploymentMode) Javadoc Deployment mode for task/query requests initiated from this node.
(available from ver. 2.1)		 Yes ISOLATED Javadoc
setPeerClassLoadingEnabled(boolean) Javadoc Enables/disables peer class loading. Yes true
setPeerClassLoadingTimeout(long) Javadoc Specifies timeout for peer-class-loading requests in milliseconds.
(available from ver. 2.1) 		Yes 2000ms
setPeerClassLoadingMissedResourcesCacheSize(int) Javadoc Specifies internal cache size for missed resources. If attempt to load a resource failed, then it will be cached, and following attempts will not make remote calls.
(available from ver. 2.1) 		Yes 200
setP2PLocalClassPathExclude(List<String>) Javadoc List of packages in a system class path that should be to P2P loaded even if they exist locally. Yes null
setMetricsExpireTime(long) Javadoc Time in milliseconds after which a certain metric value is considered expired. Yes 0, which means that metrics don't expire.
setMetricsHistorySize(int) Javadoc Number of metrics kept in history to compute totals and averages. Yes 0, which means to use system default of 10,000
setExecutorService(ExecutorService) Javadoc Thread pool to use mainly for task and job execution. Yes GridThreadPoolExecutorService Javadoc with 100 threads.
setSystemExecutorService(ExecutorService) Javadoc Thread pool to use for processing job and task session asynchronous responses.
(available from ver. 2.1) 		Yes GridThreadPoolExecutorService Javadoc with 5 threads.
setPeerClassLoadingExecutorService(ExecutorService) Javadoc Thread pool to use for processing peer class loading requests and responses.
(available from ver. 2.1) 		Yes GridThreadPoolExecutorService Javadoc with 20 threads.
setMBeanServer(MBeanServer) Javadoc MBean server for exposing GridGain MBeans. Yes The default MBean Server provided by JDK.
setLoadBalancingSpi(GridLoadBalancingSpi) Javadoc Fully configured instance of GridLoadBalancingSpi.
Starting with GridGain 2.1 you can provide multiple instances of Load Balancing SPIs and then specify which one to use on per-task level via @GridTaskSpis Javadoc annotation attached to your GridTask implementaiton. 		Yes GridRoundRobinLoadBalancingSpi
setCheckpointSpi(GridCheckpointSpi) Javadoc Fully configured instance of GridCheckpointSpi.
Starting with GridGain 2.1 you can provide multiple instances of Checkpoint SPIs and then specify which one to use on per-task level via @GridTaskSpis Javadoc annotation attached to your GridTask implementaiton. 		Yes GridSharedFsCheckpointSPI
setCollisionSpi(GridCollisionSpi) Javadoc Fully configured instance of GridCollisionSpi. Yes GridFifoQueueCollisionSpi
setCommunicationSpi(GridCommunicationSpi) Javadoc Fully configured instance of GridCommunicationSpi. Yes GridTcpCommunicationSpi
setDeploymentSpi(GridDeploymentSpi) Javadoc Fully configured instance of GridDeploymentSpi. Yes GridLocalDeploymentSpi
setDiscoverySpi(GridDiscoverySpi) Javadoc Fully configured instance of GridDiscoverySpi. Yes GridMulticastDiscoverySpi
setEventStorageSpi(GridEventStorageSpi) Javadoc Fully configured instance of GridEventStorageSpi. Yes GridMemoryEventStorageSpi
setFailoverSpi(GridFailoverSpi) Javadoc Fully configured instance of GridFailoverSpi.
Starting with GridGain 2.1 you can provide multiple instances of Failover SPIs and then specify which one to use on per-task level via @GridTaskSpis Javadoc annotation attached to your GridTask implementaiton. 		Yes GridAlwaysFailoverSpi
setTopologySpi(GridTopologySpi) Javadoc Fully configured instance of GridTopologySpi.
Starting with GridGain 2.1 you can provide multiple instances of Topology SPIs and then specify which one to use on per-task level via @GridTaskSpis Javadoc annotation attached to your GridTask implementaiton.		 Yes GridBasicTopologySpi
setMetricsSpi(GridLocalMetricsSpi) Javadoc Fully configured instance of GridLocalMetricsSpi. Yes GridJdkLocalMetricsSpi
setTracingSpi(GridTracingSpi) Javadoc Fully configured instance of GridTracingSpi. Yes null

Some of the most commonly used configuration properties are explained in more detail below.

Grid Name

Use grid name configuration property whenever you would like to identify your grid by name. Usually, if you have only one grid node within your VM, you don't have to configure grid name explicitly and use the default no-name grid node. However, if you start multiple grid node instances in the same VM, say for unit testing or debugging, then properly configuring grid name for every grid node instance will allow you to access multiple grid nodes by name via GridFactory.getGrid(String gridName) Javadoc method.

User Attributes

User attributes allow you to attach various custom attributes to your nodes. This attributes can then be used to identify node topology for your task execution or load balancing, segmenting your grid into multiple sub-grids, etc... By default, GridGain will automatically attach or System and Environment properties to your node.

You can query node attributes practically from anywhere in your code, be that your task or job logic, or implementation of topology or load-balacing SPI's. Simply get a handle on GridNode and check its attributes via GridNode.getAttribute(String) Javadoc method.

See GridNode Interface for examples on how to configure user node attributes.
See Segmenting Grid Nodes documentation for more information on how grid can be segmented.
See GridAttributesTopologySpi and GridNodeFilterTopologySpi documentation for information on how node attributes can be used for picking custom grid node topology for task execution.

Grid Logger

Configuring proper grid logger will allow you to integrate your logging with any environment. By default, GridLog4jLogger Javadoc is used which gets its logging configuration from GRIDGAIN_HOME/config/default-log4j.xml.

For information on how to inject loggers into your code refer to Logger Injection documentation.

Below is the list of supported loggers:

  • GridLog4jLogger Javadoc - Log4j-based implementation for logging. This logger should be used by loaders that have prefer log4j-based logging. By default, GridGain will use this logger with configuration from GRIDGAIN_HOME/config/default-log4j.xml.
  • GridJavaLogger Javadoc - Logger to use with Java logging. Implementation simply delegates to Java Logging.
  • GridJbossLogger Javadoc - Logger to use in JBoss loaders. Implementation simply delegates to JBoss logging.
  • GridJclLogger Javadoc - This logger wraps any JCL (Jakarta Commons Logging) loggers. Implementation simply delegates to underlying JCL logger. This logger should be used by loaders that have JCL-based internal logging (e.g., Websphere).

Grid Mashaller

Starting with GridGain 2.1 release you are able to configure different marshallers, and if needed provide your own. GridMarshaller Javadoc allows to marshal or unmarshal objects. It provides serialization/deserialization mechanism for all instances that are sent across network or are otherwise serialized.

For information on how to inject marshallers into your code refer to Marshaller Injection documentation.

Gridgain provides the following GridMarshaller implementations:

  • GridJBossMarshaller Javadoc - this is the default marshaller used by GridGain. It used JBoss implementation of java.io.ObjectOutputStream for object serialization. All marshalled instances must implement java.io.Serializable.
  • GridJdkMarshaller Javadoc - this marshaller uses standard JDK java.io.ObjectOutputStream for object serialization.. All marshalled instances must implement java.io.Serializable.
  • GridXstreamMarshaller Javadoc - this marshaller uses Codehaus XStream for serialization of objects into XML. It does not require that marshalled instances implement java.io.Serializable, however, it performs slower than other marshaller implementations as XML is a verbose protocol.

Deployment Mode

See Deployment Modes documentation for information about different deployment modes and how user-version is used.

Executor Services

Starting with version 2.1, GridGain exposes configuration for 3 threads pools:

  • ExecutorService Javadoc - Implementation of java.util.concurrent.ExecutorService to be used for task and job executions. By default, standard ThreadPoolExecutor thread pool is provided configured to use 100 threads. Change this configuration parameter whenever you need to change the number of threads participating in GridTask/GridJob execution.
  • SystemExecutorService Javadoc - Implementation of java.util.concurrent.ExecutorService to be used for processing of asynchronous job and task session responses. By default, standard ThreadPoolExecutor thread pool is provided configured to use 5 threads. Change this configuration parameter whenever you set task session attributes frequently or feel that responses are not processed fast enough.
  • PeerClassLoadingExecutorService Javadoc - Implementation of java.util.concurrent.ExecutorService to be used for processing of all Peer Class Loading requests. By default, standard ThreadPoolExecutor thread pool is provided configured to use 20 threads. Change this configuration parameter whenever you feel that class-loading requests don't get processed fast enough.

Do not confuse executor services provided in configuration for thread pooling with grid-enabled executor service provided by GridGain.

Typos in default-spring.xml

Note that default-spring.xml configuration file has commented-out examples for executor service configuration which are slightly wrong. Whenever explicitly configuring any of the executor services, make sure to specify org.gridgain.grid.thread.GridThreadPoolExecutorService class instead of org.util.concurrent.ThreadPoolExecutor specified in the examples.

Grid Lifecycle Beans

See Grid Lifecycle Beans documentation for information on how to specify lifecycle beans and examples.

SPIs - Server Provided Interfaces

Sever Provider Interfaces allow you to configure virtually every aspect of GridGain, such as communication, discovery, topology and failover, load-balancing, etc... in LEGO-like fashion. For information on available SPI's and their configuration refer to SPI - Service Provider Interfaces documentation.

Specifying Different SPIs Per GridTask

Starting with GridGain 2.1 you can start multiple instances of GridTopologySpi, GridLoadBalancingSpi, GridFailoverSpi, and GridCheckpointSpi. If you do that, you need to tell a task which SPI to use (by default it will use the fist SPI in the list).

Add @GridTaskSpis Javadoc annotation for your task to specify what SPIs it wants to use. If this annotation is omitted, then by default GridGain will pick the first corresponding SPI implementation from the array of SPIs provided in configuration.

This example shows how to configure different SPI's for different tasks. Let's assume that you have two worker nodes, Node1 and Node2. Let's also assume that you configure Node1 to belong to SegmentA and Node2 to belong to SegmentB. Here is a sample configuration for Node1

<bean id="grid.cfg" class="org.gridgain.grid.GridConfigurationAdapter" scope="singleton">  
     <property name="userAttributes">  
         <map>  
             <entry key="segment" value="A"/>  
         </map>  
     </property>  
 </bean>

Node2 configuration looks similar to Node1 with 'segment' attribute set to 'B'.

<bean id="grid.cfg" class="org.gridgain.grid.GridConfigurationAdapter" scope="singleton">  
     <property name="userAttributes">  
         <map>  
             <entry key="segment" value="B"/>  
         </map>  
     </property>  
 </bean>

Now, if you have Task1 and Task2 starting from some master node NodeM, you can easily configure Task1 to only run on SegmentA and Task2 to only run on SegmentB. Here is how configuration on master node NodeM would look like:

<bean id="grid.cfg" class="org.gridgain.grid.GridConfigurationAdapter" scope="singleton">  
     <!--  
         Topology SPIs. We have two named SPIs: One picks up nodes  
         that have attribute "segment" set to "A" and another one sees  
         nodes that have attribute "segment" set to "B".  
     -->  
     <property name="topologySpi">  
         <list>  
             <bean class="org.gridgain.grid.spi.topology.nodefilter.GridNodeFilterTopologySpi">  
                 <property name="name" value="topologyA"/>  
                 <property name="filter">  
                     <bean class="org.gridgain.grid.GridJexlNodeFilter">  
                         <property name="expression" value="node.attributes['segment'] == 'A'"/>  
                     </bean>  
                 </property>  
             </bean>  
             <bean class="org.gridgain.grid.spi.topology.nodefilter.GridNodeFilterTopologySpi">  
                 <property name="name" value="topologyB"/>  
                 <property name="filter">  
                     <bean class="org.gridgain.grid.GridJexlNodeFilter">  
                         <property name="expression" value="node.attributes['segment'] == 'B'"/>  
                     </bean>  
                 </property>  
             </bean>  
         </list>  
     </property>  
 </bean>

Then your Task1 and Task2 would look as follows (note the @GridTaskSpis annotation).

@GridTaskSpis(topologySpi="topologyA")  
 public class GridSegmentATask extends GridTaskSplitAdapter<String, Integer> {  
 ...  
 }

and

@GridTaskSpis(topologySpi="topologyB")  
 public class GridSegmentBTask extends GridTaskSplitAdapter<String, Integer> {  
 ...  
 }

GridSpringBean

Grid Spring bean allows to bypass GridFactory Javadoc methods. In other words, this bean class allows to inject new grid instance from Spring configuration file directly without invoking static GridFactory Javadoc methods. This class can be wired directly from Spring and can be referenced from within other Spring beans. By virtue of implementing org.springframework.beans.factory.DisposableBean and org.springframework.beans.factory.InitializingBean interfaces, GridSpringBean automatically starts and stops underlying grid instance.

The following configuration parameters are optional:

  • Grid configuration (see setConfiguration(GridConfiguration) Javadoc )

Spring Configuration Example

<bean id="mySpringBean" class="org.gridgain.grid.GridSpringBean" scope="singleton">
    <property name="configuration">
        <bean id="grid.cfg" class="org.gridgain.grid.GridConfigurationAdapter" scope="singleton">
            <property name="gridName" value="mySpringGrid"/>
        </bean>
    </property>
</bean>

Or use default configuration:

<bean id="mySpringBean" class="org.gridgain.grid.GridSpringBean" scope="singleton"/>

Java Example

Here is how you may access this bean from code:

AbstractApplicationContext ctx = new FileSystemXmlApplicationContext("/path/to/spring/file");

// Register Spring hook to destroy bean automatically.
ctx.registerShutdownHook();

Grid grid = (Grid)ctx.getBean("mySpringBean");

Examples

GridConfiguration may be defined in code

GridConfigurationAdapter cfg = new GridConfigurationAdapter();

// Override default values for grid node.
cfg.setGridName("mygrid");

...

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

or from Spring configuration file (default Spring configuration file can be found in GRIDGAIN_HOME/config/default-spring.xml file).

<bean id="grid.cfg" class="org.gridgain.grid.GridConfigurationAdapter" scope="singleton">
        ...
        <property name="gridName" value="mygrid"/>
        ...
</bean>


For more information about using Spring framework for configuration click here.

Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.2.10 Build:#528 Nov 29, 2006) - Bug/feature request - Contact Administrators