Function (Apache Geode 1.13.3)
Date: 2021-06-22

org.apache.geode.cache.execute

## Interface Function<T>

- All Superinterfaces:
    Identifiable<String>, Serializable
  All Known Implementing Classes:
    BootstrappingFunction, CliFunction, CreateRegionFunction, FunctionAdapter, RegionSizeFunction, TouchPartitionedRegionEntriesFunction, TouchReplicatedRegionEntriesFunction
  Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

      @FunctionalInterface
      public interface Function<T>
      extends Identifiable<String>

  Defines the interface a user defined function implements. `Function`s can be of different types. Some can have results while others need not return any result. Some functions require writing in the targeted `Region` while some may just be read operations.

  Even though this interface extends Serializable, functions will only be serialized if they are not registered. For best performance it is recommended that you implement `getId()` to return a non-null identifier and register your function using `FunctionService.registerFunction(Function)` or the cache.xml `function` element.

  Since:
    GemFire 6.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `execute(FunctionContext<T> context)` The method which contains the logic to be executed.
    `default String` | `getId()` Return a unique function identifier, used to register the function with `FunctionService`
    `default Collection<ResourcePermission>` | `getRequiredPermissions(String regionName)` Returns the list of ResourcePermission this function requires.
    `default Collection<ResourcePermission>` | `getRequiredPermissions(String regionName, Object args)` Returns the list of ResourcePermission this function requires.
    `default boolean` | `hasResult()` Specifies whether the function sends results while executing.
    `default boolean` | `isHA()` Specifies whether the function is eligible for re-execution (in case of failure).
    `default boolean` | `optimizeForWrite()` Return true to indicate to GemFire the method requires optimization for writing the targeted `FunctionService.onRegion(org.apache.geode.cache.Region)` and any associated routing objects.

    - ### Methods inherited from interface org.apache.geode.lang.Identifiable

      `exists, find, remove`

- - ### Method Detail

    - #### hasResult

          default boolean hasResult()

      Specifies whether the function sends results while executing. The method returns false if no result is expected.

      If this method returns false, `ResultCollector.getResult()` throws `FunctionException`.

      If this method returns true, `ResultCollector.getResult()` blocks and waits for the result of function execution

      Returns:
        whether this function returns a Result back to the caller.
      Since:
        GemFire 6.0

    - #### execute

          void execute(FunctionContext<T> context)

      The method which contains the logic to be executed. This method should be thread safe and may be invoked more than once on a given member for a single `Execution`. The context provided to this function is the one which was built using Execution. The contexts can be data dependent or data-independent so user should check to see if the context provided in parameter is instance of `RegionFunctionContext`.
      Parameters:
        `context` - as created by `Execution`
      Since:
        GemFire 6.0

    - #### getId

          default String getId()

      Return a unique function identifier, used to register the function with `FunctionService`
      Specified by:
        `getId` in interface `Identifiable<String>`
      Returns:
        string identifying this function
      Since:
        GemFire 6.0

    - #### optimizeForWrite

          default boolean optimizeForWrite()

      Return true to indicate to GemFire the method requires optimization for writing the targeted `FunctionService.onRegion(org.apache.geode.cache.Region)` and any associated routing objects.

      Returning false will optimize for read behavior on the targeted `FunctionService.onRegion(org.apache.geode.cache.Region)` and any associated routing objects.

      This method is only consulted when Region passed to FunctionService#onRegion(org.apache.geode.cache.Region) is a partitioned region

      Returns:
        false if the function is read only, otherwise returns true
      Since:
        GemFire 6.0
      See Also:
        `FunctionService`

    - #### isHA

          default boolean isHA()

      Specifies whether the function is eligible for re-execution (in case of failure).
      Returns:
        whether the function is eligible for re-execution.
      Since:
        GemFire 6.5
      See Also:
        `FunctionContext.isPossibleDuplicate()`

    - #### getRequiredPermissions

          default Collection<ResourcePermission> getRequiredPermissions(String regionName)

      Returns the list of ResourcePermission this function requires.

      By default, functions require DATA:WRITE permission. If your function requires other permissions, you will need to override this method.

      Please be as specific as possible when you set the required permissions for your function e.g. if your function reads from a region, it would be good to include the region name in your permission. It's better to return "DATA:READ:regionName" as the required permission other than "DATA:READ", because the latter means only users with read permission on ALL regions can execute your function.

      All the permissions returned from this method will be ANDed together.

      Parameters:
        `regionName` - the region this function will be executed on. The regionName is optional and will only be present when the function is executed by an onRegion() executor. In other cases, it will be null. This method returns permissions appropriate to the context, independent of the presence of the regionName parameter.
      Returns:
        a collection of `ResourcePermission`s indicating the permissions required to execute the function.

    - #### getRequiredPermissions

          default Collection<ResourcePermission> getRequiredPermissions(String regionName,
                                                                        Object args)

      Returns the list of ResourcePermission this function requires.

      By default, functions require DATA:WRITE permission. If your function requires other permissions, you will need to override this method.

      Please be as specific as possible when you set the required permissions for your function e.g. if your function reads from a region, it would be good to include the region name in your permission. It's better to return "DATA:READ:regionName" as the required permission other than "DATA:READ", because the latter means only users with read permission on ALL regions can execute your function.

      All the permissions returned from this method will be ANDed together.

      Parameters:
        `regionName` - the region this function will be executed on. The regionName is optional and will only be present when the function is executed by an onRegion() executor. In other cases, it will be null. This method returns permissions appropriate to the context, independent of the presence of the regionName parameter.
        `args` - the arguments to the function.
      Returns:
        a collection of `ResourcePermission`s indicating the permissions required to execute the function.