org.gridgain.grid
Class GridFactory

java.lang.Object
  org.gridgain.grid.GridFactory

public final class GridFactory
extends Object

This interface defines a factory for the main GridGain API. It controls Grid life cycle and allows listening for grid events.

Grid Loaders

Although user can call grid factory directly to start and stop grid, grid is often started and stopped by grid loaders. Some examples of Grid loaders are:

• GridCommandLineLoader
• GridJbossLoader
• GridWeblogicStartup and GridWeblogicShutdown
• GridWebsphereLoader
• GridGlassfishLoader
• GridServletLoader

Grid Configuration

Note that all parameters passed in GridConfiguration to GridFactory.start(GridConfiguration) method are optional. If not provided, default values will be used. Below is the table that provides default value for every configuration parameter.

GridConfiguration Method	Default Value	Description
GridConfiguration.getGridName()	null	Grid name (null is a default value).
GridConfiguration.getUserAttributes()	Empty set.	Attributes to be set on local node.
GridConfiguration.getGridLogger()	Log4J logger initialized to log only to console (see GridLog4jLogger.GridLog4jLogger(boolean))	Logger to use within grid.
GridConfiguration.getExecutorService()	Grid thread pool with default initialization (see GridThreadPoolExecutorService). The size of the thread pool is 100 by default.	Executor service used by grid to handle GridTask and GridJob execution.
GridConfiguration.getSystemExecutorService()	Default thread pool size is 5.	This executor service is in charge of processing GridTaskSession requests and user messages sent via Grid.sendMessage(GridNode, Serializable) method.
GridConfiguration.getPeerClassLoadingExecutorService()	Default thread pool size is 20.	This executor service is in charge of handling peer class loading requests/responses.
GridConfiguration.getGridGainHome()	Inferred (see GridConfiguration.getGridGainHome() for details).	Path to GridGain installation folder.
GridConfiguration.getMBeanServer()	Platform MBean server (see ManagementFactory.getPlatformMBeanServer()).	MBean server used by grid.
GridConfiguration.getNodeId()	Randomly generated node ID (see UUID.randomUUID()).	Local node unique identifier.
GridConfiguration.isPeerClassLoadingEnabled()	true	Boolean flag to control peer class loading. When enabled, if a task is not deployed on a node, the system will attempt to load it from a peer node (usually from the node that initiated task execution).
GridConfiguration.getPeerClassLoadingMissedResourcesCacheSize()	true	Size of internal missed resources cache. Grid will cache all missed resources and all subsequent call for the same resource on the same class loader will return null immediately. If class was missed then subsequent call for the same class on the class loader will throw corresponding exception. But if cache size is less than needed redundant peer resources/classes requests can be sent.
GridConfiguration.getP2PLocalClassPathExclude()	Empty list.	List of packages to exclude from local classpath when executing grid tasks. All classes within these packages will be loaded on demand from the node that initiated task execution.
GridConfiguration.getMetricsExpireTime()	GridConfiguration.DFLT_METRICS_EXPIRE_TIME	Maximum time until node metrics from remote nodes are considered expired. Node metrics are frequently updated (usually with every heartbeat) and provide runtime information about remote nodes (see GridNode.getMetrics()).
GridConfiguration.getMetricsHistorySize()	GridConfiguration.DFLT_METRICS_HISTORY_SIZE	Maximum number of metrics to keep in the memory. The larger this number, the more precise the metrics calculations are (at the expense of more memory consumption). Node metrics are frequently updated (usually with every heartbeat) and provide runtime information about remote nodes (see GridNode.getMetrics()).
GridConfiguration.getPeerClassLoadingTimeout()	GridConfiguration.DFLT_PEER_CLASS_LOADING_TIMEOUT	Maximum timeout in milliseconds to wait for class-loading responses from remote nodes. After reaching this timeout ClassNotFoundException will be thrown.
GridConfiguration.getLifecycleBeans()	The default is null.	Collection of GridLifecycleBean beans. Use these beans whenever you need to plug some cusom logic before or after grid startup or stopping routines.
GridConfiguration.getDiscoveryStartupDelay()	The default value is 60,000ms specified by GridConfiguration.DFLT_DISCOVERY_STARTUP_DELAY. This should be good enough for vast majority of configurations. However, if you do anticipate an even larger delay, you should increase this value.	This value is used to expire messages from waiting list whenever node discovery discrepancies happen. During startup, it is possible for some SPI's, such as GridMuleDiscoverySpi or GridJmsDiscoverySpi, to have a small time window when Node A has discovered Node B, but Node B has not discovered Node A yet. Such time window is usually very small, a matter of milliseconds, but certain JMS providers or some Mule messaging protocols may be very slow and hence have larger discovery delay window.
GridConfiguration.getDiscoverySpi()	Multicast-based grid discovery (see GridMulticastDiscoverySpi).	Fully configured SPI used for discovering remote grid nodes.
GridConfiguration.getCommunicationSpi()	TCP-based communication (see GridTcpCommunicationSpi).	Fully configured SPI used for communication between grid nodes.
GridConfiguration.getDeploymentSpi()	Local (in-memory) deployment SPI (see GridLocalDeploymentSpi).	Fully configured SPI used for deploying grid tasks.
GridConfiguration.getCheckpointSpi()	Shared file system checkpoint SPI which (see GridSharedFsCheckpointSpi).	Fully configured SPI used for storing intermediate job state to safeguard against failures.
GridConfiguration.getEventStorageSpi()	In-memory limited event storage (see GridMemoryEventStorageSpi).	Fully configured SPI used for storing grid events.
GridConfiguration.getTopologySpi()	Basic topology spi that provides all discovered grid nodes (see GridBasicTopologySpi).	Fully configured SPI used for determining grid task execution topology.
GridConfiguration.getFailoverSpi()	Failover SPI that always fails over jobs to another node (see GridAlwaysFailoverSpi).	Fully configured SPI used for failing over jobs to another node in case of node failure.
GridConfiguration.getCollisionSpi()	Job collision SPI that executes all incoming jobs in FIFO order (see GridFifoQueueCollisionSpi).	Fully configured SPI used for handling job collisions.
GridConfiguration.getMetricsSpi()	Basic JDK-based local VM Metrics implementation (see GridJdkLocalMetricsSpi).	Fully configured SPI used for providing local VM metrics.
GridConfiguration.getLoadBalancingSpi()	Round-Robin implementation that will pick a random start node for every task and will iterate through all nodes starting at the start node sequentially for every grid job. (see GridRoundRobinLoadBalancingSpi).	Fully configured SPI used for load balancing of jobs within grid.
GridConfiguration.getTracingSpi()	If not provided, then tracing will not be performed.	Fully configured SPI used for tracing public grid method invocations.

