Package org.apache.geode.cache.execute

The org.apache.geode.cache.execute package provides APIs used for function execution on gemfire system members.

See: Description

Interface Summary

Interface	Description
Execution<IN,OUT,AGG>	Provides methods to build the context for the execution of a Function .
Function<T>	Defines the interface a user defined function implements.
FunctionContext<T1>	Defines the execution context of a Function.
RegionFunctionContext	Defines the execution context of a data dependent Function.
ResultCollector<T,S>	Defines the interface for a container that gathers results from function execution. GemFire provides a default implementation for ResultCollector.
ResultSender<T>	Provides methods to send results back to the ResultCollector.

Class Summary

Class	Description
FunctionAdapter	Deprecated Use Function instead.
FunctionService	Provides the entry point into execution of user defined Functions.

Exception Summary

Exception	Description
EmptyRegionFunctionException	Exception to indicate that Region is empty for data aware functions.
FunctionException	Thrown to indicate an error or exceptional condition during the execution of Functions in GemFire.
FunctionInvocationTargetException	Thrown if one of the function execution nodes goes away or cache is closed.

Package org.apache.geode.cache.execute Description

The org.apache.geode.cache.execute package provides APIs used for function execution on gemfire system members.

GemFire's Function Execution Service supports execution of user-defined methods on targeted GemFire system members.
The fundamental premise is to route the function transparently to the GemFire system member that hosts the data subset required by the application function and avoid moving data around on the network. Application function can be executed on just one fabric node, executed in parallel on a subset of nodes or in parallel across all the nodes.

The Function Execution Service API is based on the following classes and interfaces which work together to provide the function execution capability. The API allows execution of functions that are "data dependent" or "data independent". Data dependent functions are functions that need access to the local data set, on the targeted member.

• The FunctionService class provides methods to execute functions on targeted GemFire system members.
• Functions are java classes that implement the Function interface. Functions can be registered with the Function Execution Service.
• The application obtains the execution object Execution and uses its methods to target execution.
• Calling the execute() method on the Execution object starts the execution on the targeted Gemfire system member(s).
• Upon execution on the targeted member(s), a FunctionContext object is passed into the execute() method. Application developer can use FunctionContext to get the arguments passed into the execution of the function and references to the data regions providing access to the local dataset as well as colocated dataset on the member.
• The Application developer can get ResultSender from FunctionContext and send the results in parts to ResultCollector. As the result is sent, it is added to the ResultCollector immediately. By default GemFire returns a ResultCollector, whose getResult() method blocks until all the results have been obtained from the function execution. To stop ResultCollector from waiting for more results a last result must be sent.

Example of a "data dependent" execution using the Function Execution Service

    Region region;
    Set keySet = Collections.singleton("myKey");
    Function multiGetFunction;
    Object args;
    ResultCollector rc = FunctionService.onRegion(region)
                                        .setArguments(args)
                                        .withFilter(keySet)
                                        .withCollector(new MyCustomResultCollector())
                                        .execute(multiGetFunction.getId());
    // Application can do something else here before retrieving the result
    // It can even get deal with partial results which it will get in
    // MyCustomResultCollector.addResult().
    
    Object functionResult = rc.getResult();

Example of a Function execution on a set of regions

    Region region1, region2, region3;
    Set s = new HashSet();
    s.add(region1);
    s.add(region2);
    s.add(region3);
    Function multiGetFunction;
    Object args;
    ResultCollector rc = FunctionService.onRegions(s)
                                        .setArguments(args)
                                        .withCollector(new MyCustomResultCollector())
                                        .execute(multiGetFunction.getId());
    // Application can get the handle of all the regions at the node it is executing on.
    // This way it can get the handle of data in an efficient way.
    Object functionResult = rc.getResult();

Example of a "data independent" execution using the Function Execution Service

    DistributedSystem ds;
    Function memberSetupFunction;
    Object args;
    ResultCollector rc = FunctionService.onMembers(ds)
                                        .setArguments(args)
                                        .execute(memberSetupFunction.getId());
    //Application can do something else here before retrieving the result
    Object functionResult = rc.getResult();

Example of a "Function" to be executed which sends result to ResultCollector using ResultSender.

        public class MYFunction extends FunctionAdapter {
        
          public void execute(FunctionContext context) {
                for(int i =0 ;i< 10; i++)        
                        context.getResultSender().sendResult(i);
                context.getResultSender.lastResult(10);
          }
        
          public String getId() {
            return "MYFunction";
          }
        
          public boolean hasResult() {
            return true;
          }
        
        }

Some scenarios where function execution can be useful:

1. Any arbitrary aggregation operation that requires iteration over local data sets done more efficiently through a single call to the cache server
2. Application wants to execute a server side behaviour.
3. Application wants to operate on many regions at a time. Like having function which need data from many regions. This can be achieved in an efficient way using function service.
4. Application wants to initialize some of its components once on each server which might be used later by executed functions, for example initialization of a 3rd party service.