org.gridgain.grid

Interface Grid

All Superinterfaces:

AutoCloseable, GridProjection

All Known Subinterfaces:

GridEx

All Known Implementing Classes:

GridKernal

public interface Grid
extends GridProjection, AutoCloseable

Main entry-point for all GridGain APIs. You can obtain an instance of Grid through GridGain.grid(), or for named grids you can use GridGain.grid(String). Note that you can have multiple instances of Grid running in the same VM by giving each instance a different name.

Note that Grid extends GridProjection which means that it provides grid projection functionality over the whole grid (instead os a subgroup of nodes).

In addition to GridProjection functionality, from here you can get the following:

• GridCache - functionality for in-memory distributed cache.
• GridDataLoader - functionality for loading data large amounts of data into cache.
• GridDr - functionality for WAN-based Data Center Replication of in-memory cache.
• GridGgfs - functionality for distributed Hadoop-compliant in-memory file system and map-reduce.
• GridStreamer - functionality for streaming events workflow with queries and indexes into rolling windows.
• GridScheduler - functionality for scheduling jobs using UNIX Cron syntax.
• GridProduct - functionality for licence management and update and product related information.
• GridCompute - functionality for executing tasks and closures on all grid nodes (inherited form GridProjection).
• GridMessaging - functionality for topic-based message exchange on all grid nodes (inherited form GridProjection).
• GridEvents - functionality for querying and listening to events on all grid nodes (inherited form GridProjection).

Grid also provides a handle on nodeLocalMap() which provides map-like functionality linked to current grid node. Node-local map is useful for saving shared state between job executions on the grid. Additionally you can also ping, start, and restart remote nodes, map keys to caching nodes, and get other useful information about topology.

Method Summary

Methods

Modifier and Type	Method and Description
<K,V> GridCache<K,V>	cache(String name) Gets the cache instance for the given name, if one does not exist IllegalArgumentException will be thrown.
Collection<GridCache<?,?>>	caches() Gets all configured caches.
void	close() Closes this instance of grid.
GridConfiguration	configuration() Gets the configuration of this grid instance.
<K,V> GridDataLoader<K,V>	dataLoader(String cacheName) Gets a new instance of data loader associated with given cache name.
GridDr	dr() Gets an instance of Data Center Replication.
GridProjection	forLocal() Gets monadic projection consisting from the local node.
GridGgfs	ggfs(String name) Gets an instance of GGFS - GridGain In-Memory File System, if one is not configured then IllegalArgumentException will be thrown.
Collection<GridGgfs>	ggfss() Gets all instances of the grid file systems.
GridNode	localNode() Gets local grid node.
GridLogger	log() Gets grid's logger.
<K> Map<GridNode,Collection<K>>	mapKeysToNodes(String cacheName, Collection<? extends K> keys) This method provides ability to detect which cache keys are mapped to which nodes on cache instance with given name.
<K> GridNode	mapKeyToNode(String cacheName, K key) This method provides ability to detect which cache keys are mapped to which nodes on cache instance with given name.
String	name() Gets the name of the grid this grid instance (and correspondingly its local node) belongs to.
<K,V> GridNodeLocalMap<K,V>	nodeLocalMap() Gets node-local storage instance.
boolean	pingNode(UUID nodeId) Pings a remote node.
GridProduct	product() Gets information about product as well as license management capabilities.
void	resetMetrics() Resets local I/O, job, and task execution metrics.
void	restartNodes() Restarts nodes satisfying optional set of predicates.
void	restartNodes(Collection<UUID> ids) Restarts nodes defined by provided IDs.
GridScheduler	scheduler() Gets an instance of cron-based scheduler.
GridSecurity	security() Gets an instance of GridSecurity interface.
GridFuture<Collection<GridTuple3<String,Boolean,String>>>	startNodes(Collection<Map<String,Object>> hosts, Map<String,Object> dflts, boolean restart, int timeout, int maxConn) Starts one or more nodes on remote host(s).
GridFuture<Collection<GridTuple3<String,Boolean,String>>>	startNodes(File file, boolean restart, int timeout, int maxConn) Starts one or more nodes on remote host(s).
void	stopNodes() Stops nodes satisfying optional set of predicates.
void	stopNodes(Collection<UUID> ids) Stops nodes defined by provided IDs.
GridStreamer	streamer(String name) Gets an instance of streamer by name, if one does not exist then IllegalArgumentException will be thrown.
Collection<GridStreamer>	streamers() Gets all instances of streamers.
Collection<GridNode>	topology(long topVer) Gets a topology by version.
long	topologyVersion() Gets current topology version.

