<< Previous | Home | Next >>

Non-Blocking Asynchronous Java 8 and Scala's Try/Success/Failure

Inspired by a recent newsletter from Heinz Kabutz as well as Scala's Futures which I investigated in my recent book, I set about using Java 8 to write an example of how to submit work to an execution service and respond to its results asynchronously, using callbacks so that there is no need to block any threads waiting for the results from the execution service.

Theory says that calling blocking methods like get on a java.util.concurrent.Future is bad, because the system will need more than the optimum number of threads if it is to continuously do work, and that results in wasting time with context switches.

In the Scala world, frameworks like Akka use programming models that mean that the frameworks will never block - the only time a thread blocks is when a user programs something which blocks, and they are discouraged from doing that. By never blocking, the framework can get away with using about one thread per core which is many less than say a standard JBoss Java EE Application Server, that has as many as 400 threads just after startup. Due largely to the work of the Akka framework, Scala 2.10 added Futures and Promises, but these don't (yet?) exist in Java.

The following code shows the goal I had in mind. It has three parts to it. Firstly, new tasks are added to the execution service using the static future method found in the class ch.maxant.async.Future. It returns a Future, but not one from the java.util.concurrent package, rather a subclass thereof from the ch.maxant.async package. Secondly, that Future has a method called map, following the functional style from Scala or the new Java 8 Stream class. The map method lets you register a callback, or more precisely, let's you map (convert) the value that the first future contains into a new value. The mapping is carried out at some other time in the future, after the first Future is completed and so it results in a new Future. Thirdly, we use another method in the Future class to register a callback to be run once all the futures we create are complete. At no time are any blocking methods of the Future API used!
final Random random = new Random();
int numTasks = 10;
List<Future<Integer>> futures = new ArrayList<>();

