org.gridgain.grid
Interface Grid

All Superinterfaces:

GridMetadataAware, GridProjection, Iterable<GridRichNode>, Serializable

All Known Implementing Classes:

GridSpringBean

public interface Grid
extends GridProjection

Start Here Main Compute Grid APIs.

You can obtain an instance of Grid through GridFactory.grid(), or for named grids you can use GridFactory.grid(String). Note that you can have multiple instances of Grid running in the same VM. For information on how to start or stop Grid please refer to GridFactory class.

Grid interface allows you to perform all the main operations on the grid. Note also that this interface extends GridProjection and defined as a global monad over all nodes in the grid, i.e. set of all nodes across all clouds and the nodes outside of any clouds.

Following short video provides quick overview of basic Compute Grid capabilities:

For more information see Grid Interface on Wiki.

Wiki & Forum:

Wiki
Forum

Method Summary

void	addLocalEventListener(GridLocalEventListener lsnr, int[] types) Adds an event listener for local events.
void	addLocalEventListener(GridLocalEventListener lsnr, int type, int... types) Adds an event listener for local events.
void	addMessageListener(GridMessageListener lsnr, GridPredicate<Object>... p) Deprecated.
String	build() Gets build number of this GridGain instance.
<K,V> GridCache<K,V>	cache() Gets default cache instance if one is configured or null otherwise.
<K,V> GridCache<K,V>	cache(String name) Gets the cache instance for the given name if one is configured or null otherwise.
Collection<GridCache<?,?>>	caches(GridPredicate<? super GridCache<?,?>>... p) Gets configured cache instance that satisfy all provided predicates.
<R> GridFuture<R>	callLocal(Callable<R> c) Executes given callable on internal system thread pool asynchronously.
void	clearSwapSpace(String space) Clears all entry from the specified swap space.
GridConfiguration	configuration() Gets the configuration of this grid instance.
String	copyright() Copyright statement for GridGain code.
void	deployTask(Class<? extends GridTask> taskCls) Explicitly deploys given grid task on the local node.
void	deployTask(Class<? extends GridTask> taskCls, ClassLoader clsLdr) Explicitly deploys given grid task on the local node.
boolean	isEnterprise() Tests whether or not this GridGain runtime runs on an enterprise edition.
boolean	isJmxRemoteEnabled() Whether or not remote JMX management is enabled for this node.
boolean	isRestartEnabled() Whether or not node restart is enabled.
boolean	isSmtpEnabled() Whether or not SMTP is configured.
GridEnterpriseLicense	license() Gets enterprise license descriptor.
Collection<GridEvent>	localEvents(GridPredicate<? super GridEvent>... p) Queries local node for events using passed-in predicate filters for event selection.
GridRichNode	localNode() Gets local grid node.
Map<String,Class<? extends GridTask<?,?>>>	localTasks(GridPredicate<? super Class<? extends GridTask<?,?>>>... p) Gets map of all locally deployed tasks keyed by their task name satisfying all given predicates.
GridLogger	log() Gets grid's logger.
String	name() Gets the name of the grid this grid instance (and correspondingly its local node) belongs to.
<K,V> GridNodeLocal<K,V>	nodeLocal() Gets node-local storage instance.
boolean	pingNode(UUID nodeId) Pings a remote node.
<T> T	readFromSwap(String space, Object key, ClassLoader ldr) Reads data stored by Grid.writeToSwap(String, Object, Object, ClassLoader) method.
void	recordLocalEvent(GridEvent evt) Records locally generated event.
void	removeFromSwap(String space, Object key, GridInClosure<Object> c, ClassLoader ldr) Removes data stored by Grid.writeToSwap(String, Object, Object, ClassLoader) method.
boolean	removeLocalEventListener(GridLocalEventListener lsnr, int... types) Removes local event listener.
boolean	removeMessageListener(GridMessageListener lsnr) Deprecated.
GridRichNode	rich(GridNode node) Creates grid rich node wrapped around given thin node.
GridFuture<?>	runLocal(Runnable r) Executes given closure on internal system thread pool asynchronously.
<R> GridScheduleFuture<R>	scheduleLocal(Callable<R> c, String pattern) Schedules closure for execution using local cron-based scheduling.
GridScheduleFuture<?>	scheduleLocal(Runnable c, String pattern) Schedules closure for execution using local cron-based scheduling.
void	sendAdminEmail(String subj, String body, boolean html) Sends given email to all configured admin emails.
GridFuture<Boolean>	sendAdminEmailAsync(String subj, String body, boolean html) Schedule sending of given email to all configured admin emails.
long	topologyHash(Iterable<? extends GridNode> nodes) This method calculates hash value of the given set of nodes (a topology).
void	undeployTask(String taskName) Makes the best attempt to undeploy a task from the whole grid.
String	version() Ges version string of the GridGain instance.
GridEvent	waitForEvent(long timeout, Runnable c, GridPredicate<? super GridEvent> p, int... types) Blocks and waits for the local event.
GridFuture<GridEvent>	waitForEventAsync(GridPredicate<? super GridEvent> p, int... types) Gets event future that allows for asynchronous waiting for the specified events.
void	writeToSwap(String space, Object key, Object val, ClassLoader ldr) Writes given data to specified swap space.

