org.apache.ignite.compute.gridify

## Annotation Type GridifySetToSet

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

  `GridifySetToSet` annotation allows 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.

  `GridifySetToSet` 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 annotation is to provide very simple and easy to use ForkJoin gridification for some often used use cases. Note that in a standard `Gridify` annotation the user has to write `ComputeTask` 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 1, R 2, ..., R n,}, where F (S 1, S 2, ..., S k) == {F (S 1), F (S 2), ..., F (S k)}` which defines a function whose result can be constructed as concatenation of results of the same function applied to subsets of the original set.

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

  - java.util.Collection
  - java.util.Iterator
  - java.util.Enumeration
  - java.lang.CharSequence
  - java array

  Note that when using `@GridifySetToSet` 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. In either case, Ignite must be able to serialize the state passed to remote node.

  # Java Example

  Example for these types of functions would be any function that is looking for a subset of data in a given input collection. For example:

       ...
       @GridifySetToSet(threshold = 2)
       public static Collection<Number> findAllPrimeNumbers(Collection<Number> input) {...}
       ...

  This function searches all elements in the input collection and returns another collection containing only prime numbers found in the original collection. We can split this collection into two sub-collection, find primes in each - and then simply concatenate two collections to get the final set of all primes.

  The formal definition of (or requirement for) such method:

  - Have return value of type Collection<T>
  - Have one and only one parameter of type Collection<T>
  - Order of Collection<T> parameter is irrelevant
  - Method can have as many other parameters as needed of any type except for Collection<T>
  - Logic of the method must allow for concatenation of results from the same method apply on a subset of the original collection

  # Jboss AOP

  The following configuration needs to be applied to enable JBoss byte code weaving. Note that Ignite is not shipped with JBoss and necessary libraries will have to be downloaded separately (they come standard if you have JBoss installed already):
  - The following JVM configuration must be present:
    - `-javaagent:[path to jboss-aop-jdk50-4.x.x.jar]`
    - `-Djboss.aop.class.path=[path to ignite.jar]`
    - `-Djboss.aop.exclude=org,com -Djboss.aop.include=org.apache.ignite.examples`
  - The following JARs should be in a classpath:
    - `javassist-3.x.x.jar`
    - `jboss-aop-jdk50-4.x.x.jar`
    - `jboss-aspect-library-jdk50-4.x.x.jar`
    - `jboss-common-4.x.x.jar`
    - `trove-1.0.2.jar`

  # AspectJ AOP

  The following configuration needs to be applied to enable AspectJ byte code weaving.
  - JVM configuration should include: `-javaagent:${IGNITE_HOME}/libs/aspectjweaver-1.7.2.jar`
  - META-INF/aop.xml file should be created and specified on the classpath. The file should contain Gridify aspects and needed weaver options.

  # 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(java.lang.Object)` for the object that has method with `GridifySetToSet` 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

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String` | `gridName` Deprecated. Use `igniteInstanceName()`. Nonempty `igniteInstanceName()` takes precedence.
    `String` | `igniteInstanceName`
    `Class<? extends GridifyInterceptor>` | `interceptor`
    `Class<? extends GridifyNodeFilter>` | `nodeFilter`
    `int` | `splitSize`
    `int` | `threshold`
    `long` | `timeout`

- - ### Element Detail

    - #### nodeFilter

          public abstract Class<? extends GridifyNodeFilter> nodeFilter

      Returns:
        Optional node filter to filter nodes participated in job split.
      Default:
        org.apache.ignite.compute.gridify.GridifyNodeFilter.class

  - - #### timeout

          public abstract long timeout

      Returns:
        Optional gridify task execution timeout. Default is `0` which indicates that task will not timeout.
      Default:
        0L

  - - #### threshold

          public abstract int threshold

      Returns:
        Optional parameter that defines the minimal value below which the execution will NOT be grid-enabled.
      Default:
        0

  - - #### splitSize

          public abstract int splitSize

      Returns:
        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 Ignite 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 `threshold()` value. In most cases, however, the optimal value for the split size is the `threshold()` value. For example, if input collection size is 100, number of nodes 10 and split size is set to 5 - Ignition 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) - Ignite 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

      Returns:
        Optional interceptor class.
      Default:
        org.apache.ignite.compute.gridify.GridifyInterceptor.class

  - - #### gridName

          @Deprecated
          public abstract String gridName

      Deprecated. Use `igniteInstanceName()`. Nonempty `igniteInstanceName()` takes precedence.
      Returns:
        Name of the grid to use. By default, no-name default grid is used. Refer to `Ignition` for information about named grids.
      Default:
        ""

  - - #### igniteInstanceName

          public abstract String igniteInstanceName

      Returns:
        Name of the Ignite instance to use. By default, no-name default Ignite instance is used. Refer to `Ignition` for information about named Ignite instances.
      Default:
        ""

2022 Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.12.0
Release Date | : January 10 2022