We've begun to develop some example code that demonstrates the use and utility of the Functor component.
In order to keep the examples in sync with the rest of the code, each example is written as a JUnit TestCase. The example programs are executed along with all the other unit tests, and can be invoked via ant test or maven test once you've set up Ant or Maven as described in the build instructions.
If you're not familiar with JUnit, don't worry. An understanding of JUnit isn't important for an understanding of these examples, and we'll walk you through the relevant bits anyway.
Two things you'll want to know about JUnit are (a) all the methods whose names start with "test" will be executed automatically by the test suite and (b) there are various "assert" methods that can be used to make assertions about the Objects being tested. If any assertion fails, the JUnit framework will count (and report) this as a test failure.
You can run a specific test case or sub-suite via Ant by invoking
ant -Dtest.entry=<fully-specified-test-case-name> test
or in Maven by invoking
maven -Dtestcase=<fully-specified-test-case-name> test:single
For example, to run the Quicksort example, invoke
ant -Dtest.entry=org.apache.commons.functor.example.QuicksortExample test
or
maven -Dtestcase=org.apache.commons.functor.example.QuicksortExample test:single
To run all the examples, invoke:
ant -Dtest.entry=org.apache.commons.functor.example.TestAll test
or
maven -Dtestcase=org.apache.commons.functor.example.TestAll test:single
Each example is has descriptive prose mixed right in with the source, as /* C++ style */ comments.
"Pragmatic" Dave Thomas has been blogging a series of programming exercises he calls Code Katas. These exercises are intended to provide "practice sesssions" that allow programmers to hone their craft. The notion is borrowed from the practice of Karate, where, in Dave's words "a kata is an exercise where you repeat a form many, many times, making little improvements in each".
Here we use several of Dave's Code Katas to explore the Commons-Functor library.
The lines package demonstrates a functional approach to IO using Generators and the Algorithms class.
The Functor package, and more generally, a functional approach to program design, supports a powerful technique for balancing behavior specialization and code reuse.
Traditional Object Oriented design suggests inheritence as a mechanism code reuse, and method overloading as a mechanism for specialization. For example, one defines a general purpose, perhaps even abstract class, say AbstractList, and then extend or specialize this parent via subclasses, inheriting some behaviors and overloading others.
Functors encourage another, complementary approach to code reuse and behavior specialiazation: composition. Following a compositional design, we create a number of simple objects and then combine them to create more complex behaviors. For example, the Commons Pool component defines an ObjectPool type that maintains a collection of pooled objects, but delegates to a PoolableObjectFactory to create, validate and destroy the objects to be pooled. Arbitrary ObjectPool implementations can be composed with arbitrary PoolableObjectFactory implementations in order to create new types of pools.
The FlexiMap example applies this design to java.util.Map, demonstrating how "pluggable" functors can be applied to a generic Map structure in order to introduce new behaviors.
The map package is a more complete example of this, implementing a number of the Commons-Collections Maps derived from a base FunctoredMap.
The Quicksort example presents an implementation of the Quicksort sorting algorithm written in a functional programming style using Commons Functor.