Methods inherited from interface org.gridgain.grid.GridProjection

compute, events, forAttribute, forCache, forDaemons, forHost, forNode, forNodeId, forNodeIds, forNodes, forOthers, forOthers, forPredicate, forRandom, forRemotes, forStreamer, grid, message, metrics, node, node, nodes, predicate

Method Detail

name

String name()

Gets the name of the grid this grid instance (and correspondingly its local node) belongs to. Note that single Java VM can have multiple grid instances all belonging to different grids. Grid name allows to indicate to what grid this particular grid instance (i.e. grid runtime and its local node) belongs to.

If default grid instance is used, then null is returned. Refer to GridGain documentation for information on how to start named grids.

Returns:

Name of the grid, or null for default grid.

log

GridLogger log()

Gets grid's logger.

Returns:

Grid's logger.

nodeLocalMap

<K,V> GridNodeLocalMap<K,V> nodeLocalMap()

Gets node-local storage instance.

Node-local values are similar to thread locals in a way that these values are not distributed and kept only on local node (similar like thread local values are attached to the current thread only). Node-local values are used primarily by closures executed from the remote nodes to keep intermediate state on the local node between executions.

There's only one instance of node local storage per local node. Node local storage is based on ConcurrentMap and is safe for multi-threaded access.

Returns:

Node local storage instance for the local node.

configuration

GridConfiguration configuration()

Gets the configuration of this grid instance.

NOTE:
SPIs obtains through this method should never be used directly. SPIs provide internal view on the subsystem and is used internally by GridGain kernal. In rare use cases when access to a specific implementation of this SPI is required - an instance of this SPI can be obtained via this method to check its configuration properties or call other non-SPI methods.

Returns:

Grid configuration instance.

forLocal

GridProjection forLocal()

Gets monadic projection consisting from the local node.

Returns:

Monadic projection consisting from the local node.

product

GridProduct product()

Gets information about product as well as license management capabilities.

Returns:

Instance of product.

scheduler

GridScheduler scheduler()

Gets an instance of cron-based scheduler.

Returns:

Instance of scheduler.

security

GridSecurity security()

Gets an instance of GridSecurity interface. Available in enterprise edition only.

Returns:

Instance of GridSecurity interface.

dr

@GridOnlyAvailableIn(value=DATA_GRID)
GridDr dr()

Gets an instance of Data Center Replication.

Returns:

Instance of Data Center Replication.

cache

@GridOnlyAvailableIn(value=DATA_GRID)
<K,V> GridCache<K,V> cache(@Nullable
                                                           String name)

Gets the cache instance for the given name, if one does not exist IllegalArgumentException will be thrown. Note that in case named cache instance is used as GGFS data or meta cache, IllegalStateException will be thrown.

Type Parameters:

K - Key type.

V - Value type.

Parameters:

name - Cache name.

Returns:

Cache instance for given name.

See Also:

GridGgfsConfiguration, GridGgfsConfiguration.getDataCacheName(), GridGgfsConfiguration.getMetaCacheName()

caches

@GridOnlyAvailableIn(value=DATA_GRID)
Collection<GridCache<?,?>> caches()

Gets all configured caches. Caches that are used as GGFS meta and data caches will not be returned in resulting collection.

Returns:

All configured caches.

See Also:

GridGgfsConfiguration, GridGgfsConfiguration.getDataCacheName(), GridGgfsConfiguration.getMetaCacheName()

dataLoader

@GridOnlyAvailableIn(value=DATA_GRID)
<K,V> GridDataLoader<K,V> dataLoader(@Nullable
                                                                     String cacheName)

Gets a new instance of data loader associated with given cache name. Data loader is responsible for loading external data into in-memory data grid. For more information refer to GridDataLoader documentation.

Parameters:

cacheName - Cache name (null for default cache).

Returns:

Data loader.

ggfs

@GridOnlyAvailableIn(value=HADOOP)
GridGgfs ggfs(String name)

Gets an instance of GGFS - GridGain In-Memory File System, if one is not configured then IllegalArgumentException will be thrown.

GGFS is fully compliant with Hadoop FileSystem APIs and can be plugged into Hadoop installations. For more information refer to documentation on Hadoop integration shipped with GridGain.

