org.apache.geode.cache.execute

## Interface Execution<IN,OUT,AGG>

- Type Parameters:
    `IN` - The type of the argument passed into the function, if any
    `OUT` - The type of results sent by the function
    `AGG` - The type of the aggregated result returned by the ResultCollector

      public interface Execution<IN,OUT,AGG>

  Provides methods to build the context for the execution of a `Function` . A Context describes the environment in which the `Execution` will take place.

  This interface is implemented by GemFire. To obtain an instance of it use `FunctionService`.

  Since:
    GemFire 6.0
  See Also:
    `FunctionService`, `Function`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `ResultCollector<OUT,AGG>` | `execute(Function function)` Executes the function instance provided.
    `ResultCollector<OUT,AGG>` | `execute(java.lang.String functionId)` Executes the function using its id
    `Execution<IN,OUT,AGG>` | `setArguments(IN args)` Specifies the user data passed to the function when it is executed.
    `Execution<IN,OUT,AGG>` | `withArgs(IN args)` Deprecated. use `setArguments(Object)` instead
    `Execution<IN,OUT,AGG>` | `withCollector(ResultCollector<OUT,AGG> rc)` Specifies the `ResultCollector` that will receive the results after the function has been executed.
    `Execution<IN,OUT,AGG>` | `withFilter(java.util.Set<?> filter)` Specifies a data filter of routing objects for selecting the GemFire members to execute the function on.

- - ### Method Detail

    - #### withFilter

          Execution<IN,OUT,AGG> withFilter(java.util.Set<?> filter)

      Specifies a data filter of routing objects for selecting the GemFire members to execute the function on.

      Applicable only for regions with `DataPolicy.PARTITION` DataPolicy. If the filter is null, it will execute on all data of the region.

      Parameters:
        `filter` - Set defining the data filter to be used for executing the function
      Returns:
        an Execution with the filter
      Throws:
        `java.lang.IllegalArgumentException` - if filter passed is null.
        `java.lang.UnsupportedOperationException` - if not called after `FunctionService.onRegion(org.apache.geode.cache.Region)`
      Since:
        GemFire 6.0

    - #### setArguments

          Execution<IN,OUT,AGG> setArguments(IN args)

      Specifies the user data passed to the function when it is executed. The function can retrieve these arguments using `FunctionContext.getArguments()`
      Parameters:
        `args` - user data passed to the function execution
      Returns:
        an Execution with args
      Throws:
        `java.lang.IllegalArgumentException` - if the input parameter is null
      Since:
        Geode 1.2

    - #### withArgs

          Execution<IN,OUT,AGG> withArgs(IN args)

      Deprecated. use `setArguments(Object)` instead
      Specifies the user data passed to the function when it is executed. The function can retrieve these arguments using `FunctionContext.getArguments()`
      Parameters:
        `args` - user data passed to the function execution
      Returns:
        an Execution with args
      Throws:
        `java.lang.IllegalArgumentException` - if the input parameter is null
      Since:
        GemFire 6.0

    - #### withCollector

          Execution<IN,OUT,AGG> withCollector(ResultCollector<OUT,AGG> rc)

      Specifies the `ResultCollector` that will receive the results after the function has been executed. Collector will receive results as they are sent from the `Function.execute(FunctionContext)` using `ResultSender`.
      Returns:
        an Execution with a collector
      Throws:
        `java.lang.IllegalArgumentException` - if `ResultCollector` is null
      Since:
        GemFire 6.0
      See Also:
        `ResultCollector`

    - #### execute

          ResultCollector<OUT,AGG> execute(java.lang.String functionId)
                                    throws FunctionException

      Executes the function using its id

      `Function.execute(FunctionContext)` is called on the instance retrieved using `FunctionService.getFunction(String)` on the executing member.

      Returns:
        ResultCollector to retrieve the results received. This is different object than the ResultCollector provided in `withCollector(ResultCollector)`. User has to use this reference to retrieve results.
      Throws:
        `LowMemoryException` - if the `Function.optimizeForWrite()` returns true and there is a low memory condition
        `FunctionException`
      Since:
        GemFire 6.0

    - #### execute

          ResultCollector<OUT,AGG> execute(Function function)
                                    throws FunctionException

      Executes the function instance provided.

      `Function.execute(FunctionContext)` is called on the de-serialized instance on the executing member.

      Parameters:
        `function` - instance to execute
      Returns:
        ResultCollector to retrieve the results received. This is different object than the ResultCollector provided in `withCollector(ResultCollector)`. User has to use this reference to retrieve results.
      Throws:
        `LowMemoryException` - if the `Function.optimizeForWrite()` returns true and there is a low memory condition
        `FunctionException`
      Since:
        GemFire 6.0