Multiple Grid Instances

Note that you can start multiple grid nodes within same VM by specifying grid name (see GridFactory.start(GridConfiguration)). This may be useful for testing whenever it is needed to check internal job parameters when jobs are running on different nodes. In most cases, however, you should use default no-name grid.

Shutdown Hook

GridFactory sets shutdown hook (see Runtime.addShutdownHook(Thread)) to stop all started grids when VM is exiting but it is recommended to stop all started grid instances in your code where you started them. Defining GRIDGAIN_NO_SHUTDOWN_HOOK system property or environment variable and setting value to true will prevent GridFactory of setting up its own shutdown hook and you can stop all grid instances in your own one.

Examples

Use GridFactory.start() method to start grid with default configuration. You can also use GridConfigurationAdapter to override some default configuration. Below is an example on how to start grid with URI deployment and JGroups-based discovery SPI's.

 GridConfigurationAdapter cfg = new GridConfigurationAdapter();

 GridUriDeployment deploySpi = new GridUriDeployment();

 deploySpi.setUriList(Collections.singletonList("classes://tmp/ideoutput/classes"));

 GridJgroupsDiscovery discoSpi = new GridJgroupsDiscovery();

 discoSpi.setConfigurationFile("/config/jgroups/multicast/jgroups.xml");

 cfg.setDeploymentSpi(deploySpi);
 cfg.setDiscoverySpi(discoSpi);

 GridFactroy.start(cfg);
 

Here is how a grid instance can be configured from Spring XML configuration file. The example below configures a grid instance with additional user attributes (see GridNode.getAttributes()) and specifies a grid name:

 <bean id="grid.cfg" class="org.gridgain.grid.GridConfigurationAdapter" scope="singleton">
     ...
     <property name="gridName" value="mygrid"/>
     <property name="userAttributes">
         <map>
             <entry key="group" value="worker"/>
             <entry key="grid.node.benchmark">
                 <bean class="org.gridgain.grid.benchmarks.GridLocalNodeBenchmark" init-method="start"/>
             </entry>
         </map>
     </property>
     ...
 </bean>
 