Parameters:

name - GGFS name.

Returns:

GGFS instance.

ggfss

@GridOnlyAvailableIn(value=HADOOP)
Collection<GridGgfs> ggfss()

Gets all instances of the grid file systems.

Returns:

Collection of grid file systems instances.

streamer

@GridOnlyAvailableIn(value=STREAMING)
GridStreamer streamer(@Nullable
                                                      String name)

Gets an instance of streamer by name, if one does not exist then IllegalArgumentException will be thrown.

Parameters:

name - Streamer name.

Returns:

Streamer for given name.

streamers

@GridOnlyAvailableIn(value=STREAMING)
Collection<GridStreamer> streamers()

Gets all instances of streamers.

Returns:

Collection of all streamer instances.

localNode

GridNode localNode()

Gets local grid node.

Returns:

Local grid node.

pingNode

boolean pingNode(UUID nodeId)

Pings a remote node.

Discovery SPIs usually have some latency in discovering failed nodes. Hence, communication to remote nodes may fail at times if an attempt was made to establish communication with a failed node. This method can be used to check if communication has failed due to node failure or due to some other reason.

Parameters:

nodeId - ID of a node to ping.

Returns:

true if node for a given ID is alive, false otherwise.

See Also:

GridDiscoverySpi

startNodes

GridFuture<Collection<GridTuple3<String,Boolean,String>>> startNodes(File file,
                                                                   boolean restart,
                                                                   int timeout,
                                                                   int maxConn)
                                                                     throws GridException

Starts one or more nodes on remote host(s).

This method takes INI file which defines all startup parameters. It can contain one or more sections, each for a host or for range of hosts (note that they must have different names) and a special 'defaults' section with default values. They are applied to undefined parameters in host's sections.

Returned result is collection of tuples. Each tuple corresponds to one node start attempt and contains hostname, success flag and error message if attempt was not successful. Note that successful attempt doesn't mean that node was actually started and joined topology. For large topologies (> 100s nodes) it can take over 10 minutes for all nodes to start. See individual node logs for details.

Parameters:

file - Configuration file.

restart - Whether to stop existing nodes. If true, all existing nodes on the host will be stopped before starting new ones. If false, nodes will be started only if there are less nodes on the host than expected.

timeout - Connection timeout.

maxConn - Number of parallel SSH connections to one host.

Returns:

Future for collection of tuples, each containing host name, result (success of failure) and error message (if any).

Throws:

GridException - In case of error.

startNodes

GridFuture<Collection<GridTuple3<String,Boolean,String>>> startNodes(Collection<Map<String,Object>> hosts,
                                                                   @Nullable
                                                                   Map<String,Object> dflts,
                                                                   boolean restart,
                                                                   int timeout,
                                                                   int maxConn)
                                                                     throws GridException

Starts one or more nodes on remote host(s).

Each map in hosts collection defines startup parameters for one host or for a range of hosts. The following parameters are supported:

Name	Type	Description
host	String	Hostname (required). Can define several hosts if their IPs are sequential. E.g., 10.0.0.1~5 defines range of five IP addresses. Other parameters are applied to all hosts equally.
port	Integer	Port number (default is 22).
uname	String	Username (if not defined, current local username will be used).
passwd	String	Password (if not defined, private key file must be defined).
key	File	Private key file (if not defined, password must be defined).
nodes	Integer	Expected number of nodes on the host. If some nodes are started already, then only remaining nodes will be started. If current count of nodes is equal to this number, and restart flag is false, then nothing will happen.
ggHome	String	Path to GridGain installation folder. If not defined, GRIDGAIN_HOME environment variable must be set on remote hosts.
cfg	String	Path to configuration file (relative to ggHome).
script	String	Custom startup script file name and path (relative to ggHome). You can also specify a space-separated list of parameters in the same string (for example: "bin/my-custom-script.sh -v").

dflts map defines default values. They are applied to undefined parameters in hosts collection.

Returned result is collection of tuples. Each tuple corresponds to one node start attempt and contains hostname, success flag and error message if attempt was not successful. Note that successful attempt doesn't mean that node was actually started and joined topology. For large topologies (> 100s nodes) it can take over 10 minutes for all nodes to start. See individual node logs for details.

Parameters:

hosts - Startup parameters.

dflts - Default values.

