ResultCollector (Apache Geode 1.6.0)
Date: 2018-04-23

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

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and 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, java.util.concurrent.TimeUnit unit)` Method used to pull results from the ResultCollector.

- - ### Method Detail

    - #### 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,
                      java.util.concurrent.TimeUnit unit)
               throws FunctionException,
                      java.lang.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
        `java.lang.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:
        `resultOfSingleExecution` -
        `memberID` - DistributedMember ID to which result belongs
      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