A grid instance with Spring configuration above can be started as following. Note that you do not need to pass path to Spring XML file if you are using GRIDGAIN_HOME/config/default-spring.xml. Also note, that the path can be absolute or relative to GRIDGAIN_HOME.

 GridFactory.start("/path/to/spring/xml/file.xml");
 

You can also instantiate grid directly from Spring without using GridFactory. For more information refer to GridSpringBean documentation.



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

Method Summary

static void	addListener(GridFactoryListener listener) Adds a listener for grid life cycle events.
static List<Grid>	getAllGrids() Gets a list of all grids started so far.
static Grid	getGrid() Gets an instance of default no-name grid.
static Grid	getGrid(String name) Gets an named grid instance.
static Grid	getGrid(UUID localNodeId) Gets a grid instance for given local node ID.
static GridFactoryState	getState() Gets state of grid default grid.
static GridFactoryState	getState(String name) Gets states of named grid.
static boolean	removeListener(GridFactoryListener listener) Removes listener added by GridFactory.addListener(GridFactoryListener) method.
static Grid	start() Starts grid with default configuration.
static Grid	start(org.springframework.context.ApplicationContext springCtx) Starts grid with default configuration.
static Grid	start(GridConfiguration cfg) Starts grid with given configuration.
static Grid	start(GridConfiguration cfg, org.springframework.context.ApplicationContext springCtx) Starts grid with given configuration.
static Grid	start(String springCfgPath) Starts all grids specified within given Spring XML configuration file.
static Grid	start(String springCfgPath, org.springframework.context.ApplicationContext ctx) Starts all grids specified within given Spring XML configuration file.
static Grid	start(URL springCfgUrl) Starts all grids specified within given Spring XML configuration file URL.
static Grid	start(URL springCfgUrl, org.springframework.context.ApplicationContext ctx) Starts all grids specified within given Spring XML configuration file URL.
static boolean	stop(boolean cancel) Stops default grid.
static boolean	stop(boolean cancel, boolean wait) Stops default grid.
static boolean	stop(String name, boolean cancel) Stops named grid.
static boolean	stop(String name, boolean cancel, boolean wait) Stops named grid.
static void	stopAll(boolean cancel) Stops all started grids.
static void	stopAll(boolean cancel, boolean wait) Stops all started grids.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getState

public static GridFactoryState getState()

Gets state of grid default grid.

Returns:

Default grid state.

getState

public static GridFactoryState getState(String name)

Gets states of named grid. If name is null, then state of default no-name grid is returned.

Parameters:

name - Grid name. If name is null, then state of default no-name grid is returned.

Returns:

Grid state.

stop

public static boolean stop(boolean cancel)

Stops default grid. This method is identical to GridFactory.stop(null, cancel) call. Note that method does not wait for all tasks to be completed.

Parameters:

cancel - If true then all jobs currently executing on default grid will be cancelled by calling GridJob.cancel() method. Note that just like with Thread.interrupt(), it is up to the actual job to exit from execution

Returns:

true if default grid instance was indeed stopped, false otherwise (if it was not started).

stop

public static boolean stop(boolean cancel,
                           boolean wait)

Stops default grid. This method is identical to GridFactory.stop(null, cancel, wait) call. If wait parameter is set to true then it will wait for all tasks to be finished.

Parameters:

cancel - If true then all jobs currently executing on default grid will be cancelled by calling GridJob.cancel() method. Note that just like with Thread.interrupt(), it is up to the actual job to exit from execution.

wait - If true then method will wait for all task being executed until they finish their execution.

Returns:

true if default grid instance was indeed stopped, false otherwise (if it was not started).

stop

public static boolean stop(String name,
                           boolean cancel)

Stops named grid. If cancel flag is set to true then all jobs currently executing on local node will be interrupted. If grid name is null, then default no-name grid will be stopped. It does not wait for the tasks to finish their execution.

Parameters:

name - Grid name. If null, then default no-name grid will be stopped.

cancel - If true then all jobs currently will be cancelled by calling GridJob.cancel() method. Note that just like with Thread.interrupt(), it is up to the actual job to exit from execution. If false, then jobs currently running will not be canceled. In either case, grid node will wait for completion of all jobs running on it before stopping.

Returns:

true if named grid instance was indeed found and stopped, false otherwise (the instance with given name was not found).

stop

