ResultCollector (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode.cache.execute, interface: ResultCollector

Package org.apache.geode.cache.execute

# Interface ResultCollector<T,S>

public interface ResultCollector<T,S>

Defines the interface for a container that gathers results from function execution.
GemFire provides a default implementation for ResultCollector. Applications can choose to implement their own custom ResultCollector. A custom ResultCollector facilitates result sorting or aggregation. Aggregation functions like sum, minimum, maximum and average can also be applied to the result using a custom ResultCollector. Results arrive as they are sent using the `ResultSender.sendResult(Object)` and can be used as they arrive. To indicate that all results have been received `endResults()` is called.

Example:

      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
      Or it can have some logic in {addResult(DistributedMember, Object) to use the partial results.
      If it wants to see all the results it can use
      Object functionResult = rc.getResult();
      or
      Object functionResult = rc.getResult(timeout,TimeUnit);
      depending on if it wants to wait for all the results or wait for a timeout period.

GemFire provides default implementation of ResultCollector which collects results in Arraylist. There is no need to provide a synchronization mechanism in the user implementations of ResultCollector

Since:
  GemFire 6.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addResult(DistributedMember memberID, T resultOfSingleExecution)`
  Method used to feed result to the ResultCollector.
  `void`
  `clearResults()`
  GemFire will invoke this method before re-executing function (in case of Function Execution HA).
  `void`
  `endResults()`
  GemFire will invoke this method when function execution has completed and all results for the execution have been obtained and `added to the ResultCollector` Unless the `ResultCollector` has received `last result` from all the executing nodes, it keeps waiting for more results to come.
  `S`
  `getResult()`
  Method used to pull results from the ResultCollector.
  `S`
  `getResult(long timeout, TimeUnit unit)`
  Method used to pull results from the ResultCollector.

- ## Method Details

  - ### getResult

    S getResult() throws FunctionException
    Method used to pull results from the ResultCollector. It returns the result of function execution, potentially blocking until `all the results are available` has been called.
    Returns:
      the result
    Throws:
      `FunctionException` - if result retrieval fails
    Since:
      GemFire 6.0

  - ### getResult

    S getResult(long timeout, TimeUnit unit) throws FunctionException, InterruptedException
    Method used to pull results from the ResultCollector. It returns the result of function execution, blocking for the timeout period until `all the results are available`. If all the results are not received in provided time a FunctionException is thrown.
    Parameters:
      `timeout` - the maximum time to wait
      `unit` - the time unit of the timeout argument
    Returns:
      the result
    Throws:
      `FunctionException` - if result retrieval fails within timeout provided
      `InterruptedException` - if the current thread was interrupted while waiting
    Since:
      GemFire 6.0

  - ### addResult

    void addResult(DistributedMember memberID, T resultOfSingleExecution)
    Method used to feed result to the ResultCollector. It adds a single function execution result to the ResultCollector It is invoked every time a result is sent using ResultSender.
    Parameters:
      `memberID` - DistributedMember ID to which result belongs
      `resultOfSingleExecution` - the result to add
    Since:
      GemFire 6.0

  - ### endResults

    void endResults()
    GemFire will invoke this method when function execution has completed and all results for the execution have been obtained and `added to the ResultCollector` Unless the `ResultCollector` has received `last result` from all the executing nodes, it keeps waiting for more results to come.
    Since:
      GemFire 6.0
    See Also:
      - `ResultSender.lastResult(Object)`

  - ### clearResults

    void clearResults()
    GemFire will invoke this method before re-executing function (in case of Function Execution HA). This is to clear the previous execution results from the result collector
    Since:
      GemFire 6.5