GridGain™ 4.3.1e
Enterprise "Big Data" Edition

org.gridgain.grid.gridify
Annotation Type GridifySetToValue


@Documented
@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface GridifySetToValue

GridifySetToValue annotation is the way to grid-enable existing code with specific semantics.

This annotation can be applied to any public method that needs to be grid-enabled, static or non-static. When this annotation is applied to a method, the method execution is considered to be grid-enabled. In general, the execution of this method can be transferred to another node in the grid, potentially splitting it into multiple subtasks to be executed in parallel on multiple grid nodes. But from the caller perspective this method still looks and behaves like a local apply. This is achieved by utilizing AOP-based interception of the annotated code and injecting all the necessary grid logic into the method execution.

GridifySetToValue used as extended version of Gridify annotation. It provides automated gridification of two popular types of mathematical functions that allow for "embarrassingly" simple parallelization (for example, find prime numbers in collection or find maximum in collection). The goal of this addition is to provide very simple and easy to use real ForkJoin gridification for some often used use cases. Note that in a standard Gridify annotation the user has to write GridTask to provide ForkJoin behavior. In a proposed design - the ForkJoin will be achieved automatically.

Let F be the function or a method in Java language and St be a set of values of type t or a typed Collection<T> in Java. Let also R be the result value. These are the types of functions that will be supported (defined in terms of their properties):

F (S 1, S 2, ..., S k) => R, where F (S 1, S 2, ..., S k) == F (F (S 1), F (S 2), ..., F (S k)) which basically defines a function over a set that produces the same result when applied recursively over its results for a subsets of the original set.

In definition above we used Collection<T> for the purpose of example. The following Java collections will have to be supported as return values or method parameters:

Note that when using @GridifySetToValue annotation the state of the whole instance will be serialized and sent out to remote node. Therefore the class must implement Serializable interface. If you cannot make the class Serializable, then you must implement custom grid task which will take care of proper state initialization (see HelloWorld - Gridify With State example). In either case, GridGain must be able to serialize the state passed to remote node.

Java Example

Example for these types of functions would be any aggregate function returning single value from the multiple inputs. For example:

 ...
 @GridifySetToValue(threshold = 2)
 public static Number findMaxValue(Collection<Number> input);
 ...
 
Method findMaxValuefindMaxValue simply traverses the input collection and finds the maximum element in. If we split this collection into two sub-collections, for example, and find maximums in each - we can then apply the same method to the collection of two just found maximums to find the overall maximum elements of the original collection. The formal definition of (or requirement for) such method:

Jboss AOP

The following configuration needs to be applied to enable JBoss byte code weaving. Note that GridGain is not shipped with JBoss and necessary libraries will have to be downloaded separately (they come standard if you have JBoss installed already):

AspectJ AOP

The following configuration needs to be applied to enable AspectJ byte code weaving.

Spring AOP

Spring AOP framework is based on dynamic proxy implementation and doesn't require any specific runtime parameters for online weaving. All weaving is on-demand and should be performed by calling method GridifySpringEnhancer.enhance(Object) for the object that has method with GridifySetToValue annotation.

Note that this method of weaving is rather inconvenient and AspectJ or JBoss AOP is recommended over it. Spring AOP can be used in situation when code augmentation is undesired and cannot be used. It also allows for very fine grained control of what gets weaved.

 

Optional Element Summary
 String gridName
          Name of the grid to use.
 Class<? extends GridifyInterceptor> interceptor
          Optional interceptor class.
 Class<? extends GridifyNodeFilter> nodeFilter
          Optional node filter to filter nodes participated in job split.
 int splitSize
          Optional parameter that defines a split size.
 int threshold
          Optional parameter that defines the minimal value below which the execution will NOT be grid-enabled.
 long timeout
          Optional gridify task execution timeout.
 

nodeFilter

public abstract Class<? extends GridifyNodeFilter> nodeFilter
Optional node filter to filter nodes participated in job split.

Default:
org.gridgain.grid.gridify.GridifyNodeFilter.class

timeout

public abstract long timeout
Optional gridify task execution timeout. Default is 0 which indicates that task will not timeout.

Default:
0L

threshold

public abstract int threshold
Optional parameter that defines the minimal value below which the execution will NOT be grid-enabled.

Default:
0

splitSize

public abstract int splitSize
Optional parameter that defines a split size. Split size in other words means how big will be the sub-collection that will travel to remote nodes. Note that this is NOT a dynamic setting and you have to set the split size up front. This may look as a deficiency but GridGain will properly handle this case by giving more than one sub-collection to a specific node (as defined by load balancing SPI in use).

This value should be greater than zero and can be less, equal or greater than GridifySetToValue.threshold() value. In most cases, however, the optimal value for the split size is the GridifySetToValue.threshold() value. For example, if input collection size is 100, number of nodes 10 and split size is set to 5 - GridGain will submit 2 sub-collections of 5 elements each to each node (provided in order by load balancing SPI).

By default (when split size is zero) - GridGain will automatically determine the split size based on number of nodes and collection size - if collection size is available (not an iterator). If collection size cannot be determined - the split size will default to threshold. If threshold is not set - a runtime exception will be thrown.

Default:
0

interceptor

public abstract Class<? extends GridifyInterceptor> interceptor
Optional interceptor class.

Default:
org.gridgain.grid.gridify.GridifyInterceptor.class

gridName

public abstract String gridName
Name of the grid to use. By default, no-name default grid is used. Refer to GridFactory for information about named grids.

Default:
""

GridGain™ 4.3.1e
Enterprise "Big Data" Edition

GridGain - In-Memory Big Data
Enterprise "Big Data" Edition, ver. 4.3.1e.10112012
2012 Copyright © GridGain Systems
Follow us:   Follow GridGain on Github Join GridGain User Group Follow GridGain on Twitter Follow GridGain on Vimeo