public static boolean stop(String name,
                           boolean cancel,
                           boolean wait)

Stops named grid. If cancel flag is set to true then all jobs currently executing on local node will be interrupted. If grid name is null, then default no-name grid will be stopped. If wait parameter is set to true then grid will wait for all tasks to be finished.

Parameters:

name - Grid name. If null, then default no-name grid will be stopped.

cancel - If true then all jobs currently will be cancelled by calling GridJob.cancel() method. Note that just like with Thread.interrupt(), it is up to the actual job to exit from execution. If false, then jobs currently running will not be canceled. In either case, grid node will wait for completion of all jobs running on it before stopping.

wait - If true then method will wait for all task being executed until they finish their execution.

Returns:

true if named grid instance was indeed found and stopped, false otherwise (the instance with given name was not found).

stopAll

public static void stopAll(boolean cancel)

Stops all started grids. If cancel flag is set to true then all jobs currently executing on local node will be interrupted. It does not wait for the tasks to finish their execution.

Note: it is usually safer and more appropriate to stop grid instances individually instead of blanket operation. In most cases, the party that started the grid instance should be responsible for stopping it.

Parameters:

cancel - If true then all jobs currently executing on all grids will be cancelled by calling GridJob.cancel() method. Note that just like with Thread.interrupt(), it is up to the actual job to exit from execution

stopAll

public static void stopAll(boolean cancel,
                           boolean wait)

Stops all started grids. If cancel flag is set to true then all jobs currently executing on local node will be interrupted. If wait parameter is set to true then grid will wait for all tasks to be finished.

Note: it is usually safer and more appropriate to stop grid instances individually instead of blanket operation. In most cases, the party that started the grid instance should be responsible for stopping it.

Parameters:

cancel - If true then all jobs currently executing on all grids will be cancelled by calling GridJob.cancel() method. Note that just like with Thread.interrupt(), it is up to the actual job to exit from execution

wait - If true then method will wait for all tasks being executed until they finish their execution.

start

public static Grid start()
                  throws GridException

Starts grid with default configuration. By default this method will use grid configuration defined in GRIDGAIN_HOME/config/default-spring.xml configuration file. If such file is not found, then all system defaults will be used.

Throws:

GridException - If default grid could not be started. This exception will be thrown also if default grid has already been started.

Returns:

Started grid.

start

public static Grid start(org.springframework.context.ApplicationContext springCtx)
                  throws GridException

Starts grid with default configuration. By default this method will use grid configuration defined in GRIDGAIN_HOME/config/default-spring.xml configuration file. If such file is not found, then all system defaults will be used.

Throws:

GridException - If default grid could not be started. This exception will be thrown also if default grid has already been started.

Parameters:

springCtx - Spring application context.

Returns:

Started grid.

start

public static Grid start(GridConfiguration cfg)
                  throws GridException

Starts grid with given configuration. Note that this method is no-op if grid with the name provided in given configuration is already started.

Throws:

GridException - If grid could not be started. This exception will be thrown also if named grid has already been started.

Parameters:

cfg - Grid configuration. This cannot be null.

Returns:

Started grid.

start

public static Grid start(GridConfiguration cfg,
                         org.springframework.context.ApplicationContext springCtx)
                  throws GridException

Starts grid with given configuration. Note that this method is no-op if grid with the name provided in given configuration is already started.

Throws:

GridException - If grid could not be started. This exception will be thrown also if named grid has already been started.

Parameters:

cfg - Grid configuration. This cannot be null.

springCtx - Spring application context, possibly null. If provided, this context can be injected into grid tasks and grid jobs using @GridSpringApplicationContextResource annotation.

Returns:

Started grid.

start

public static Grid start(String springCfgPath)
                  throws GridException

Starts all grids specified within given Spring XML configuration file. If grid with given name is already started, then exception is thrown. In this case all instances that may have been started so far will be stopped too.

Usually Spring XML configuration file will contain only one Grid definition. Note that Grid configuration bean(s) is retrieved form configuration file by type, so the name of the Grid configuration bean is ignored.

Throws:

GridException - If grid could not be started or configuration read. This exception will be thrown also if grid with given name has already been started or Spring XML configuration file is invalid.

Parameters:

springCfgPath - Spring XML configuration file path or URL. This cannot be null.

Returns:

Started grid. If Spring configuration contains multiple grid instances, then the 1st found instance is returned.

start

