Execution (Apache Geode 1.13.0)
Date: 2020-09-07

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(Function function, long timeout, TimeUnit unit)` Executes the function instance provided.
    `ResultCollector<OUT,AGG>` | `execute(String functionId)` Executes the function using its id.
    `ResultCollector<OUT,AGG>` | `execute(String functionId, long timeout, TimeUnit unit)` Executes the function using its id with the specified timeout.
    `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(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(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:
        `IllegalArgumentException` - if filter passed is null.
        `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:
        `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:
        `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:
        `IllegalArgumentException` - if `ResultCollector` is null
      Since:
        GemFire 6.0
      See Also:
        `ResultCollector`

    - #### execute

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

      Executes the function using its id. When executed from a client, it blocks until all results have been received or the global timeout (gemfire.CLIENT_FUNCTION_TIMEOUT Java property), if set, has expired.

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

      Parameters:
        `functionId` - id of the function 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

    - #### execute

          ResultCollector<OUT,AGG> execute(String functionId,
                                           long timeout,
                                           TimeUnit unit)
                                    throws FunctionException

      Executes the function using its id with the specified timeout. It blocks until all results have been received or the timeout has expired.

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

      Parameters:
        `functionId` - id of the function to execute
        `timeout` - time to wait for the operation to finish before timing out
        `unit` - timeout unit
      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:
        `FunctionException`
      Since:
        Geode 1.11

    - #### execute

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

      Executes the function instance provided. When executed from a client, it blocks until all results have been received or the global timeout (gemfire.CLIENT_FUNCTION_TIMEOUT Java property), if set, has expired.

      `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

    - #### execute

          ResultCollector<OUT,AGG> execute(Function function,
                                           long timeout,
                                           TimeUnit unit)
                                    throws FunctionException

      Executes the function instance provided. It blocks until all results have been received or the timeout has expired.

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

      Parameters:
        `function` - instance to execute
        `timeout` - time to wait for the operation to finish before timing out
        `unit` - timeout unit
      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:
        Geode 1.11