This proposal contains a number of improvements to the function service to improve usability issues.
There are some minor improvements that already have JIRAs. We should just apply the changes described in these jiras.
GEODE-625 - A function's ResultCollector throws ClassCastException when ResultSender.sendException is invoked Open
GEODE-393 - FunctionContext should provide a Cache Open
GEODE-641 - Allow lambda expressions to be used for Geode functions Closed
GEODE-336 - Function extends Identifiable without specifying generics type for Identifiable Closed
RegionFunctionContext should provide the local data set
If you want to operate on the local data set for a function, you have to do this
There are several problems with this approach.
- It's not clear that ctx.getDataSet does not return the local data.
- The local data set is not mockable for unit tests, because this static function call extracts it using internal APIs on concrete classes. This prevents this sort of function from being tested in a pure unit test.
- The user has to know that PartitionRegionHelper exists; the API is not obvious
- The various methods on PartitionRegionHelper are confusing, specifically it's unclear to a user why they should use getLocalDataForContext instead of getLocalData
RegionFunctionContext should just provide a getLocalDataSet method. We will add this new method to the RegionFunctionContext interface. We will deprecate the PartitionRegionHelper.getLocalDataForContext.
See GEODE-726 Open
Functions executed on a region should implement a different interface
Any function that is executed on a region has to do a cast:
This is not an intuitive API; the user has to know that there is such a thing as RegionFunctionContext. This can also lead to ClassCastExceptions if the user tries to cast the FunctionContext and it is not actually a RegionFunctionContext
Instead, we will add a new RegionFunction interface that provides a RegionFunctionContext. FunctionService.onRegion will return a RegionExecution interface with an execute method that takes a RegionFunction.
See GEODE-394 Open for more details.
The methods isHA, hasResult, optimizeForWrite should move from the Function interface to the Execution interface
isHA, hasResult, and optimizeForWrite are methods on Function that the user can override. However, that makes it harder to write lambda expressions for functions, because if you want to set one of these parameters you can now longer use a lambda.
Also the function service API provides a way to invoke functions using a string id. For example FunctionService.onServer().execute("MY_FUNCTION_ID"). If we remove these extra methods from the Function interface, this code will no longer need to look up the Function on the client and the Function class will not have to exist on the client any more.
We will add isHA(boolean), hasResult(Boolean) and optimizeForWrite(boolean) to the Execution interface. These methods will be deprecated on the function interface. Unfortunately, if someone invokes a function on a client given the string id, we will still need to look up the function class for now in case they have specified these parameters on their function. But in another release we can remove the deprecated parameters and stop using them.
See GEODE-727 Open
The Function interface should return a value
The function context has a ResultSender with methods like sendResult, lastResult, sendException, etc. Unfortunately, that makes the common case of a function that returns a single result unnecessarily verbose and error prone. For example, if no result is sent that can cause issues:
Instead, the function interfaces should return a value. For the simple case where there is only one result, the user can just return the result. For cases with multiple streaming results, the user can look up the result sender. For cases with no results the user can just return null. The return value will be ignored anyway if the user invokes the function with hasResult==false.
We can't change the existing Function interface, but we can add a return value to the new RegionFunction interface we're introducing. We can also introduce a MemberFunction interface that returns a value, to distinguish it from the RegionFunction.
Combining these changes with GEODE-2217 - Add generic type parameter to FunctionContext interface Closed would result in interfaces with two generic types, one for the function argument type and another for the function return type.
See GEODE-729 Open
Add Cache.getFunctionService and deprecate the static methods on FunctionService
This proposal might be a bit more controversial. The issue is that the current FunctionService leads people to write code that is harder to test, because they cannot mock the FunctionService if they are making static calls to FunctionService.onRegion. If FunctionService is something that could be provided by the cache, a user can mock FunctionService and assert that functions are invoked.
The other issue this fixes is that FunctionService has methods like onMembers(String ... groups) that internally look up a static cache. Besides making it hard for users to use Mocks with FunctionService code, this also ties us to having a singleton cache and distributed system. Since we're trying to get rid of singletons we should fix this API to not rely on an underlying singleton.
Stop Requiring the user to use the ResultCollector returned by the execute method.
The javadocs for execute say this
It's confusing to users that geode wraps their result collector in another collector that has different behavior.
We should make sure that users don't have to call getResults on the returned ResultCollector. If we want to make it easier for users to implement a ResultCollector that waits for all of the results to arrive, we should provide helper classes like a BlockingResultCollector that waits for all results to arrive in getResults.
Part of the reason is is required right now is the way that exceptions get handled. If a function throws an exception or even just sends an exception with ResultSender.sendResult, the user's ResultCollector will never see it. The only way to get the exception is to call getResult on the result collector returned by execute. See GEODE-625 Open .
Summary of changes
Examples of API changes