public static Grid start(String springCfgPath,
                         org.springframework.context.ApplicationContext ctx)
                  throws GridException

Starts all grids specified within given Spring XML configuration file. If grid with given name is already started, then exception is thrown. In this case all instances that may have been started so far will be stopped too.

Usually Spring XML configuration file will contain only one Grid definition. Note that Grid configuration bean(s) is retrieved form configuration file by type, so the name of the Grid configuration bean is ignored.

Throws:

GridException - If grid could not be started or configuration read. This exception will be thrown also if grid with given name has already been started or Spring XML configuration file is invalid.

Parameters:

springCfgPath - Spring XML configuration file path or URL. This cannot be null.

ctx - Spring application context.

Returns:

Started grid. If Spring configuration contains multiple grid instances, then the 1st found instance is returned.

start

public static Grid start(URL springCfgUrl)
                  throws GridException

Starts all grids specified within given Spring XML configuration file URL. If grid with given name is already started, then exception is thrown. In this case all instances that may have been started so far will be stopped too.

Usually Spring XML configuration file will contain only one Grid definition. Note that Grid configuration bean(s) is retrieved form configuration file by type, so the name of the Grid configuration bean is ignored.

Throws:

GridException - If grid could not be started or configuration read. This exception will be thrown also if grid with given name has already been started or Spring XML configuration file is invalid.

Parameters:

springCfgUrl - Spring XML configuration file URL. This cannot be null.

Returns:

Started grid. If Spring configuration contains multiple grid instances, then the 1st found instance is returned.

start

public static Grid start(URL springCfgUrl,
                         org.springframework.context.ApplicationContext ctx)
                  throws GridException

Starts all grids specified within given Spring XML configuration file URL. If grid with given name is already started, then exception is thrown. In this case all instances that may have been started so far will be stopped too.

Usually Spring XML configuration file will contain only one Grid definition. Note that Grid configuration bean(s) is retrieved form configuration file by type, so the name of the Grid configuration bean is ignored.

Throws:

GridException - If grid could not be started or configuration read. This exception will be thrown also if grid with given name has already been started or Spring XML configuration file is invalid.

Parameters:

springCfgUrl - Spring XML configuration file URL. This cannot be null.

ctx - Spring application context.

Returns:

Started grid. If Spring configuration contains multiple grid instances, then the 1st found instance is returned.

getGrid

public static Grid getGrid()
                    throws IllegalStateException

Gets an instance of default no-name grid. Note that caller of this method should not assume that it will return the same instance every time.

This method is identical to GridFactory.getGrid(null) call.

Throws:

IllegalStateException - Thrown if default grid was not properly initialized or grid instance was stopped or was not started.

Returns:

An instance of default no-name grid. This method never returns null.

getAllGrids

public static List<Grid> getAllGrids()

Gets a list of all grids started so far.

Returns:

List of all grids started so far.

getGrid

public static Grid getGrid(UUID localNodeId)
                    throws IllegalStateException

Gets a grid instance for given local node ID. Note that grid instance and local node have one-to-one relationship where node has ID and instance has name of the grid to which both grid instance and its node belong. Note also that caller of this method should not assume that it will return the same instance every time.

Throws:

IllegalStateException - Thrown if grid was not properly initialized or grid instance was stopped or was not started.

Parameters:

localNodeId - ID of local node the requested grid instance is managing.

Returns:

An instance of named grid. This method never returns null.

getGrid

public static Grid getGrid(String name)
                    throws IllegalStateException

Gets an named grid instance. If grid name is null or empty string, then default no-name grid will be returned. Note that caller of this method should not assume that it will return the same instance every time.

Note that Java VM can run multiple grid instances and every grid instance (and its node) can belong to a different grid. Grid name defines what grid a particular grid instance (and correspondently its node) belongs to.

Throws:

IllegalStateException - Thrown if default grid was not properly initialized or grid instance was stopped or was not started.

Parameters:

name - Grid name to which requested grid instance belongs to. If null, then grid instanced belonging to a default no-name grid will be returned.

Returns:

An instance of named grid. This method never returns null.

addListener

public static void addListener(GridFactoryListener listener)

Adds a listener for grid life cycle events.

Parameters:

listener - Listener for grid life cycle events.

removeListener

public static boolean removeListener(GridFactoryListener listener)

Removes listener added by GridFactory.addListener(GridFactoryListener) method.

Parameters:

listener - Listener to remove.

Returns:

true if listener was added before, false otherwise.