Methods inherited from interface org.gridgain.grid.GridProjection

affinityCall, affinityCall, affinityCallAsync, affinityCallAsync, affinityRun, affinityRun, affinityRunAsync, affinityRunAsync, call, call, call, call, call, call, call, callAsync, callAsync, callAsync, callAsync, callAsync, callAsync, callAsync, callOptimistic, callOptimisticAsync, contains, contains, cpus, cross, cross, cross0, daemonNodes, dynamic, execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, execute, executeSync, executeSync, executeSync, executor, grid, gridify, gridify, gridify, gridify, gridify, gridify, gridify, gridify, gridify, gridify, gridify, gridify, hasLocalNode, hasRemoteNodes, hosts, isEmpty, isEmptyFor, listen, mapKeysToNodes, mapKeysToNodes, mapKeyToNode, mapKeyToNode, mapreduce, mapreduce, mapreduce, mapreduce, mapreduceAsync, mapreduceAsync, mapreduceAsync, mapreduceAsync, merge, neighborhood, node, nodeId8, nodes, nodes, oldest, oldestx, parent, predicate, projectionForAttribute, projectionForCaches, projectionForNodeIds, projectionForNodeIds, projectionForNodes, projectionForNodes, projectionForPredicate, projectionMetrics, random, randomx, reduce, reduce, reduce, reduce, reduceAsync, reduceAsync, reduceAsync, reduceAsync, remoteEvents, remoteEventsAsync, remoteListenAsync, remoteListenAsync, remoteListenAsync, remoteNodes, remoteProjection, restartNodes, restartNodes, restartNodes, run, run, run, run, run, run, run, runAsync, runAsync, runAsync, runAsync, runAsync, runAsync, runAsync, runOptimistic, runOptimisticAsync, send, send, size, split, startNodes, startNodes, stopNodes, stopNodes, stopNodes, topologyHash, withCheckpointSpi, withFailoverSpi, withLoadBalancingSpi, withName, withResultClosure, withTopologySpi, youngest, youngestx

Methods inherited from interface java.lang.Iterable

iterator

Methods inherited from interface org.gridgain.grid.GridMetadataAware

addMeta, addMetaIfAbsent, addMetaIfAbsent, allMeta, copyMeta, copyMeta, hasMeta, hasMeta, meta, putMetaIfAbsent, putMetaIfAbsent, removeMeta, removeMeta, replaceMeta

Method Detail

license

@Nullable
@GridEnterpriseFeature(value="Returns \'null\' in Community Edition.")
GridEnterpriseLicense license()

Gets enterprise license descriptor.

Returns:

Enterprise license descriptor or null when running on Community Edition.

isRestartEnabled

boolean isRestartEnabled()

Whether or not node restart is enabled. Node restart us supported when this node was started with bin/ggstart.{sh|bat} script using -r argument. Node can be programmatically restarted using GridFactory.restart(boolean, boolean)} method.

Returns:

True if restart mode is enabled, false otherwise.

See Also:

GridFactory.restart(boolean, boolean)

isJmxRemoteEnabled

boolean isJmxRemoteEnabled()

Whether or not remote JMX management is enabled for this node. Remote JMX management is enabled when the following system property is set:

• com.sun.management.jmxremote

Returns:

True if remote JMX management is enabled - false otherwise.

isSmtpEnabled

boolean isSmtpEnabled()

Whether or not SMTP is configured. Note that SMTP is considered configured if SMTP host is provided in configuration (see GridConfiguration.getSmtpHost().

If SMTP is not configured all emails notifications will be disabled.

Returns:

True if SMTP is configured - false otherwise.

See Also:

GridConfiguration.getSmtpFromEmail(), GridConfiguration.getSmtpHost(), GridConfiguration.getSmtpPassword(), GridConfiguration.getSmtpPort(), GridConfiguration.getSmtpUsername(), GridConfiguration.isSmtpSsl(), GridConfiguration.isSmtpStartTls(), Grid.sendAdminEmailAsync(String, String, boolean)

sendAdminEmailAsync

@GridEnterpriseFeature
GridFuture<Boolean> sendAdminEmailAsync(String subj,
                                                              String body,
                                                              boolean html)

Schedule sending of given email to all configured admin emails. If no admin emails are configured this method is no-op. If SMTP is not configured this method is no-op.

Note that this method returns immediately with the future and all emails will be sent asynchronously in a different thread. If email queue is full or sending has failed - the email will be lost. Email queue can fill up if rate of scheduling emails is greater than the rate of SMTP sending.

Implementation is not performing any throttling and it is responsibility of the caller to properly throttle the emails, if necessary.

Note that this feature only available in Enterprise Edition.

Parameters:

subj - Subject of the email.

body - Body of the email.

html - If true the email body will have MIME html subtype.

Returns:

Email's future. You can use this future to check on the status of the email. If future completes ok and its result value is true email was successfully sent. In all other cases - sending process has failed.

See Also:

Grid.isSmtpEnabled(), Grid.sendAdminEmail(String, String, boolean), GridConfiguration.getAdminEmails()

sendAdminEmail

@GridEnterpriseFeature
void sendAdminEmail(String subj,
                                          String body,
                                          boolean html)
                    throws GridException

Sends given email to all configured admin emails. If no admin emails are configured this method is no-op. If SMTP is not configured this method is no-op.

Note that this method will return only if email is successfully sent. In case of sending failure it will throw exception. This method will block until either email is successfully sent or exception is thrown due to failure.

Implementation is not performing any throttling and it is responsibility of the caller to properly throttle the emails, if necessary.

Note that this feature only available in Enterprise Edition.

Throws:

GridException - Thrown in case when sending has failed.

Parameters:

subj - Subject of the email.

body - Body of the email.

html - If true the email body will have MIME html subtype.

See Also:

Grid.isSmtpEnabled(), Grid.sendAdminEmailAsync(String, String, boolean), GridConfiguration.getAdminEmails()

log

GridLogger log()

Gets grid's logger.

Returns:

Grid's logger.

isEnterprise

boolean isEnterprise()

Tests whether or not this GridGain runtime runs on an enterprise edition. This method is primarily for informational purpose.

Returns:

True for enterprise edition, false - for community edition.

See Also:

GridEnterpriseFeatureException, GridEnterpriseOnly

rich

GridRichNode rich(GridNode node)

Creates grid rich node wrapped around given thin node.

Note that in most cases end user should not have to use this method as most of the APIs returning rich nodes already. This functionality exists for easier migration from previous versions as well as for internal purposes.

Note also that GridGain caches rich instances internal and for same thin node it will always return the same rich node.

Parameters:

node - Thin node to wrap.

Returns:

Rich node.

waitForEvent

GridEvent waitForEvent(long timeout,
                       @Nullable
                       Runnable c,
                       @Nullable
                       GridPredicate<? super GridEvent> p,
                       @Nullable
                       int... types)
                       throws GridException

Blocks and waits for the local event.

This is one of the two similar methods providing different semantic for waiting for events. One method (this one) uses passed in optional continuation so that caller can pass a logic that emits the event, and another method returns future allowing caller a more discrete control.

This method returns when either event of specified type has been generated and passed the optional predicate, if any, or the timeout has elapsed. Note that some local events are generated in response to the actions on remote nodes.

This method encapsulates an important paradigm as many operations in GridGain cause local events to be generated even for the operations that may happen on the remote nodes. This method provides convenient one-stop blocking and waiting functionality for such cases.

Throws:

GridException - Thrown only when continuation throws any exception.

Parameters:

timeout - Timeout in milliseconds. If timeout value is less than or equal to zero, the method will not wait at all and will return immediately.

c - Optional continuation. If specified it will ba called right after the event listener is registered but before the wait countdown started. This parameter is important when you need to avoid a window between execution of an operation that can cause the event and settings the event listener. Passing this operation as continuation into this method allows to avoid this window.

p - Optional filtering predicate. Only if predicates evaluates to true will the event end the wait. Note that events of provided types only will be fed to the predicate.

types - Types of the events to wait for.

Returns:

Grid event if one occurred or null if the call got timed out.

See Also:

Grid.waitForEventAsync(GridPredicate, int...)

waitForEventAsync

GridFuture<GridEvent> waitForEventAsync(@Nullable
                                        GridPredicate<? super GridEvent> p,
                                        @Nullable
                                        int... types)

Gets event future that allows for asynchronous waiting for the specified events.

This is one of the two similar methods providing different semantic for waiting for events. One method uses passed in optional continuation so that caller can pass a logic that emits the event, and another method (this one) returns future allowing caller a more discrete control.

This method returns a future which by calling one of its get methods will block and wait for the specified event (either indefinitely or with provided timeout). Note that you need to call this method to acquire the future before emitting the event itself. This way you can avoid the window when event is emitted but no listener is set for it.

This method encapsulates an important paradigm as many operations in GridGain cause local events to be generated even for the operations that may happen on the remote nodes. This method provides convenient one-stop blocking and waiting functionality for such cases.

Parameters:

p - Optional filtering predicate. Only if predicates evaluates to true will the event end the wait. Note that events of provided types only will be fed to the predicate.

types - Types of the events to wait for.

Returns:

Grid event future.

See Also:

Grid.waitForEvent(long, Runnable, GridPredicate, int...)

topologyHash

long topologyHash(Iterable<? extends GridNode> nodes)

This method calculates hash value of the given set of nodes (a topology). Topology hash can be used in applications with optimistic locking scenario that relying on unchanged topology during a long operation.

Note that since GridGain topology architecture is peer-to-peer (without centralized coordination) there is still a small window in which different nodes would have different version for the same topology. Therefore, this version cannot be used in strict ACID context. Values returned by this method are not guaranteed to be sequential. Standard implementation uses CRC32 hash method.

Parameters:

nodes - Collection of grid nodes. Note that this can be either full topology or any subset of it.

Returns:

8-byte topology hash value.

addLocalEventListener

void addLocalEventListener(GridLocalEventListener lsnr,
                           int[] types)

Adds an event listener for local events.

Note that by default all events in GridGain are enabled and therefore generated and stored by whatever event storage SPI is configured. GridGain can and often does generate thousands events per seconds under the load and therefore it creates a significant additional load on the system. If these events are not needed by the application this load is unnecessary and leads to significant performance degradation.

It is highly recommended to enable only those events that your application logic requires by using either GridConfiguration.getExcludeEventTypes() or GridConfiguration.getIncludeEventTypes() methods in GridGain configuration. Note that certain events are required for GridGain's internal operations and such events will still be generated but not stored by event storage SPI if they are disabled in GridGain configuration.

Note also that since event types are defined as integer the unknown (invalid) event types cannot be detected and therefore will be ignored (because there is no way to know which user-defined types are used).

Throws:

GridRuntimeException - Thrown in case when passed in array of event types is empty.

Parameters:

lsnr - Event listener for local events to add.

types - Event types for which this listener will be notified. If this array is empty an exception will be thrown.

NOTE: subscribing to large set of events will impose significant performance penalty.

See Also:

GridEvent, GridEventType, Grid.addLocalEventListener(GridLocalEventListener, int, int...)

addLocalEventListener

void addLocalEventListener(GridLocalEventListener lsnr,
                           int type,
                           @Nullable
                           int... types)

Adds an event listener for local events.

Note that by default all events in GridGain are enabled and therefore generated and stored by whatever event storage SPI is configured. GridGain can and often does generate thousands events per seconds under the load and therefore it creates a significant additional load on the system. If these events are not needed by the application this load is unnecessary and leads to significant performance degradation.

It is highly recommended to enable only those events that your application logic requires by using either GridConfiguration.getExcludeEventTypes() or GridConfiguration.getIncludeEventTypes() methods in GridGain configuration. Note that certain events are required for GridGain's internal operations and such events will still be generated but not stored by event storage SPI if they are disabled in GridGain configuration.

Note that unlike its sibling method this method never throws an exception because its signature guarantees that there is at least one event type to subscribe for.

Note also that since event types are defined as integer the unknown (invalid) event types cannot be detected and therefore will be ignored (because there is no way to know which user-defined types are used).

Parameters:

lsnr - Event listener for local events to add.

type - Event type for which this listener will be notified.

types - Optional event types for which this listener will be notified.

See Also:

GridEvent, GridEventType, Grid.addLocalEventListener(GridLocalEventListener, int[])

removeLocalEventListener

boolean removeLocalEventListener(GridLocalEventListener lsnr,
                                 @Nullable
                                 int... types)

Removes local event listener.

Parameters:

lsnr - Local event listener to remove.

types - Types of events for which to remove listener. If not specified, then listener will be removed for all types it was registered for.

Returns:

true if listener was removed, false otherwise.

See Also:

GridEventType, GridEvent

addMessageListener

@Deprecated
void addMessageListener(GridMessageListener lsnr,
                                   @Nullable
                                   GridPredicate<Object>... p)

Deprecated.

Register a message listener to receive messages that are sent by remote nodes and which pass all provided message filters. See GridProjection.listen(GridPredicate2[]) method for more convenient message listening API.

Parameters:

lsnr - Message listener to register.

p - Message filter predicates. If none is provided - every message received will be delivered to registered listener.

See Also:

GridProjection.listen(GridPredicate2[]), GridProjection.send(Collection, GridPredicate[]), GridProjection.send(Object, GridPredicate[]), Grid.removeMessageListener(GridMessageListener)

removeMessageListener

@Deprecated
boolean removeMessageListener(GridMessageListener lsnr)

Deprecated.

Removes a previously registered message listener. See GridProjection.listen(GridPredicate2[]) method for more convenient message listening API.

Parameters:

lsnr - Message listener to remove.

Returns:

true of message listener was removed, false if it was not previously registered.

See Also:

GridProjection.listen(GridPredicate2[]), Grid.addMessageListener(GridMessageListener, GridPredicate[]), GridProjection.send(Collection, GridPredicate[]), GridProjection.send(Object, GridPredicate[])

localNode

GridRichNode localNode()

Gets local grid node.

Returns:

Local grid node.

runLocal

GridFuture<?> runLocal(@Nullable
                       Runnable r)
                       throws GridException

Executes given closure on internal system thread pool asynchronously.

Note that class GridAbsClosure implements Runnable and class GridOutClosure implements Callable interface. Note also that class GridFunc and typedefs provide rich APIs and functionality for closures and predicates based processing in GridGain. While Java interfaces Runnable and Callable allow for lowest common denominator for APIs - it is advisable to use richer Functional Programming support provided by GridGain available in org.gridgain.grid.lang package.

Throws:

GridException - Thrown in case of rejected execution by internal system thread pool.

Parameters:

r - Runnable to execute. If null - this method is no-op.

Returns:

Future for this execution.

See Also:

Grid.callLocal(Callable), GridAbsClosure

callLocal

<R> GridFuture<R> callLocal(@Nullable
                            Callable<R> c)
                        throws GridException

Executes given callable on internal system thread pool asynchronously.

Note that class GridAbsClosure implements Runnable and class GridOutClosure implements Callable interface. Note also that class GridFunc and typedefs provide rich APIs and functionality for closures and predicates based processing in GridGain. While Java interfaces Runnable and Callable allow for lowest common denominator for APIs - it is advisable to use richer Functional Programming support provided by GridGain available in org.gridgain.grid.lang package.

Throws:

GridException - Thrown in case of rejected execution by internal system thread pool.

Type Parameters:

R - Type of the return value for the closure.

Parameters:

c - Callable to execute. If null - this method is no-op.

Returns:

Future for this execution.

See Also:

Grid.runLocal(Runnable), GridOutClosure

scheduleLocal

GridScheduleFuture<?> scheduleLocal(@Nullable
                                    Runnable c,
                                    String pattern)
                                    throws GridException

Schedules closure for execution using local cron-based scheduling.

Here's an example of scheduling a closure that broadcasts a message to all nodes five times, once every minute, with initial delay in two seconds:

 G.grid().scheduleLocal(
     new CA() { // CA is a type alias for GridAbsClosure.
         @Override public void apply() {
             try {
                 g.run(BROADCAST, F.println("Hello Node! :)");
             }
             catch (GridException e) {
                 throw new GridClosureException(e);
             }
         }
     }, "{2, 5} * * * * *" // 2 seconds delay with 5 executions only.
 );
 

Note that class GridAbsClosure implements Runnable and class GridOutClosure implements Callable interface. Note also that class GridFunc and typedefs provide rich APIs and functionality for closures and predicates based processing in GridGain. While Java interfaces Runnable and Callable allow for lowest common denominator for APIs - it is advisable to use richer Functional Programming support provided by GridGain available in org.gridgain.grid.lang package.

Throws:

GridException - Thrown in case of any errors.

Parameters:

c - Closure to schedule to run as a background cron-based job. If null - this method is no-op.

pattern - Scheduling pattern in UNIX cron format with optional prefix {n1, n2} where n1 is delay of scheduling in seconds and n2 is the number of execution. Both parameters are optional.

Returns:

Scheduled execution future.

scheduleLocal

<R> GridScheduleFuture<R> scheduleLocal(@Nullable
                                        Callable<R> c,
                                        String pattern)
                                    throws GridException

Schedules closure for execution using local cron-based scheduling.

Here's an example of scheduling a closure that broadcasts a message to all nodes five times, once every minute, with initial delay in two seconds:

 G.grid().scheduleLocal(
     new CO() { // CO is a type alias for GridOutClosure.
         @Override public String apply() {
             try {
                 g.run(BROADCAST, F.println("Hello Node! :)");

                 return "OK";
             }
             catch (GridException e) {
                 throw new GridClosureException(e);
             }
         }
     }, "{2, 5} * * * * *" // 2 seconds delay with 5 executions only.
 );
 

Note that class GridAbsClosure implements Runnable and class GridOutClosure implements Callable interface. Note also that class GridFunc and typedefs provide rich APIs and functionality for closures and predicates based processing in GridGain. While Java interfaces Runnable and Callable allow for lowest common denominator for APIs - it is advisable to use richer Functional Programming support provided by GridGain available in org.gridgain.grid.lang package.

Throws:

GridException - Thrown in case of any errors.

Parameters:

c - Closure to schedule to run as a background cron-based job. If null - this method is no-op.

pattern - Scheduling pattern in UNIX cron format with optional prefix {n1, n2} where n1 is delay of scheduling in seconds and n2 is the number of execution. Both parameters are optional.

Returns:

Scheduled execution future.

nodeLocal

<K,V> GridNodeLocal<K,V> nodeLocal()

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.

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

deployTask

void deployTask(Class<? extends GridTask> taskCls)
                throws GridException

Explicitly deploys given grid task on the local node. Upon completion of this method, a task can immediately be executed on the grid, considering that all participating remote nodes also have this task deployed. If peer-class-loading is enabled (see GridConfiguration.isPeerClassLoadingEnabled()), then other nodes will automatically deploy task upon execution request from the originating node without having to manually deploy it.

Another way of class deployment which is supported is deployment from local class path. Class from local class path has a priority over P2P deployed. Following describes task class deployment:

• If peer class loading is enabled (see GridConfiguration.isPeerClassLoadingEnabled())
  Task class loaded from local class path if it is not defined as P2P loaded (see GridConfiguration.getPeerClassLoadingClassPathExclude()).
  If there is no task class in local class path or task class needs to be peer loaded it is downloaded from task originating node.
• If peer class loading is disabled (see GridConfiguration.isPeerClassLoadingEnabled())
  Check that task class was deployed (either as GAR or explicitly) and use it.
  If task class was not deployed then we try to find it in local class path by task name. Task name should correspond task class name.
  If task has custom name (that does not correspond task class name) and this task was not deployed before then exception will be thrown.

Note that this is an alternative deployment method additionally to deployment SPI that provides more formal method of deploying a task, e.g. deployment of GAR files and/or URI-based deployment. See GridDeploymentSpi for detailed information about grid task deployment.

Note that class can be deployed multiple times on remote nodes, i.e. re-deployed. GridGain maintains internal version of deployment for each instance of deployment (analogous to class and class loader in Java). Execution happens always on the latest deployed instance (latest that is on the node where execution request is originated). This allows a very convenient development model when a developer can execute a task on the grid from IDE, then realize that he made a mistake, stop his node in IDE, fix mistake and re-execute the task. Grid will automatically detect that task got renewed and redeploy it on all remote nodes upon execution.

This method has no effect if the class passed in was already deployed. Implementation checks for this condition and returns immediately.

Throws:

GridException - If task is invalid and cannot be deployed.

Parameters:

taskCls - Task class to deploy. If task class has GridTaskName annotation, then task will be deployed under a name specified within annotation. Otherwise, full class name will be used as task's name.

See Also:

GridDeploymentSpi

deployTask

void deployTask(Class<? extends GridTask> taskCls,
                ClassLoader clsLdr)
                throws GridException

Explicitly deploys given grid task on the local node. Upon completion of this method, a task can immediately be executed on the grid, considering that all participating remote nodes also have this task deployed. If peer-class-loading is enabled (see GridConfiguration.isPeerClassLoadingEnabled()), then other nodes will automatically deploy task upon execution request from the originating node without having to manually deploy it.

Another way of class deployment which is supported is deployment from local class path. Class from local class path has a priority over P2P deployed. Following describes task class deployment:

• If peer class loading is enabled (see GridConfiguration.isPeerClassLoadingEnabled())
  Task class loaded from local class path if it is not defined as P2P loaded (see GridConfiguration.getPeerClassLoadingClassPathExclude()).
  If there is no task class in local class path or task class needs to be peer loaded it is downloaded from task originating node using provided class loader.
• If peer class loading is disabled (see GridConfiguration.isPeerClassLoadingEnabled())
  Check that task class was deployed (either as GAR or explicitly) and use it.
  If task class was not deployed then we try to find it in local class path by task name. Task name should correspond task class name.
  If task has custom name (that does not correspond task class name) and this task was not deployed before then exception will be thrown.

Note that this is an alternative deployment method additionally to deployment SPI that provides more formal method of deploying a task, e.g. deployment of GAR files and/or URI-based deployment. See GridDeploymentSpi for detailed information about grid task deployment.

Note that class can be deployed multiple times on remote nodes, i.e. re-deployed. GridGain maintains internal version of deployment for each instance of deployment (analogous to class and class loader in Java). Execution happens always on the latest deployed instance (latest that is on the node where execution request is originated). This allows a very convenient development model when a developer can execute a task on the grid from IDE, then realize that he made a mistake, stop his node in IDE, fix mistake and re-execute the task. Grid will automatically detect that task got renewed and redeploy it on all remote nodes upon execution.

This method has no effect if the class passed in was already deployed. Implementation checks for this condition and returns immediately.

Throws:

GridException - If task is invalid and cannot be deployed.

Parameters:

taskCls - Task class to deploy. If task class has GridTaskName annotation, then task will be deployed under a name specified within annotation. Otherwise, full class name will be used as task's name.

clsLdr - Task resources/classes class loader. This class loader is in charge of loading all necessary resources.

See Also:

GridDeploymentSpi

localTasks

Map<String,Class<? extends GridTask<?,?>>> localTasks(@Nullable
                                                      GridPredicate<? super Class<? extends GridTask<?,?>>>... p)

Gets map of all locally deployed tasks keyed by their task name satisfying all given predicates. If no tasks were locally deployed, then empty map is returned. If no predicates provided - all locally deployed tasks, if any, will be returned.

Parameters:

p - Set of filtering predicates. If no predicates provided - all locally deployed tasks, if any, will be returned.

Returns:

Map of locally deployed tasks keyed by their task name.

undeployTask

void undeployTask(String taskName)
                  throws GridException

Makes the best attempt to undeploy a task from the whole grid. Note that this method returns immediately and does not wait until the task will actually be undeployed on every node.

Note that GridGain maintains internal versions for grid tasks in case of redeployment. This method will attempt to undeploy all versions on the grid task with given name.

Throws:

GridException - Thrown if undeploy failed.

Parameters:

taskName - Name of the task to undeploy. If task class has GridTaskName annotation, then task was deployed under a name specified within annotation. Otherwise, full class name should be used as task's name.

localEvents

Collection<GridEvent> localEvents(@Nullable
                                  GridPredicate<? super GridEvent>... p)

Queries local node for events using passed-in predicate filters for event selection.

Parameters:

p - Mandatory predicates to filter events. All predicates must be satisfied for the event to be returned.

Note: unlike other methods in GridGain APIs if no predicates is provided this method will return no results. This exception is made to avoid situation when all local events are erroneously returned. Returning all local events may result in creating collection with tens of thousands elements seriously compromising the system's performance.

Returns:

Collection of grid events found on local node.

See Also:

PE

recordLocalEvent

void recordLocalEvent(GridEvent evt)

Records locally generated event. Registered local listeners will be notified, if any. This event can be obtained from the remote nodes by performing a distributed query using GridProjection.remoteEvents(GridPredicate, long, GridPredicate[]) method.

Parameters:

evt - Locally generated event.

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 GridFactory documentation for information on how to start named grids.

Returns:

Name of the grid, or null for default grid.

version

String version()

Ges version string of the GridGain instance. This method is for information purpose only.

Returns:

GridGain version string (excluding the build number).

See Also:

Grid.build()

build

String build()

Gets build number of this GridGain instance. This method is for information purpose only.

Returns:

GridGain instance build number.

See Also:

Grid.version()

copyright

String copyright()

Copyright statement for GridGain code.

Returns:

Legal copyright statement for GridGain code.

cache

<K,V> GridCache<K,V> cache(@Nullable
                           String name)

Gets the cache instance for the given name if one is configured or null otherwise.

Type Parameters:

K - Key type.

V - Value type.

Parameters:

name - Cache name.

Returns:

Cache instance for given name or null if one does not exist.

cache

<K,V> GridCache<K,V> cache()

Gets default cache instance if one is configured or null otherwise. The GridCacheProjection.name() method on default instance returns null.

Type Parameters:

K - Key type.

V - Value type.

Returns:

Default cache instance.

caches

Collection<GridCache<?,?>> caches(@Nullable
                                  GridPredicate<? super GridCache<?,?>>... p)

Gets configured cache instance that satisfy all provided predicates. If no predicates provided - all configured caches will be returned.

Parameters:

p - Predicates. If none provided - all configured caches will be returned.

Returns:

Configured cache instances that satisfy all provided predicates.

writeToSwap

void writeToSwap(@Nullable
                 String space,
                 Object key,
                 @Nullable
                 Object val,
                 @Nullable
                 ClassLoader ldr)
                 throws GridException

Writes given data to specified swap space.

Throws:

GridException - Thrown in case of any errors.

Parameters:

space - Optional swap space name. If null is passed - global swap space will be used.

key - Data key.

val - Data value.

ldr - Class loader (optional).

readFromSwap

@Nullable
<T> T readFromSwap(@Nullable
                            String space,
                            Object key,
                            @Nullable
                            ClassLoader ldr)
               throws GridException

Reads data stored by Grid.writeToSwap(String, Object, Object, ClassLoader) method.

Throws:

GridException - Thrown in case of any errors.

Parameters:

space - Optional swap space name. If null is passed - global swap space will be used.

key - Data key.

ldr - Class loader (optional).

Returns:

Data read from swap space or null if no data was stored.

removeFromSwap

void removeFromSwap(@Nullable
                    String space,
                    Object key,
                    @Nullable
                    GridInClosure<Object> c,
                    @Nullable
                    ClassLoader ldr)
                    throws GridException

Removes data stored by Grid.writeToSwap(String, Object, Object, ClassLoader) method.

Throws:

GridException - Thrown in case of any errors.

Parameters:

space - Optional swap space name. If null is passed - global swap space will be used.

key - Data key.

c - Optional closure that takes removed value and executes after actual removing. If there was no value in storage the closure is not executed.

ldr - Class loader (optional).

clearSwapSpace

void clearSwapSpace(@Nullable
                    String space)
                    throws GridException

Clears all entry from the specified swap space.

Throws:

GridException - Thrown in case of any errors.

Parameters:

space - Optional swap space name. If null is passed - global swap space will be used.

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.