for(int i = 0; i < numTasks; i++){
    final int j = i;
    log("adding future " + i);
    // PART 1
    //start some work async / in the future
    Future<String> f = future(new Task<String>( () -> {
        if(j < 5){
            log("working success");
            return "20";
            log("working failure");
            throw new Exception();
    // PART 2
    //register a callback, to be called when the work is done
    log("adding mapping callback to future");
    final Future<Integer> f2 = f.map( (Try<String> stringNumber) -> {
        return stringNumber.map( (String s) -> {
            log("mapping '" + s + "' to int");
            return Integer.parseInt(s);
        }).recover( (Exception e) -> {
            return -10;
        }).get(); //wont throw an exception, because we provided a recovery!

// PART 3
log("registering callback for final result");
Future.registerCallback(futures, (List<Try<Integer>> results) -> {
    Integer finalResult = results.stream().map( (Try<Integer> t) -> {
        log("mapping " + t);
        try {
            return t.get();
        } catch (Exception e) {
            return 0;
    }).reduce(0, (Integer i1, Integer i2) -> {
        log("reducing " + i1 + " and " + i2);
        return i1 + i2;
    log("final result is " + finalResult);
    if(finalResult != 50){
        throw new RuntimeException("FAILED");
System.out.println("Completed submitting all tasks on thread " + Thread.currentThread().getId());
//this main thread will now die, but the Future executor is still up and running.  the callback will shut it down and with it, the jvm.
Line 11 calls the future method to register a new Task, which is constructed using a Work instance, constructed here using a Java 8 lambda. The work sleeps for a little time and then either returns the number 20, as a string, or throws an exception, just to demonstrate how errors are handled.

Using the Future that line 11 gets back from the execution service, line 25 maps it's value from a string into an integer, resulting in a Future<Integer> rather than a Future<String>. That result is added to a list of Futures on line 35, which part 3 uses on line 40. The registerCallback method will ensure that the given callback is called after the last future is completed.

The mapping on lines 25-33 is done using a lambda which is passed a Try object. A Try is a little like a Java 8 Optional and is an abstraction (super class) of the Success and Failure classes, which I implemented based on my knowledge of their Scala counterparts. It allows programmers to handle failure more easily than having to explicitly check for errors. My implementation of the Try interface is as follows:
public interface Try<T> {
    /** returns the value, or throws an exception if its a failure. */
    T get() throws Exception;
    /** converts the value using the given function, resulting in a new Try */
    <S> Try<S> map(Function1<T, S> func);
    /** can be used to handle recovery by converting the exception into a {@link Try} */
    Try<T> recover(Recovery<T> r);
What happens is that the implementation of the Success and Failure handle errors gracefully. For example, if the Future on line 11 of the first listing is completed with an exception, then the lambda on line 25 of the first listing is passed a Failure object, and calling the map method on a Failure does absolutely nothing. No exception is raised, nothing. To compensate, you can call the recover method, for example on line 29 of the first listing, which allows you to handle the exception and return a value with which your program can continue, for example a default value.

The Success class on the other hand implements the map and recover methods of the Try interface differently, such that calling map leads to the given function being called, but calling recover does absolutely nothing. Instead of explicitly coding a try/catch block, the map and recover methods allow for a nicer syntax, one which is more easily validated when reading or reviewing code (which happens more often to code, than writing it).

Since the map and recover methods wrap the results of the functions in Trys, you can chain the calls together, such as lines 26, 29 and 32. The Try API from Scala has many more methods than the three that I have implemented here. Note that I chose not to use a java.util.function.Function in my Try API because it's apply method doesn't throw Exception which meant that the code shown in the first listing wasn't as nice as it now is. Instead I wrote the Function1 interface.

Part 3 of the puzzle is how to get the program to do something useful after all the Futures are complete, without nasty blocking calls like those to the Future#get() method. The solution is to register a callback as shown on line 40. That callback is, like all the others shown here, submitted to the execution service. That means we have no guarantee which thread will run it, and that has a side effect, namely that thread local storage (TLS) no longer works - some frameworks like (older versions of?) Hibernate relied on TLS, and they just won't work here. Scala has a nice way of solving that problem using the implicit keyword, which Java doesn't have (yet...?), so some other mechanism needs to be used. I'm mentioning it, just so that you are aware of it.

So, when the last future completes, lines 40-60 are called, and passed a List of Trys containing Integers, rather than Futures. The registerCallback method converts the futures into appropriate Successes or Failures. But how can we convert those into something useful? With a simple map/reduce of course, and luckily, Java 8 now supports that with the Stream class, which is instantated from the collection of Trys on line 42 by calling the stream() method. First I map (convert) the Trys into their values, and then I reduce the stream to a single value on line 49. Instead of passing my own implementation of a lambda that sums values, I could have used Integer::sum, for example someStream.reduce(0, Integer::sum).

The last time I ran the program, it outputted the following:
Thread-1 says: adding future 0
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 1
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 2
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 3
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 4
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 5
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 6
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 7
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 8
Thread-1 says: adding mapping callback to future
Thread-1 says: adding future 9
Thread-1 says: adding mapping callback to future
Thread-1 says: registering callback for final result
Thread-10 says: working success
Completed submitting all tasks on thread 1
Thread-14 says: working success
Thread-10 says: working failure
Thread-14 says: working failure
Thread-12 says: working success
Thread-10 says: working failure
Thread-10 says: mapping '20' to int
Thread-10 says: mapping '20' to int
Thread-10 says: recovering
Thread-10 says: recovering
Thread-10 says: mapping '20' to int
Thread-10 says: recovering
Thread-11 says: working success
Thread-11 says: mapping '20' to int
Thread-13 says: working success
Thread-10 says: mapping '20' to int
Thread-12 says: working failure
Thread-12 says: recovering
Thread-14 says: working failure
Thread-14 says: recovering
Thread-14 says: mapping Success(20)
Thread-14 says: mapping Success(20)
Thread-14 says: mapping Success(20)
Thread-14 says: mapping Success(20)
Thread-14 says: mapping Success(20)
Thread-14 says: mapping Success(-10)
Thread-14 says: mapping Success(-10)
Thread-14 says: mapping Success(-10)
Thread-14 says: mapping Success(-10)
Thread-14 says: mapping Success(-10)
Thread-14 says: final result is 50
Thread-14 says: SUCESS
As you can see, the main thread adds all the tasks and registers all the mapping functions (lines 1-20). It then registers the callback (line 21 of the output which corresponds to line 39 of the listing), and finally outputs the text from line 63 in the listing, after which it dies, because it has nothing else to do. Line 22 and lines 24-42 of the output then show the various threads in the pool (which contained 5 threads) processing the work as well as mapping from String to Integer, or recovering from an exception. This is the code in parts 1 and 2 of the first listing. You can see that it is entirely asynchronous, with some mappings / recoveries occuring before all the initial work is complete (compare lines 38 or 40 which are a mapping and recovery respectively, to line 41 of the output, which occurs afterwards and is the last of the initial work). Lines 43-52 are the output of the map/reduce which is part 3 of the main listing. Note that no reduce is logged, because the code I ran, and which is on Github, uses the Integer::sum shortcut mentioned above, rather than lines 50-51 of the first listing shown above.

While all of this is possible using Java 6 (or even 5?), for example by getting the tasks which are submit to the pool to submit the callback themselves, once they are finished, the amount of code needed to do that is larger and the code itself would be uglier than that shown here. Java 8 lambdas, Futures which can be mapped using callbacks and the Try API with its neat error handling all make the solution shown here arguably more maintainable.

The code shown above, as well as the code for the classes in the ch.maxant.async package, are available under the Apache License Version 2.0, and can be downloaded from my Github account.

Copyright ©2013, Ant Kutschera
Tags : , ,
Social Bookmarks :  Add this post to Slashdot    Add this post to Digg    Add this post to Reddit    Add this post to Delicious    Add this post to Stumble it    Add this post to Google    Add this post to Technorati    Add this post to Bloglines    Add this post to Facebook    Add this post to Furl    Add this post to Windows Live    Add this post to Yahoo!

Play 2.0 framework and XA transactions

XA transactions are useful and out of the box, Play 2.0 today does not have support for them.  Here I show how to add that support:

First off, some examples when XA is useful:

- JPA uses two physical connections if you use entities from two different persistence.xml - those two connections might need to be committed in one transaction, so XA is your only option
- Committing a change in a database and at the same time committing a message to JMS.  E.g. you want to guarantee that an email is sent after you successfully commit an order to the database, asynchronously.  There are other ways, but JMS provides a transactional way to do this with little overhead in having to think about failure.
- Writing to a physically different database because of any of several political reasons (legacy system, different department responsible for different database server / different budgets).
- See http://docs.codehaus.org/display/BTM/FAQ#FAQ-WhywouldIneedatransactionmanager

So the way I see it, XA is something Play needs to "support".

Adding support is very easy.  I have created a play plugin which is based on Bitronix.  Resources are configured in the Bitronix JNDI tree (why on earth does Play use a config file rather than JNDI?! anyway...)  You start the transaction like this, "withXaTransaction":

    def someControllerMethod = Action {
                    withXaTransaction { ctx =>

addValidation(user.get, bookingRef, ctx)
addValidation(bookingRef, user.get, ctx)
                    val tickets = TicketRepository.
eventUid, getTickets(eventUid), user, eventValidationForm))

The ctx object is an XAContext (my own class) which lets you look up resources like a datasource, or set rollback in case of a failure.  So the validation repo does this, using ScalaQuery (I used "withSession" rather than "withTransaction!"):

    def addValidation(bookingRef: String, validator: User, ctx: XAContext) = {
        val ds = ctx.lookupDS("jdbc/maxant/
        Database.forDataSource(ds) withSession { implicit db: Session =>
bookingRef, validator.email, new java.sql.Timestamp(now)))

And the ticket repo does the following with JMS:

    def addValidation(user: User, bookingRef: String, ctx: XAContext) = {

        val xml =

        val qcf = ctx.lookupCF("jms/maxant/
        val qc = qcf.createConnection("
        val qs = qc.createSession(false, Session.AUTO_ACKNOWLEDGE)
        val q = qs.createQueue("
ticketValidationQueue") //val q = ctx.lookup(QUEUE).asInstanceOf[Queue]
        val sender = qs.createProducer(q)
        val m = qs.createTextMessage(xml.

I've tested it with writing to MySQL and sending a JMS message to JBoss (HornetQ) and it seems to work well (except getting hornetQ to play with Bitronix was a bitch - see here: https://community.jboss.org/thread/206180?tstart=0).

The scala code for the XA support is:

package ch.maxant.scalabook.play20.plugins.xasupport

import play.api.mvc.RequestHeader
import play.api.mvc.Results
import play.api.mvc.Request
import play.api.mvc.AnyContent
import play.api.mvc.Result
import play.api.mvc.Action
import play.api.mvc.Security
import play.api._
import play.api.mvc._
import play.api.data._
import play.api.data.Forms._
import ch.maxant.scalabook.
import bitronix.tm.
import java.util.Hashtable
import javax.naming.Context._
import javax.naming.InitialContext
import javax.sql.DataSource
import bitronix.tm.
import java.io.File
import org.scalaquery.session.
import org.scalaquery.SQueryException
import scala.collection.mutable.
import java.sql.Connection
import java.sql.SQLException
import org.scalaquery.session.Session
import bitronix.tm.
import javax.jms.ConnectionFactory

class XAContext {

    private val env = new Hashtable[String, String]()
FACTORY, "bitronix.tm.jndi.BitronixInitialContextFactory")
    private val namingCtx = new InitialContext(env);

    var rollbackOnly = false
    def lookup(name: String) = {
    def lookupDS(name: String) = {
    def lookupCF(name: String) = {

trait XASupport { self: Controller =>

    private lazy val tm = play.api.Play.current.plugin[
XASupportPlugin] match {
      case Some(plugin) =>
      case None => throw new Exception("There is no XASupport plugin registered. Make sure it is enabled. See play documentation. (Hint: add it to play.plugins)")

     * Use this flow control to make resources used inside `f` commit with the XA protocol.
     * Conditions: get resources like drivers or connection factories out of the context passed to f.
     * Connections are opened and closed as normal, for example by the withSession flow control offered
     * by ScalaQuery / SLICK.
    def withXaTransaction[T](f: XAContext => T): T = {

        //get a ref to the transaction, in case when we want to commit we are no longer on the same thread and TLS has lost the TX.
        //we have no idea what happens inside f!  they might spawn new threads or send work to akka asyncly
        val t = tm.getCurrentTransaction
Started XA transaction " + t.getGtrid())
        val ctx = new XAContext()
        var completed = false
            val result = f(ctx)
            completed = true
committing " + t.getGtrid() + "...")
committed " + t.getGtrid())
            if(!completed || ctx.rollbackOnly){
                //in case of exception, or in case of set rollbackOnly = true
rolling back (completed=" + completed + "/ctx.rollbackOnly=" + ctx.rollbackOnly)

class XASupportPlugin(app: play.Application) extends Plugin {

    protected[plugins] var tm: BitronixTransactionManager = null
    override def onStart {
        //TODO how about getting config out of jar!
        val file = new File(".", "app/bitronix-default-config.
Using Bitronix config at " + file)
        val prop = System.getProperty("bitronix.
tm.configuration", file) //default
tm.configuration", prop) //override with default, if not set

        //start the TM
        tm = TransactionManagerServices.
Started TM with resource config " + TransactionManagerServices.getConfiguration.getResourceConfigurationFilename)

    override def onStop {
        //on graceful shutdown, we want to shutdown the TM too
Shutting down TM")
        Logger("XASupport").info("TM shut down")


Use the code as you like, I'm giving it away for free :-)  Just don't complain if it don't work ;-)

It would be nice to see this plugin extended and turned into something a little more production ready.  Even nicer would be for Play to support a transaction manager natively, including fetching resources out of JNDI.

Have fun!

(copyright Ant Kutschera 2012)

Tags : , ,
Social Bookmarks :  Add this post to Slashdot    Add this post to Digg    Add this post to Reddit    Add this post to Delicious    Add this post to Stumble it    Add this post to Google    Add this post to Technorati    Add this post to Bloglines    Add this post to Facebook    Add this post to Furl    Add this post to Windows Live    Add this post to Yahoo!

Hacking Maven

We don't use M2Eclipse to integrate Maven and Eclipse, partly because we had some bad experiences a couple of years ago when we were still using Eclipse 3.4 and partly because some of our developers use IBMs RAD to develop, and it doesn't (or at least wasn't) compatible. Our process is to update our local sources from SVN and then to run Maven's eclipse:eclipse locally with the relevant workspace setting so that our .project and .classpath files are generated, based on the dependencies and other information in the POMs. It works well enough, but the plan is indeed to move to M2Eclipse at some stage soon.

We have parent POMs for each sub-system (each of which is made of several Eclipse projects). Some of us pull multiple sub-systems into our workspaces which is useful when you refactor interfaces between sub-systems, because Eclipse can refactor the code which calls the interfaces at the same time as you refactor the interfaces, saving lots of work. Maven generates .classpath files for Eclipse which reference everything in the workspace as a source projet rather than a JAR out of the local Maven repo. That is important because if Maven created JAR references and not project references, Eclipse's refactoring wouldn't adjust the code calling the refactored code.

10 days ago we switched from a build process based on continuum and archiva to jenkins and nexus. All of a sudden we lost some of the source references which were replaced with JAR references. If a project was referred to in a parent POM then it was referenced as a project in Eclipse, but if it was a sub-system built using a second parent POM, then Eclipse was referring to the project as a JAR from the local Maven repo. That was bad news for our refactoring! Here is an example of what used to happen:

    subsystem-a-project-2 references subsystem-a-project-1 as a project

    subsystem-b-project-1 references subsystem-a-project-1 as a project

Here is what was happening when we used Jenkins and Nexus:

    subsystem-a-project-2 references subsystem-a-project-1 as a project

    subsystem-b-project-1 references subsystem-a-project-1 as a JAR!!!

At the same time as moving to Jenkins and Nexus, we upgraded a few libraries and our organisational POM. We also moved our parent POMs from the root directory of the sub-system into a project for the parent (in preparation for using M2Eclipse which prefers having the parent POM in the workspace).

The question was, where do we start looking? Some people suggested it was because we'd moved the parent POM, others thought it was because we'd updated a version of a library on which eclipse:eclipse might have a dependency and others were of the opinion we had to return to Continuum and Archiva.

One of our sharp eyed developers noticed that we were getting the following output on the command line during the local Maven build:

    Artifact subsystem-a-project-1 already available as a workspace project, but with different version...

That was the single find which led to us solving the problem quickly. I downloaded the source of eclipse:eclipse from Maven central, under org/apache/maven/plugins/maven-eclipse-plugin. I created a dummy Java project in Eclipse. Next, I added the following environment variable to my command line from where I run Maven:

    set MAVEN_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=28000

That tells the JRE to open a debug port and wait until a debugger is connected before running the app. Running a Java program with those args makes it output "Listening for transport dt_socket at address: 28000". In Eclipse I went to the debug run configurations and added a remote connection at localhost on port 28000. It needs a project, so I added the dummy project I'd just created. I connected and Maven continued to run now that I was connected. The next step was to add the Maven Plugin source code which I'd downloaded from Maven Central. By right clicking on the debug view in the debug perspective (click on the tree), it is possible to add/update source attachments, and I added the sources JAR that I'd downloaded. The last bit was to find a suitable breakpoint. I extracted the sources from the downloaded ZIP and searched the files for the text which was being output by Maven which was hinting at the problem ("already available as a workspace project"). EclipsePlugin was the suspect class!

I added the eclipse:eclipse JAR to my dummy project so that I could open the class in Eclipse using ctrl+shift+t. Eclipse opened the class, but hadn't worked out that the source from the source attachment belongs to that class. There is a button in the editor to attach the source by locating the JAR downloaded from Maven Central and Eclipse then showed the source code and I was able to add a breakpoint. By this time Maven had finished, so I restarted it and this time I hit the breakpoint, and the problem became quite clear. For some reason, rather than the version being a simple SNAPSHOT version, it contained a timestamp. The eclipse:eclipse plugin was of the opinion that I didn't have the correct code in the workspace, and so rather than create a project reference, it created a JAR reference based on the JAR in the local Maven repo.

The internet is full of information about how Maven3 now uses unqiue timestamps for each build artefact deployed to the repo. There were some references saying you could disable it for Maven2 (which we still use), but when you move to Maven3 you can't disable it. I thought about submitting a bug report to Codehaus (who supplies the eclipe:eclipse plugin), but it occurred to me that we were still referencing version 2.8 in our organisational POM and I'd spotted a 2.9 version when I was at Maven Central. So I updated the organisational POM to use version 2.9 of eclipse:eclipse and gave that a shot.

Hooray! 23:17 and I'd fixed our problem. Shame I had a 06:30 start the next day for a meeting :-/

This isn't the first time that we've made the mistake of doing too much in a migration. We could have stuck with Continuum and Archiva when we updated our org-POM, and then step for step migrated to Nexus (still using Archiva) and then finally moved over to Nexus. Had we done that, we might not have had the problems we did; but the effort of a slow migration might also have been larger.

For me, the point to take away is that it easier to debug maven and go straight to the source of the problem, than it is to attempt to fix the problem by trail and error, as we were doing before I debugged Maven. Debugging Maven might sound like it's advanced or complicated, but it's damn fun - it's real hacking and the feeling of solving a puzzle in this way makes the effort worth it. I fully recommend it if for no other reason that you get exposed to reading other peoples (open source) code.

Copyright © 2012, Ant Kutschera

Social Bookmarks :  Add this post to Slashdot    Add this post to Digg    Add this post to Reddit    Add this post to Delicious    Add this post to Stumble it    Add this post to Google    Add this post to Technorati    Add this post to Bloglines    Add this post to Facebook    Add this post to Furl    Add this post to Windows Live    Add this post to Yahoo!

100% code coverage, Hibernate Validator and Design by Contract

Code coverage in unit testing was one of the first things I learned in my software engineering career. The company I worked at taught me that you should have 100% coverage as a goal, but achieving it does not mean there are no bugs in the system. At that time, I worked at a company whose big thing was that they delivered very reliable billing software to telecomms operators. We used to invest as much time writing unit tests as we did writing the code. If you included unit tests, integration tests, system tests and acceptance tests, more time was spent testing than designing and implementing the code which ran in production. It was impressive and I have never worked with or for a company with that kind of model since, although I am sure there are many companies which operate like that.

The other day I was thinking back to those days and reading up about unit testing to refresh myself in preparation for a unit testing course I'm attending soon (don't want the instructor to know more than me!) and I started to wonder about what kind of code could be fully covered during unit testing, but which could still contain a bug. While I learned that 100% coverage should be the goal, in over 10 years I have never worked on a project which achieved that. So I have never surprised to find a bug in code which I thought was "fully" tested.

It's fun write whacky code - you don't normally try and write bugs :-) I started with the specification:

     * @return String "a" or "b" depending upon the values
     * passed to the init method. If variable "a" is true,
     * then string "a" is returned. If variable "b" is true,
     * then "b" is returned. If neither is true, then "" is
     * returned. Variable "b" is important than "a", so if
     * both are true then return "b".

Now, the tricky part was to write code which contained a bug yet was easy to cover with incomplete tests. I came up with the following. The specification above is for the "getResult()" method.

public class SomeClass {

    private boolean a;
    private boolean b;

    public SomeClass init(boolean a, boolean b) {
        this.a = a;
        this.b = b;
        return this;

    public String getResult() {
        String s = "";
        if(a) {
            s = "a";
            s += "b"; // <-- oops!
        return s;

The "bug" is in the method "getResult" and the problem is that instead of just an assignment, the "plus equals" operator has been used. An "else" would probably make the code a little safer too. But I think code like this is quite typical of the buggy code that finds its way into productive systems. Even the best programmers have lapses of concentration where they write typos like this (especially in open plan offices!).

The unit test which a programmer trying to achieve 100% coverage, would look something like this:

    public void test() {
        assertEquals("a", new SomeClass().init(true, false).getResult());
        assertEquals("b", new SomeClass().init(false, true).getResult());

Using Emma for Eclipse I measured complete coverage. But wait! There is still a bug. The code does not do what it says in the Javadoc spec. If I initialise the object with "true, true", then the result will be "ab", because of the "plus equals" operator. So even though I have 100% coverage, I still have a bug.

I asked myself what that means to me as a programmer. What do I need to look out for, when writing tests. Imagine the code above was tucked away among hundereds of other lines of code, then the chances of seeing it are really quite small. The test wouldn't be just two lines long and the problem wouldn't be jumping out of the page.

One way to look at the problem is to say that there is a bug because the code isn't fulfilling its contract. OK, I use "contract" in the loose sense of the word, but the Javadoc is basically a contract. It tells anyone calling that method what to expect, yet the codes is not doing what the user expects.

So perhaps one solution is to not only entirely exercise the code, but entirely exercise the contract? Is there a way to translate the Javadoc contract into something more concrete which the testing tools can help me check? Yes, namely my using some kind of Design (or Program) by Contract (DBC or PBC) framework. JSR-303 isn't strictly DBC, but close. It lets you use annotations to state your expectations about parameters passed to methods, as well as your expectation about the result being returned. You can create your own complex constraints quite easily. I added the following annotations to my code to help in my quest for bug free code:

    @Size(min=0, max=1)
    public String getResult() {

Now, method validation (validating method calls, rather than validating the bean itself) is something which comes as an extra in Hibernate Validator, and which really isn't part of JSR-303 - it's only described in Appendix C as optional. To test this, I used Google Guice to add an AOP interceptor to any methods marked with the @Valid annotation, and in that interceptor, I call the Hibernate Method Validator. I end up with something like this:

    Injector injector = Guice.createInjector(new AbstractModule(){
        protected void configure() {
                    new MethodValidatorInterceptor());
    SomeClass someClass = injector.getInstance(SomeClass.class);
    someClass.init(true, false);
    assertEquals("a", someClass.getResult());

    someClass = injector.getInstance(SomeClass.class);
    someClass.init(false, true);
    assertEquals("b", someClass.getResult());
public class MethodValidatorInterceptor<T> implements MethodInterceptor {

    public Object invoke(MethodInvocation invocation) throws Throwable {

        //validate all inputs
        Set<MethodConstraintViolation<T>> mcvs =
               invocation.getMethod(), invocation.getArguments());
        if(mcvs.size() != 0){
            throw new IllegalArgumentException(String.valueOf(mcvs));

        //call through to the actual method being called
        Object ret = invocation.proceed();

        //validate result
        mcvs = methodValidator.validateReturnValue((T)invocation.getThis(),
            invocation.getMethod(), ret);
        if(mcvs.size() != 0){
            throw new IllegalArgumentException(String.valueOf(mcvs));

        return ret;

The above is something which a (Java EE) container should do for me - I was just messing around with simple classes in a simple Java Project. Now, it isn't quite complete, because I still have 100% coverage, and I still have that bug, because the new annotations haven't really done anything useful. Well that isn't entirely true - the reader of the code knows that the contract is a little stricter than it was when it was simple Javadoc. The reader may assume that the system will check these constraints when the method is called. But while there is still a bug, I've laid the path for adding some full pre- or post-conditions. The next step was to add a new annotation, an interface and make use of them in the interceptor.

@Target( { ElementType.METHOD })
public @interface PreCondition {
    Class<? extends ConditionChecker> implementation();

/** Any pre- or post-condition is written in
  * an implementation of this interface
public interface ConditionChecker {
    void checkCondition()
        throws ConstraintViolationException;

The annotation can be added to the business code, in this case to add a pre-condition. I created a similar annotation for post-conditions. When I add the pre-condition to a method, I also state which class contains the code for checking that pre-condition:

    @Size(min=0, max=1)
    public String getResult() {

The interceptor can check for the presence of such a pre-condition annotation before calling through to the method being called. If the annotation is found, the interceptor attempts to create an instance of the implementation class, and calls it's "checkCondition" method.

So the final part of this puzzle is to write a pre-condition which will help me to fail to get 100% coverage when I test with the test shown near the top of this post. Here it is, implemented as a static final inner class inside the SomeClass class, so that it has access to the fields "a" and "b":

public class MyPreAndPostCondition implements ConditionChecker {
    public void checkCondition()
            throws ConstraintViolationException {

        //im going to list all combinations of
        //a and b which I support
        if(!a && b) return;
        if(!b && a) return;
        if(!b && !a) return;
        if(a && b) return;

When I now test my code, I no longer get 100% coverage, because the last two lines in the pre-condition are not covered. Hooray! The tools can now tell me what I still need to test...

Now, while this technical solution works, I think it is really ugly. Like I said, if the code which is causing the problem were to be found within one or two hundred other lines of code, and were reliant on local variables rather than fields in my class, I would have no chance of using a pre-condition like this to help me locate the problem.

So to sum up, DBC isn't going to help me solve the problem that 100% code coverage can still contain errors. I think DBC frameworks (and there are a lot out there, some which do exactly what I have done here using the @PreCondition annotation) help to make contracts more concrete. If you use method validation from Hibernate Validator, you don't have to write as much Javadoc, because the reader knows that the container will give up before calling the method if anything fails to validate. To me as a programmer, that is much more satisfying than praying that some Javadoc reflects what I have really implemented.

I have known programmers who don't write tests because a DBC framework is in place and that makes them feel safe. But just because you declare a contract, does not mean the code actually works. Whether the code fails hard with a validation exception or at some time later because your code is buggy, makes no difference - both are inacceptable! From that perspective, DBC contracts are simply hints to the tester what could be useful tests, and they ensure that the code fails hard, early.

While I was refreshing my testing skills, I also learned the difference between mocks and stubs. For years I had always thought they were the same thing, but it turns out that stubs return pre-fed answers, whereby mocks check the sequence of calls to them too. On a different thread at DZone, someone made a point that unit testing was pointless because it never helped them find bugs, and it caused lots of work when refactoring, because all that does is break their tests. I'd say that this is simply a question of black box versus white box testing. Black box unit testing should never break if you refactor your code - the tests are simply clients to the code which you are refactoring, and tools like Eclipse will modify the calling code if you modify the interfaces being called, including tests. You can get pretty good testing results by just using black box tests - the large majority of the tests I write are black box tests and when I write such tests, I tend to have bug free code.

I've talked about writing contracts to help the reader determine what they should expect when they use your code. Unit tests themselves work similarly, because they show the reader examples of how to call your code and what to expect when your code changes system state. They hint to the reader how the writer intended the code to be used. While I don't advocate TDD (perhaps only because I have never been on a project which used it or at a company which valued quality enough to warrant TDD), I do encourage writing tests and using validation and pre-/post-conditions because they help document the code with the added bonus of finding the occassional bug. At the same time, I am an architect and we need to keep things like budgets in mind. You have an influence on your budget when you estimate, assuming you are allowed to do that. Your customer might push you to reduce your estimates, and that is an indication about their commitment to quality, because they won't budge on scope or delivery dates! So write as many tests as you can, within your budget and start with the code which is most complex and which gets called most often. and remember, 100% coverage is not really your best friend because bugs may still lurk.

© 2011, Ant Kutschera
Social Bookmarks :  Add this post to Slashdot    Add this post to Digg    Add this post to Reddit    Add this post to Delicious    Add this post to Stumble it    Add this post to Google    Add this post to Technorati    Add this post to Bloglines    Add this post to Facebook    Add this post to Furl    Add this post to Windows Live    Add this post to Yahoo!

A really simple but powerful rule engine

UPDATE: Version 2.2.0, JavaScript (Nashorn) rules in the JVM - see here.

UPDATE: Version 2.1.0, Java 8, Maven, GitHub - see here.

UPDATE: Version 2.0 of the library now exists which supports Scala. It is a breaking change in that "Action" instances as shown below are now "AbstractAction", and the "Action" class is only supported in Scala, where functions can be passed to the action constructor instead of having to override the AbstractAction. Scala collections are also supported in the engine.

I have the requirement to use a rule engine. I want something light weight and fairly simple, yet powerful. While there are products out there which are super good, I don't want something with the big learning overhead. And, I fancied writing my own!

Here are my few basic requirements:

  • Use some kind of expression language to write the rules,
  • It should be possible to store rules in a database,
  • Rules need a priority, so that only the best can be fired,
  • It should also be possible to fire all matching rules,
  • Rules should evaluate against one input which can be an object like a tree, containing all the information which rules need to evaluate against
  • Predefined actions which are programmed in the system should be executed when certains rules fire.

So to help clarify those requirements, imagine the following examples:

1) In some forum system, the administrator needs to be able to configure when emails are sent.

Here, I would write some rules like "when the config flag called sendUserEmail is set to true, send an email to the user" and "when the config flag called sendAdministratorEmail is true and the user has posted less than 5 postings, send an email to the administrator".

2) A tarif system needs to be configurable, so that the best tarif can be offered to customers.

For that, I could write rules like these: "when the person is younger than 26 the Youth tarif is applicable", "when the person is older than 59, the Senior tarif is applicable", and "when the person is neither a youth, nor a senior, then they should be given the Default tarif, unless they have had an account for more than 24 months, in which case they should be offered the Loyalty tarif".

3) A train ticket can be considered to be a product. Depending upon the travel request, different products are suitable.

A rule here, could be something like: "if the travel distance is more than 100km and first class is desired, then product A is to be sold."

Finally, a more complex example, involving some iteration of the input, rather than just property evaluation:

4) Timetable software needs to deterimine when students can leave school.

A rule for that might read: "If a class contains any student under age 10, the entire class gets to leave early. Otherwise, they leave at the normal time."

So, with those requirements in mind, I went to look for an expression language. I started with the unified expression language specified in JSP 2.1. Using the jasper jar used in Tomcat and Apache Commons EL jar, I got something up and running very quickly. Then I discovered the MVEL library from Codehaus.org, which incidentally is used in Drools (the leading Java rule engine?) and it worked even better. It offers far more functionality as far as I can tell.

So, I designed my rule engine to work like this:

1) An engine is configured with some rules.

2) A rule has these attributes:
    - namespace: an engine may contain many rules, but only some may be relevant to a particular call and this namespace can be used for filtering
    - name: a unique name within a namespace
    - expression: an MVEL expression for the rule
    - outcome: a string which the engine might use if this rules expression evaluates to true
    - priority: an integer. The bigger the value, the higher the priority.
    - description: a useful description to aid the management of rules.

3) The engine is given an input object and evaluates all rules (optionally within a namespace) and either:
    a) returns all rules which evaluate to true,
    b) returns the outcome (string) from the rule with the highest priority, out of all rules evaluating to true,
    c) execute an action (defined within the application) which is associated with the outcome of the rule with the highest priority, out of all rules evaluating to true.

4) "Action"s are instances of classes which the application programmer can supply. An action is given a name. When the engine is asked to execute an action based on the rules, the name of the action matching the "winning" rule's outcome is executed.

5) A rule can be built up of "sub-rules". A subrule is only ever used as a building block on which to base more complex rules. When evaluating rules, the engine will never select a subrule to be the best (highest priority) "winning" rule, i.e. one evaluating to true. Subrules make it easier to build complex rules, as I shall show shortly.

So, time for some code!

First, let's look at the code for the tarif system:

Rule r1 = new Rule("YouthTarif", "input.person.age < 26", "YT2011", 3, "ch.maxant.someapp.tarifs", null);
Rule r2 = new Rule("SeniorTarif", "input.person.age > 59", "ST2011", 3, "ch.maxant.someapp.tarifs", null);
Rule r3 = new Rule("DefaultTarif", "!#YouthTarif && !#SeniorTarif", "DT2011", 3, "ch.maxant.someapp.tarifs", null);
Rule r4 = new Rule("LoyaltyTarif", "#DefaultTarif && input.account.ageInMonths > 24", "LT2011", 4, "ch.maxant.someapp.tarifs", null);
List<Rule> rules = Arrays.asList(r1, r2, r3, r4);

Engine engine = new Engine(rules, true);

TarifRequest request = new TarifRequest();
request.setPerson(new Person("p"));
request.setAccount(new Account());

String tarif = engine.getBestOutcome(request);

So, in the above code, I have added 4 rules to the engine, and told the engine to throw an exception if any rule cannot be pre-compiled. Then, I created a TarifRequest, which is the input object. That object is passed into the engine, when I ask the engine to give me the best outcome. In this case, the best outcome is the string "YT2011", the name of the most suitable tarif for the customer I added to the tarif request.

How does it all work? When the engine is given the rules, it does some validation on them, and pre-compiles the rules (to improve overall performance). Notice how the first two rules refer to an object called "input"? That is the object passed into the "getBestOutcome" method on the engine. The engine passes the input object to the MVEL class together with each rules expression. Anytime an expression evaluates to "true", the rule is put to the side as a candidate to be the winner. At the end, the candidates are sorted in order of priority, and the outcome field of the rule with the highest priority is returned by the engine.

Notice how the third and fourth rules contain the '#' character. That is not standard MVEL expression language. The engine examines all rules when they are passed to it, and it replaces any token starting with a hash symbol, with the expression found in the rule named the same as the token. It wraps the expression in brackets. The logger outputs the full rule after reference rules have been resolved and replaced, just in case you want to check the rule.

In the above business case, we were only interested in the best tarif for the customer. Equally, we might have been interested in a list of possible tarifs, so that we could offer the customer a choice. In that case, we could have called the "getMatchingRules" method on the engine, which would have returned all rules, sorted by priority. The tarif names are (in this case) the "outcome" field of the rules.

In the above example, I wanted to receive any of the four outcomes, from the four rules. Sometimes however, you might want to build complex rules based on building blocks, but you might never want those building blocks to be a winning outcome. The train trip example from above can be used to show what I mean here:

Rule rule1 = new SubRule("longdistance", "input.distance > 100", "ch.maxant.produkte", null);
Rule rule2 = new SubRule("firstclass", "input.map[\"travelClass\"] == 1", "ch.maxant.produkte", null);
Rule rule3 = new Rule("productA", "#longdistance && #firstclass", "productA", 3, "ch.maxant.produkte", null);
List<Rule> rules = Arrays.asList(rule1, rule2, rule3);

Engine e = new Engine(rules, true);

TravelRequest request = new TravelRequest(150);
request.put("travelClass", 1);
List rs = e.getMatchingRules(request); 

In the above code, I build rule3 from two subrules. But I never want the outcomes of those building blocks to be output from the engine. So I create them as SubRules. SubRules don't have an outcome field or priority. They are simply used to build up more complex rules. After the engine has used the sub-rules to replace all tokens beginning in a hash during initialisation, it discards the SubRules - they are not evaluated.

The TravelRequest above takes a distance in the constructor, and contains a map of additional parameters. MVEL let's you easily access map values using the syntax shown in rule 2.

Next, consider the business case of wanting to configure an forum system. The code below introduces actions. Actions are created by the application programmer and supplied to the engine. The engine takes the outcomes (as described in the first example), and searches for actions with the same names as those outcomes, and calls the "execute" method on those actions (they all implement the IAction interface). This functionality is useful when a system must be capable of predefined things, but the choice of what to do needs to be highly configurable and independent of deployment.

Rule r1 = new Rule("SendEmailToUser", "input.config.sendUserEmail == true", "SendEmailToUser", 1, "ch.maxant.someapp.config", null);
Rule r2 = new Rule("SendEmailToModerator", "input.config.sendAdministratorEmail == true and input.user.numberOfPostings < 5", "SendEmailToModerator", 2, "ch.maxant.someapp.config", null);
List<Rule> rules = Arrays.asList(r1, r2);
final List<String> log = new ArrayList<String>();
Action<ForumSetup, Void> a1 = new Action<ForumSetup, Void>("SendEmailToUser") {
  public Void execute(ForumSetup input) {
    log.add("Sending email to user!");
    return null;
Action<ForumSetup, Void> a2 = new Action<ForumSetup, Void>("SendEmailToModerator") {
  public Void execute(ForumSetup input) {
    log.add("Sending email to moderator!");
    return null;

Engine engine = new Engine(rules, true);

ForumSetup setup = new ForumSetup();
engine.executeAllActions(setup, Arrays.asList(a1, a2));

In the code above, the actions are passed to the engine when we call the "executeAllActions" method. In this case, both actions are executed, because the setup object causes both rules to evaluate to true. Note that the actions are executed in the order of highest priority rule first. Each action is only ever executed once - it's name is noted after execution and it will not be executed again, until the engines "execute*Action*" method is called again. Also, if you only want the action associated with the best outcome to be executed, call the "executeBestAction" method instead of "executeAllActions".

Finally, let's consider the classroom example.

String expression = 
    "for(student : input.students){" +
    "	if(student.age < 10) return true;" +
    "}" +
    "return false;";

Rule r1 = new Rule("containsStudentUnder10", expression , "leaveEarly", 1, "ch.maxant.rules", "If a class contains a student under 10 years of age, then the class may go home early");
Rule r2 = new Rule("default", "true" , "leaveOnTime", 0, "ch.maxant.rules", "this is the default");
Classroom classroom = new Classroom();
classroom.getStudents().add(new Person(12));
classroom.getStudents().add(new Person(10));
classroom.getStudents().add(new Person(8));

Engine e = new Engine(Arrays.asList(r1, r2), true);
String outcome = e.getBestOutcome(classroom);

The outcome above is "leaveEarly", because the classroom contains one student whose age is less than 10. MVEL let's you write some pretty comprehensive expressions, and is really a programming language in it's own right. The engine simply requires a rule to return true, if the rule is to be considered a candidate for firing.

There are more examples in the JUnit tests contained in the source code.

So, the requirements are fulfiled, except for "It should be possible to store rules in a database". While this library doesn't support reading and writing rules to / from a database, rules are String based. So it wouldn't be hard to create some JDBC or JPA code which reads rules out of a database and populates Rule objects and passes them to the Engine. I haven't added this to the library, because normally these things as well as the management of rules is something quite project specific. And because my library will never be as cool or popular as Drools, I'm not sure it would be worth my while to add such functionality.

I've put the rule engine into an OSGi library with the LGPL licence and it can be downloaded from my tools site. This library depends on MVEL, which can be downloaded here (I used version 2.0.19). If you like it, let me know!

© 2011, Ant Kutschera

Social Bookmarks :  Add this post to Slashdot    Add this post to Digg    Add this post to Reddit    Add this post to Delicious    Add this post to Stumble it    Add this post to Google    Add this post to Technorati    Add this post to Bloglines    Add this post to Facebook    Add this post to Furl    Add this post to Windows Live    Add this post to Yahoo!