restart - Whether to stop existing nodes. If true, all existing nodes on the host will be stopped before starting new ones. If false, nodes will be started only if there are less nodes on the host than expected.

timeout - Connection timeout in milliseconds.

maxConn - Number of parallel SSH connections to one host.

Returns:

Future for collection of tuples, each containing host name, result (success of failure) and error message (if any).

Throws:

GridException - In case of error.

stopNodes

void stopNodes()
               throws GridException

Stops nodes satisfying optional set of predicates.

NOTE: System.exit(GridGain.KILL_EXIT_CODE) will be executed on each stopping node. If you have other applications running in the same JVM along with GridGain, those applications will be stopped as well.

Throws:

GridException - In case of error.

stopNodes

void stopNodes(Collection<UUID> ids)
               throws GridException

Stops nodes defined by provided IDs.

NOTE: System.exit(GridGain.KILL_EXIT_CODE) will be executed on each stopping node. If you have other applications running in the same JVM along with GridGain, those applications will be stopped as well.

Parameters:

ids - IDs defining nodes to stop.

Throws:

GridException - In case of error.

restartNodes

void restartNodes()
                  throws GridException

Restarts nodes satisfying optional set of predicates.

NOTE: this command only works for grid nodes started with GridGain ggstart.sh or ggstart.bat scripts.

Throws:

GridException - In case of error.

restartNodes

void restartNodes(Collection<UUID> ids)
                  throws GridException

Restarts nodes defined by provided IDs.

NOTE: this command only works for grid nodes started with GridGain ggstart.sh or ggstart.bat scripts.

Parameters:

ids - IDs defining nodes to restart.

Throws:

GridException - In case of error.

topologyVersion

long topologyVersion()

Gets current topology version. In case of TCP discovery (see GridTcpDiscoverySpi) topology versions are sequential - they start from '1' and get incremented every time whenever a node joins or leaves. For other discovery SPIs topology versions may not be (and likely are not) sequential.

Returns:

Current topology version.

topology

@Nullable
Collection<GridNode> topology(long topVer)
                              throws UnsupportedOperationException

Gets a topology by version. Returns null if topology history storage doesn't contain specified topology version (history currently keeps last 1000 snapshots).

Parameters:

topVer - Topology version.

Returns:

Collection of grid nodes which represented by specified topology version, if it is present in history storage, null otherwise.

Throws:

UnsupportedOperationException - If underlying SPI implementation does not support topology history. Currently only GridTcpDiscoverySpi supports topology history.

mapKeysToNodes

<K> Map<GridNode,Collection<K>> mapKeysToNodes(@Nullable
                                             String cacheName,
                                             @Nullable
                                             Collection<? extends K> keys)
                                           throws GridException

This method provides ability to detect which cache keys are mapped to which nodes on cache instance with given name. Use it to determine which nodes are storing which keys prior to sending jobs that access these keys.

This method works as following:

• For local caches it returns only local node mapped to all keys.
• For fully replicated caches, GridCacheAffinityFunction is used to determine which keys are mapped to which groups of nodes.
• For partitioned caches, the returned map represents node-to-key affinity.

Parameters:

cacheName - Cache name, if null, then default cache instance is used.

keys - Cache keys to map to nodes.

Returns:

Map of nodes to cache keys or empty map if there are no alive nodes for this cache.

Throws:

GridException - If failed to map cache keys.

mapKeyToNode

@Nullable
<K> GridNode mapKeyToNode(@Nullable
                                 String cacheName,
                                 K key)
                      throws GridException

This method provides ability to detect which cache keys are mapped to which nodes on cache instance with given name. Use it to determine which nodes are storing which keys prior to sending jobs that access these keys.

This method works as following:

• For local caches it returns only local node ID.
• For fully replicated caches first node ID returned by GridCacheAffinityFunction is returned.
• For partitioned caches, the returned node ID is the primary node for the key.

Parameters:

cacheName - Cache name, if null, then default cache instance is used.

key - Cache key to map to a node.

Returns:

Primary node for the key or null if cache with given name is not present in the grid.

Throws:

GridException - If failed to map key.

resetMetrics

void resetMetrics()

Resets local I/O, job, and task execution metrics.

close

void close()
           throws GridException

Closes this instance of grid. This method is identical to calling G.stop(gridName, true).

The method is invoked automatically on objects managed by the try-with-resources statement.

Specified by:

close in interface AutoCloseable

Throws:

GridException - If failed to stop grid.