 | This documentation applies to the Functor Pattern 1.1.0. The latest Functor Pattern documentation is available is here. |
The Functor Pattern
This is an example implementation of Function Objects (Wikipedia) or as it is also known, the Functor Pattern, built with Coherence.
The Functor Pattern is an extension to the Command Pattern. In fact the semantics are identical with the exception that the Functor Pattern additionally provides a mechanism to return values (or re-throw exceptions) to the Submitter (using Java 5+ Futures) where as the Command Pattern does not provide such capabilities. Consequently in order to use Functor Pattern it is highly recommended that you understand the Command Pattern.
Dependencies
This project (like other Coherence Incubator projects) uses Apache Ivy for dependency specification and management. While a standard ivy.xml definition file ships with the source and documentation distribution, the following diagram visually indicates the current dependencies.
|
Outline
Rationale
The Functor Pattern provides a useful alternative to Oracle Coherence EntryProcessors with the advantage that Functors are executed asynchronously, instead of synchronously as is the case with EntryProcessors. |
What's New?
The following changes have been made since the Functor Pattern 1.0.0 release.
- Migrated to use Apache Ivy for dependency management, building and publishing artifacts
- Added support for canceling Functors using the returned Future.
- Added support to wait a specified amount of time for results from a Functor using a Future.
Example
Let's start with a simple example where we use the Functor Pattern to asynchronously increment and return the value of a Counter
First, we'll start by writing a simple Counter:
import java.io.Serializable;
import com.oracle.coherence.patterns.command.Context;
public class Counter implements Context, Serializable {
private long next;
public Counter(long initialValue) {
this.next = initialValue;
}
public long next() {
return next++;
}
public String toString() {
return String.format("Counter{next=%d}", next);
}
}
Second, let's write a Functor that will increment the value of a Counter
import java.io.Serializable;
import com.oracle.coherence.patterns.command.ExecutionEnvironment;
import com.oracle.coherence.patterns.functor.Functor;
public class NextValueFunctor implements Functor<Counter, Long>, Serializable {
private static final long serialVersionUID = 4841498972676821911L;
public Long execute(ExecutionEnvironment<Counter> executionEnvironment) {
Counter counter = executionEnvironment.getContext();
long next = counter.next();
executionEnvironment.setContext(counter);
return next;
}
}
Lastly, let's write a simple example to test our Functor.
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Future;
import com.oracle.coherence.common.identifiers.Identifier;
import com.oracle.coherence.patterns.command.ContextsManager;
import com.oracle.coherence.patterns.command.DefaultContextsManager;
import com.oracle.coherence.patterns.functor.DefaultFunctorSubmitter;
import com.oracle.coherence.patterns.functor.FunctorSubmitter;
import com.tangosol.net.CacheFactory;
public class FunctorPatternExample {
public static void main(String[] args) throws InterruptedException, ExecutionException {
ContextsManager contextsManager = DefaultContextsManager.getInstance();
Identifier contextIdentifier = contextsManager.registerContext("myCounter", new Counter(0));
FunctorSubmitter functorSubmitter = DefaultFunctorSubmitter.getInstance();
functorSubmitter.submitCommand(contextIdentifier, new LoggingCommand("Commenced", 0));
for (int i = 0; i < 50; i++) {
Future<Long> future = functorSubmitter.submitFunctor(contextIdentifier, new NextValueFunctor());
System.out.println(future.get());
}
functorSubmitter.submitCommand(contextIdentifier, new LoggingCommand("Completed", 0));
Thread.sleep(2000);
Counter counter = (Counter)contextsManager.getContext(contextIdentifier);
System.out.println(counter);
}
}
Frequently Asked Questions
What is the relationship between the Functor Pattern, Command Pattern, Entry Processors and the Invocation Service for performing work in a cluster?
The following table outlines the main differences.
| |
Functor Pattern |
Command Pattern |
EntryProcessors |
InvocationService |
| Processing Target |
A Context |
A Context |
A Cache Entry |
A Cluster Member |
| Submission Behavior |
Non-Blocking |
Non-Blocking |
Blocking |
Blocking and Non-Blocking |
| Execution Order |
Order of Submission |
Order of Submission |
Order of Submission (unless using PriorityTasks) |
Order of Submission |
Supports Return Values?
(and re-throwing Exceptions) |
Yes |
No |
Yes |
Yes |
Guaranteed to Execute?
(if Submitter terminates after submission) |
Yes |
Yes |
Yes (submitter blocks) |
Yes (for blocking), No (for non-blocking) |
Guaranteed to Execute?
(if Target JVM terminates during execution) |
Yes |
Yes |
Yes (submitter automatically retries) |
No (retry up to developer) |
| Submitted requests recoverable from disk? |
Yes (when using Cache Store) |
Yes (when using Cache Store) |
No |
No |
| Request may be cancelled? |
Yes |
Yes |
No |
Yes (for non-blocking) |
Can Functors and Commands be submitted to the same Context?
Yes. Functors and Commands may be submitted for execution against the same Context. They will be executed in the order of submission from the Submitter. Further, FunctorSubmitters may be used instead of CommandSubmitters (as the FunctorSubmitter interface is a sub-interface of the CommandSubmitter interface)
How do I monitor the execution of Functors ?
As the Functor Pattern uses the Command Pattern for the internal implementation (and that is JMX enabled), all you need to do is simply enable JMX.
References and Additional Information
