nosewheelie

Technology, mountain biking, politics & music.

Archive for August, 2008

Handling nulls

without comments

I got some feedback to my Error handling with Either, or, Why Either rocks! post, basically saying it was incomprehensible.

So, here’s a nice introductory post on Option: Handling nulls. Should be a gentler introduction.

Written by Tom Adams

August 21st, 2008 at 11:42 am

Scoodi featured on Brisbane Extra

without comments

Scoodi, the Rails app I’ve spent a fair bit of this year working on was featured on Brisbane Extra yesterday.

Brad and Kristian do a lovely job of marketing :)

Written by Tom Adams

August 15th, 2008 at 1:19 pm

Posted in Environment,Ruby,Technology

Tagged with

Deploying a Maven artefact without a repository using Ant

without comments

You know the drill, you’re working on an open source project (or two), and users start demanding Maven support. Why you ask yourself? Why, would anyone want to use Maven. But then, they assure you that it’s not by choice. That yes, they know Maven sucks, that it makes the simple hard and moderate impossible. But they’ve been forced to use it, and they’d like help. Now you know Ant has problems, but Maven? Seriously?

Seriously. So you decide to add in Maven support. After all, you’re running the project for the people, and having Maven support would help adoption, so it’s all good (and you get to write lame blog posts too!).

Now here’s where the fun begins…

The problem is that you’re using a tool other than Maven to build the project(s), and you have no Maven repository into which to deploy your project artefacts. The example I’ll show is using Google Code, but this could be any Subversion service, the process should be similar – with the exception of the SVN commands – for exposing a repository over HTTP. I’m also using Ant as the build tool, again, this should be replicable in other tools.

To save you the hassle of find them yourself, here’s the two links you’ll need. Firstly, here’s the Guide to uploading artifacts to the Central Repository, and secondly, here’s the Maven Deploy Plugin Usage overview. Be warned though, like most things Maven, this documentation is pretty scarce, for example what URL schemes does the deploy-file plugin take? Will it accept svn://... URLs? Who knows, but this is what worked for me.

All in all, the process is fairly simple once you figure it all out. The thing we’ll be building is called a Maven Bundle, and is simply a jar (zip) file containing certain content. We’ll then “deploy” this into a local “repository”, creating the necessary directory structure.

  1. Ensure your project is creating three artefacts, a main jar, a sources jar, and a javadoc jar. The last two (source & javadoc) are optional, however they seem to be standard for most Maven bundles, and Maven aware tools (such as IntelliJ) will automatically link the source and javadoc jars to the main classes.

    As detailed in the guide, they need to be named as follows:

    ${artifactId}-${version}.jar
    ${artifactId}-${version}-sources.jar
    ${artifactId}-${version}-javadoc.jar
    

    Note that if your project also contains Scala code, and Scaladoc (as Functional Java & Instinct do), I’ve not looked into how to get these hooked up into the Maven bundle. Lift is using Maven so I guess it’s possible…

  2. Create a Maven POM file, the guide linked above shows you the minimum you’ll need to get started (there are rules in the guide, that tell you what you must and can’t have in a POM for deployment). Here’s Instinct’s POM:

    <?xml version="1.0"?>
    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
        <modelversion>4.0.0</modelversion>
        <groupid>com.googlecode.instinct</groupid>
        <artifactid>instinct-core</artifactid>
        <packaging>jar</packaging>
        <name>Instinct Core</name>
        <description>Instinct Behaviour Driven Development (BDD) Framework</description>
        <version>0.1.9</version>
        <url>http://instinct.googlecode.com/</url>
        <licenses>
            <license>
                <name>The Apache Software License, Version 2.0</name>
                <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
                <distribution>repo</distribution>
            </license>
        </licenses>
        <scm>
            <url>http://instinct.googlecode.com/svn/</url>
        </scm>
        <dependencies>
          ...
        </dependencies>
    </project>
    
  3. You’ll now need to build your bundle, the contents should look like this:

    pom.xml
    ${artifactId}-${version}.jar
    ${artifactId}-${version}-sources.jar
    ${artifactId}-${version}-javadoc.jar
    

    Here’s some Ant XML showing how this can be done:

    <property name="build.dir" value="build"/>
    <property name="release.dir" value="${build.dir}/release"/>
    <property name="maven-bundle.jar" value="instinct-0.1.9-bundle.jar"/>
    <target name="-maven-bundle" depends="-jar,-sources-jar,-javadoc">
        <mkdir dir="${release.dir}"/>
        <jar destfile="${release.dir}/${maven-bundle.jar}">
            <fileset dir="${basedir}" includes="pom.xml"/>
            <fileset dir="${build.dir}" includes="${project.jar}"/>
            <fileset dir="${build.dir}" includes="${sources.jar}"/>
            <fileset dir="${build.dir}" includes="${javadoc.jar}"/>
        </jar>
    </target>
    

    And here’s what it builds:

    $ unzip -l build/release/instinct-0.1.9-bundle.jar Archive:  build/release/instinct-0.1.9-bundle.jar
      Length     Date   Time    Name
     --------    ----   ----    ----
            0  08-08-08 22:48   META-INF/
           98  08-08-08 22:48   META-INF/MANIFEST.MF
         2136  08-08-08 12:36   pom.xml
       378565  08-08-08 22:48   instinct-0.1.9.jar
       315685  08-08-08 15:28   instinct-0.1.9-sources.jar
       693521  08-08-08 22:48   instinct-0.1.9-javadoc.jar
     --------                   -------
      1390005                   6 files
    
  4. Create a spot in your svn for the maven artefacts, this will become your “repository”. I added mine here: http://instinct.googlecode.com/svn/artifacts/maven/.
  5. Take a checkout of this directory, you’ll need to store it somewhere local to the project, you’ll need its path later. I checked mine out into a peer directory to my project, so from the project it’s accessed as “../artifacts/maven”. This will be a local version of your repository.
  6. You’ll now need to “deploy” your classes jar into this local repository, as follows (documented in the deploy plugin usage):

    $ mvn deploy:deploy-file -Durl=file://../artifacts/maven -DrepositoryId=local-svn-artifacts -Dfile=instinct-core-0.1.9.jar -DpomFile=pom.xml
    

    I tried to get the deploy-file goal to deploy to a remove SVN directly with no luck, YMMV. Again, the documentation is lacking here.

    Note that the deploy-file goal does not accept bundles, it needs to be just your classes jar. If you want your sources and javadoc there as well, you’ll need to copy and hash them also (see Ant target below).

    Alternatively, you can have your build tool do this for you:

    <property name="maven-bundle.jar" value="${project.shortname}-${project.version.full}-bundle.jar"/>
    <property name="maven-repo.dir" value="${basedir}/../artifacts/maven"/>
    <property name="maven-repo-release.dir" value="${maven-repo.dir}/com/googlecode/instinct/instinct-core/${project.version.full}"/>
    <exec dir="${basedir}" executable="mvn" failonerror="true" os="Mac OS X,Linux">
      <arg value="deploy:deploy-file"/>
      <arg value="-Durl=file://${maven-repo.dir}"/>
      <arg value="-DrepositoryId=local-svn-artifacts"/>
      <arg value="-Dfile=${build.dir}/${project.jar}"/>
      <arg value="-DpomFile=${basedir}/pom.xml"/>
    </exec>
    <copy file="${release.dir}/${maven-bundle.jar}" todir="${maven-repo-release.dir}"/>
    <copy file="${build.dir}/${sources.jar}" todir="${maven-repo-release.dir}"/>
    <copy file="${build.dir}/${javadoc.jar}" todir="${maven-repo-release.dir}"/>
    <checksum file="${maven-repo-release.dir}/${sources.jar}" algorithm="MD5" forceOverwrite="yes" fileext=".md5"/>
    <checksum file="${maven-repo-release.dir}/${sources.jar}" algorithm="SHA" forceOverwrite="yes" fileext=".sha1"/>
    <checksum file="${maven-repo-release.dir}/${javadoc.jar}" algorithm="MD5" forceOverwrite="yes" fileext=".md5"/>
    <checksum file="${maven-repo-release.dir}/${javadoc.jar}" algorithm="SHA" forceOverwrite="yes" fileext=".sha1"/>
    
  7. Check the structure of the local repository, it should look something like this:

    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9.jar
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9-javadoc.jar.sha1
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9-sources.jar
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9.jar.md5
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9-javadoc.jar
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9-sources.jar.md5
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9-bundle.jar
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9-javadoc.jar.md5
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9.jar.sha1
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9.pom
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9.pom.md5
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9.pom.sha1
    maven/com/googlecode/instinct/instinct-core/0.1.9/instinct-core-0.1.9-sources.jar.sha1
    maven/com/googlecode/instinct/instinct-core/maven-metadata.xml
    maven/com/googlecode/instinct/instinct-core/maven-metadata.xml.md5
    maven/com/googlecode/instinct/instinct-core/maven-metadata.xml.sha1
    
  8. If you’re happy with the local repository, commit it into your (svn) repository. Instinct’s 0.1.9 release was deployed into this URL: http://instinct.googlecode.com/svn/artifacts/maven/com/googlecode/instinct/instinct-core/0.1.9/.
  9. You’re now done with the technical side of building a bundle. You’ll then need to log a JIRA issue for the Maven developers to upload your bundle (following the instructions in the guide). Then wait, and hope… Here’s the Instinct 0.1.9 request.

There is another way that users can download your Maven artefacts without them needing to be deployed to the central Maven repository, it’s detailed in the introduction to Maven repositories. Basically client projects of your project need to add a repository to their POM as follows (substituting the ID and URL belong for that of your repository):

<project>
  ...
  <repositories>
    <repository>
      <id>instinct-repository</id>
      <url>http://instinct.googlecode.com/svn/artifacts/maven/</url>
    </repository>
  </repositories>
  ...
</project>

Note that the process I’ve described of uploading to the central repository process is a manual one. Looking at the Maven issues for bundle uploads, it appears that if you don’t provide rsync or ssh access to your repository, you need to make manual upload requests. Others who’ve followed a similar process to this one are asking whether the Maven sync can happen automatically, to which I’ve not seen an answer. The documentation isn’t overly clear on this last point. A friend of mine asked on the Maven IRC channel yesterday and was told syncing over HTTP “just works”, though this isn’t evident by the details in the guide, the issues being reported nor the list of automatically synced repositories.

For those interested, these instructions were gleaned from looking at other projects that deploy Maven artefacts, including GWT-Maven and the Struts 2 Maven Plugin repository.

Written by Tom Adams

August 11th, 2008 at 8:25 am

Posted in Functional,Instinct,Java

Tagged with , ,

Instinct 0.1.9 Release

without comments

I’m happy to announce the release of Instinct 0.1.9. This is a maintenance release that also allowed me to introduce some new features such as custom lifecycles. Other tidbits include multiple specification failures reported, Scala examples, additional Functional Java matchers (List, Either, Option), Maven bundle and a seperate source JAR.

Downloads are available from the project site.

Here’s the full list of changes:

  • Core Features
    • Custom specification lifecycles can now be plugged in using the @Context annotation. This would allow for example, a Spring application context to be initialised and wired into each specification method allowing integration-style specifications using a Spring beans.
    • Multiple errors are now displayed when a specification fails with more than one exception.
  • Expectation API
    • Added fj.data.List matchers: expect.that(List.nil().cons(1)).isEqualTo(List.nil().cons(1))
    • Added fj.data.Option matchers: expect.that(Some(1)).isSome(1), expect.that(foo.bar()).isNone().
    • Added fj.data.Either matchers: expect.that(error()).isLeft(runtimeException), expect.that(foo.bar()).isRight(42).
  • Scala integration
    • Added Scala stack example, showing the use of Instinct under Scala to spec out Scala code.
  • Maven integration
    • Added Maven bundle to allow uploading to central Maven repository.
  • Packaging
    • Moved source code out of main jar into instinct-<version>-sources.jar (for Maven).
    • Moved javadoc into jar instead of zip instinct-<version>-javadoc.jar (for Maven).
  • Infrastructure
    • Upgraded to Functional Java 2.10.
    • Downgraded (again) to CGLib 2.1.3 (for Maven integration).
  • Bugs
    • (Issue 21) Expected exception try-catch should only wrap specs, not before and after.
    • (Issue 19) Throwing exception out of mocked code confused expected exception handling.
    • (Issue 40) Formatting of multiple exception report could be nicer.

Written by Tom Adams

August 8th, 2008 at 4:10 pm

Posted in BDD,Instinct,Java,Scala

Error handling with Either, or, Why Either rocks!

with 3 comments

Instinct, like most xUnit-like frameworks provides the ability to run methods, and have the status of those methods reported. In xUnit frameworks these methods are called tests, in Instinct they’re called specifications.

Specifications are ordinary instance methods that are marked in a way (naming convention or annotation) that tells Instinct to run them. Each specification has a lifecycle associated with it, where both the creator of the method (the developer specifying code) and the framework itself performs pre- and post-specification steps (Instinct tries to take away and simplify a lot of the drudgery involved in traditional testing).

Specifications have the following lifecycle (the default implementation can be overridden):

  1. The context class for the specification is created.
  2. The mockery is reset, all mocks now contain no expectations.
  3. Specification actors are auto-wired.
  4. Before specification methods are run.
  5. The specification is run.
  6. After specification methods are run.
  7. Mock expectations are verified.

Any step of this lifecycle can throw exceptions causing the specification to fail. For example a before specification method may throw a NullPointerException, or a specification may pass while a mock used in it may not have an expectation met.

The framework needs flexibility in choosing which parts of the lifecycle to run, which parts are important when executing the specification, what failures constitute stopping the run of a specification, etc.

Here’s the code we’re starting with:

private SpecificationResult runSpecification(final SpecificationMethod specificationMethod) {
  final long startTime = clock.getCurrentTime();
  try {
    final Class<?> contextClass = specificationMethod.getContextClass();
    final Object instance = invokeConstructor(contextClass);
    runSpecificationLifecycle(instance, specificationMethod);
    return createSpecResult(specificationMethod, SPECIFICATION_SUCCESS, startTime);
  } catch (Throwable exceptionThrown) {
    final SpecificationRunStatus status = new SpecificationRunFailureStatus(exceptionSanitiser.sanitise(exceptionThrown));
    return createSpecResult(specificationMethod, status, startTime);
  }
}

private void run(final Object contextInstance, final SpecificationMethod specificationMethod) {
  Mocker.reset();
  actorAutoWirer.autoWireFields(contextInstance);
  try {
    runMethods(contextInstance, specificationMethod.getBeforeSpecificationMethods());
    runSpecificationMethod(contextInstance, specificationMethod);
  } finally {
    try {
      runMethods(contextInstance, specificationMethod.getAfterSpecificationMethods());
    } finally {
      Mocker.verify();
    }
  }
}

This implementation of of the specification runner is overly simplistic. It runs everything within a large try-catch block, which means there’s no way to tell which part of the specification failed (before, spec, after, etc.). It also cannot collect up errors, so if an error occurs in a specification and a mock fails to verify, only the verification error is propagated. These are currently two of the highest priority user reported issues on Instinct.

Here’s my first attempt at isolating which part of the specification failed, each of the constants passed to fail define the location of the failure.

public SpecificationResult run(final SpecificationMethod specificationMethod) {
  try {
    final Class<?> contextClass = specificationMethod.getContextClass();
    final Object instance = invokeConstructor(contextClass);
    Mocker.reset();
    try {
      actorAutoWirer.autoWireFields(instance);
      try {
        runMethods(instance, specificationMethod.getBeforeSpecificationMethods());
        try {
          runSpecificationMethod(instance, specificationMethod);
          return result(specificationMethod, SPECIFICATION_SUCCESS);
        } catch (Throwable t) {
          return fail(specificationMethod, t, SPECIFICATION);
        } finally {
          try {
            try {
              runMethods(instance, specificationMethod.getAfterSpecificationMethods());
            } catch (Throwable t) {
              return fail(specificationMethod, t, AFTER_SPECIFICATION);
            }
          } finally {
            try {
              Mocker.verify();
            } catch (Throwable t) {
              return fail(specificationMethod, t, MOCK_VERIFICATION);
            }
          }
        }
      } catch (Throwable t) {
        return fail(specificationMethod, t, BEFORE_SPECIFICATION);
      }
    } catch (Throwable t) {
      return fail(specificationMethod, t, AUTO_WIRING);
    }
  } catch (Throwable t) {
      return fail(specificationMethod, t, CLASS_INITIALISATION);
  }
}

Obviously, this is very ugly, it’s also hard to reason about. But, as we now have the location of the failure we can make decisions as to whether we fail the specification, or not, so we’ve solved our first issue. But we haven’t made our second task any easier, we aren’t generally able to keep processing (we still validate mocks in the above code upon specification failure) and we don’t collect all the errors that occur.

And at about this time enters Either (in Scala):

The Either type represents a value of one of two possible types (a disjoint union). The data constructors; Left and Right represent the two possible values. The Either type is often used as an alternative to Option where Left represents failure (by convention) and Right is akin to Some.

Either can be used in place of conventional exception handling in Java, or, to wrap APIs that use conventional exception handling (a more thorough treatment of this issue is given in Lazy Error Handling in Java, Part 3: Throwing Away Throws). Here’s an example of the latter, using both Either and Option (discussed later).

public Either<Throwable, List<Field>> wireActors(final Object contextInstance) {
  try {
    return right(actorAutoWirer.autoWireFields(contextInstance));
  } catch (Throwable t) {
    return left(t);
  }
}

...

public Option<Throwable> verifyMocks() {
  try {
    Mocker.verify();
    return none();
  } catch (Throwable t) {
    return some(t);
  }
}

At a high level, the good thing about using Either is that your methods no longer lie; they don’t declare that they’ll return an Int, or, maybe, they’ll throw an exception, they come right out and say it: I’ll return either an exception or an Int. This is akin to conventional checked exceptions in Java (which Scala does away with), where a checked exception is used to represent a recoverable failure (enforced by the compiler) and an unchecked exception to represent an unrecoverable failure (not compiler enforced). Scala takes the correct approach here, it uses unchecked exceptions to represent the bottom value in non-terminating functions, and Either to represent recoverable failure.

Either is also much more flexible than exceptions, you can map across it, convert it into an option, add them into a container, and generally treat them like any other data structure [1].

So armed with this new knowledge, here’s the new specification lifecycle broken out from the runner itself (note, there are eleven steps in the lifecycle, including validation, however only these are exposed).

interface SpecificationLifecycle {
  <T> Either<Throwable, ContextClass> createContext(Class<T> contextClass);
  Option<Throwable> resetMockery();
  Either<Throwable, List<Field>> wireActors(Object contextInstance);
  Option<Throwable> runBeforeSpecificationMethods(
      Object contextInstance, List<LifecycleMethod> beforeSpecificationMethods);
  Option<Throwable> runSpecification(
      Object contextInstance, SpecificationMethod specificationMethod);
  Option<Throwable> runAfterSpecificationMethods(
      Object contextInstance, List<LifecycleMethod> afterSpecificationMethods);
  Option<Throwable> verifyMocks();
}

Now we need to make use of this in the specification runner, one step of which is determining the overall result, from the sequence of steps. Here’s my first attempt at this, using Functional Java’s Either to represent the result of each of the steps.

public <T extends Throwable> Either<List<T>, SpecificationResult> determineLifecycleResult(
    final Either<T, Unit> createContextResult,
    final Either<T, Unit> restMockeryResult,
    final Either<T, Unit> wireActorsResult,
    final Either<T, Unit> runBeforeSpecificationMethodsResult,
    final Either<T, SpecificationResult> runSpecificationResult,
    final Either<T, Unit> runAfterSpecificationMethodsResult,
    final Either<T, Unit> verifyMocksResult) {
  List<T> errors = List.nil();
  if (createContextResult.isLeft()) {
    errors = errors.cons(createContextResult.left().value());
  }
  if (restMockeryResult.isLeft()) {
    errors = errors.cons(restMockeryResult.left().value());
  }
  if (wireActorsResult.isLeft()) {
    errors = errors.cons(wireActorsResult.left().value());
  }
  if (runBeforeSpecificationMethodsResult.isLeft()) {
    errors = errors.cons(runBeforeSpecificationMethodsResult.left().value());
  }
  if (runSpecificationResult.isLeft()) {
    errors = errors.cons(runSpecificationResult.left().value());
  }
  if (runAfterSpecificationMethodsResult.isLeft()) {
    errors = errors.cons(runAfterSpecificationMethodsResult.left().value());
  }
  if (verifyMocksResult.isLeft()) {
    errors = errors.cons(verifyMocksResult.left().value());
  }
  return errors.isNotEmpty() ? Either.<List<T>, SpecificationResult>left(errors)
      : Either.<List<T>, SpecificationResult>right(runSpecificationResult.right().value());
}

All those ifs are a bit ugly (what happens when we have more?), and we’ve got a mutable list, surely we can do better? We’ve spotted a pattern here, and we could clean this up by folding across a list of results, pulling out the left of each Either, however Either does this for us, using Either.lefts() (it performs the fold for you).

Here’s the next cut, making use of a list of results and Either.left():

public <T extends Throwable> Either<List<Unit>, Unit> determineLifecycleResult(
    final List<Either<T, Unit>> allResults, final Either<T, Unit> specificationResult) {
  final List<T> errors = lefts(allResults);
  return errors.isEmpty() ?
      Either.<List<T>, Unit>right(specificationResult.right().value()) :
      Either.<List<T>, Unit>left(errors);
}

So what’s this doing? It takes a list of results and goes through each of the lefts (the errors) returning them as a list. As Either is a disjunction (we’ll have an error or a result, but not both), if any of the results contain an error on the left, our list will be non-empty, meaning our specification failed to run. In this case we return the errors on the left. If we have no errors (i.e. the list is empty) we return the real result on the right.

This code can be simplified further by using Option instead of Either. Option would allow us to place any exception into the some data constructor, the Unit we’re placing into Either becomes the none (we’re used to thinking of void as nothing in Java anyway). The only hassle comes if we want to treat the Option as an Either (say in the lefts call above), in that case we’d need to lift the Option into an Either.

Option<Throwable> option = ...
Either<Throwable, Unit> either = option.toEither(unit()).swap();

Option also allows use to pull each some out of a list of Options, in a similar way to how we pulled the lefts out of a list of Eithers.

List<Option<Throwable>> results = ...
List<Throwable> errors = somes(results);
Option<Throwable> overall = errors.isEmpty() ?
    Option.<Throwable>none() :
    some((Throwable) new AggregatingException(errors));

Given that we’ve now decoupled the lifecycle from the runner and we know have a better way of handling errors, here’s the pattern of the new runner code:

private SpecificationResult runLifecycle(final long startTime,
    final SpecificationLifecycle lifecycle, final SpecificationMethod specificationMethod) {
  ...
  List<Option<Throwable>> lifecycleStepErrors = nil();
  final Either<Throwable, ContextClass> createContextResult =
      lifecycle.createContext(specificationMethod.getContextClass());
  lifecycleStepErrors = lifecycleStepErrors.cons(createContextResult.left().toOption());
  if (createContextResult.isLeft()) {
    return fail(...);
  } else {
    final ContextClass contextClass = createContextResult.right().value();
    ...
    lifecycleStepErrors = lifecycleStepErrors.cons(contextValidationResult.left().toOption());
    if (contextValidationResult.isSome()) {
      return fail(...);
    } else {
      ...
      lifecycleStepErrors = lifecycleStepErrors.cons(...left().toOption());
      if (...isSome()) {
        return fail(...);
      } else {
        ...
        if (...isSome()) {
          return fail(...);
        } else {
          ...
          if (...isSome()) {
            return fail(...);
          } else {
            ...
            if (...isSome()) {
              return fail(...);
            } else {
              ...
              return determineResult(..., lifecycleStepErrors);
            }
          }
        }
      }
    }
  }
}

See the pattern there? Let’s see it in slow motion. Assume each of the lifecycle results is called a, b, c, etc.

if (a.isLeft()) {
  return fail()
} else {
  if (b.isLeft()) {
    return fail()
  } else {
    if (c.isLeft() {
    } else {
      ...
    }
  }
}

What we’re doing is binding through each lifecycle result, if we get an error, we fail fast, if we don’t, we execute the next step. There’s some other muck going on here too, we’re destructively updating the list of errors (lifecycleStepErrors), and the last few steps (run the specification, run after methods, verify mocks) are always executed, regardless of whether any fail. So how do we clean the code up? We anonymously bind through Either on the right, and sequence through the rest accumulating errors. What???

Here’s a simple example that contains eleven steps representative of running a specification. For the first eight (a through h), each step’s predecessor must succeed (i.e. we have at most one error). For the last three (i through k), we execute all of them regardless of whether they fail and accumulate the errors. We make use of the new Validation class in Functional Java (in version 2.9) to perform the last three steps (full source; this example has been further refined in the trunk).

class X {
  // The first sequence of steps...
  Either<Throwable, Unit> a;
  Either<Throwable, Unit> b;
  Either<Throwable, Unit> c;
  Either<Throwable, Unit> d;
  Either<Throwable, Unit> e;
  Either<Throwable, Unit> f;
  Either<Throwable, Unit> g;
  Either<Throwable, Unit> h;
  // The second sequence of steps...
  Either<Throwable, Unit> i;
  Either<Throwable, Unit> j;
  Either<Throwable, Unit> k;

  // Execute the first sequence of steps, fail on the first error.
  Either<Throwable, Unit> t1() {
    return a.left()
        .sequence(b).right()
        .sequence(c).right()
        .sequence(d).right()
        .sequence(e).right()
        .sequence(f).right()
        .sequence(g).right()
        .sequence(h);
  }

  // Execute the second sequence of steps, accumulate the errors.
  Option<NonEmptyList<Throwable>> t2() {
    return validation(t1()).nel().accumulate(
        Semigroup.<Throwable>nonEmptyListSemigroup(),
        Validation.<Throwable, Unit>validation(g).nel(),
        Validation.<Throwable, Unit>validation(h).nel(),
        Validation.<Throwable, Unit>validation(i).nel());
  }
}

Each of the fields in the above represents the result of executing a step in the specification lifecycle (including validation, which is beyond the SpecificationLifecycle itself), t1 represents the first eight steps, t2 the last three steps. t1 sequences through (anonymous bind) the result of each step, failing if any individual step fails. t2 executes [2] each step, continuing execution of the remaining steps if any step fails, and accumulates the errors.

Remember that this is what t1 looked like originally:

if (a.isLeft()) {
  return fail()
} else {
  if (b.isLeft()) {
    return fail()
  } else {
    if (c.isLeft() {
    } else {
      ...
    }
  }
}

Some simpler examples may make the binding clearer; consider Scala’s Option (used here for brevity). We can bind through Option using orElse:

scala> Some(7).orElse(Some(8))
res0: Option[Int] = Some(7)

Here we execute Some(7), if that fails (i.e. returns none), we execute Some(8). As we see, the result is Some(7). Let’s take a failure case:

scala> None.orElse(Some(8))
res1: Option[Int] = Some(8)

We execute None, if that fails (i.e. returns none), which it does, we execute Some(8). As we see, the result is Some(8).

Taking it back to our simple Java example, we evaluate the result of step a [2], if it fails, we return the failure, if it succeeds, we evaluate step b, and so on. This is the same logic we saw in the nested if-else blocks earlier. If any of the first eight steps fail, we get back either one error (from t1), if any of the last three steps fail, we get back at most 3 errors (from t2)

If we apply this pattern to our specification runner code, we get the following:

private SpecificationResult runLifecycle(final long startTime, final SpecificationLifecycle lifecycle,
    final SpecificationMethod specificationMethod) {
  final Either<Throwable, ContextClass> createContext = lifecycle.createContext(specificationMethod.getContextClass());
  if (createContext.isLeft()) {
    return fail(startTime, specificationMethod, createContext.left().value(), false);
  } else {
    final ContextClass contextClass = createContext.right().value();
    final Either<Throwable, Unit> validation = validateSpecification(contextClass, specificationMethod);
    if (validation.isLeft()) {
      return fail(startTime, specificationMethod, validation.left().value(), false);
    } else {
      return runSpecification(startTime, lifecycle, contextClass, specificationMethod);
    }
  }
}

That looks bit better, but where’s the complexity gone? OK, here it is…

private SpecificationResult runSpecification(final long startTime, final SpecificationLifecycle lifecycle, final ContextClass contextClass,
    final SpecificationMethod specificationMethod) {
  final Object contextInstance = constructorInvoker.invokeNullaryConstructor(contextClass.getType());
  final Validation<Throwable, Unit> preSpecificationSteps =
      validate(resetMocks().f(lifecycle)).sequence(validation(wireActors().f(lifecycle, contextInstance)))
          .sequence(validate(befores().f(lifecycle, contextInstance, contextClass.getBeforeSpecificationMethods())));
  if (preSpecificationSteps.isFail()) {
    return fail(startTime, specificationMethod, preSpecificationSteps.fail(), Option.<Throwable>none());
  } else {
    final Option<Throwable> specification = specification().f(lifecycle, contextInstance, specificationMethod);
    final Option<NonEmptyList<Throwable>> result = preSpecificationSteps.nel().accumulate(throwables(), validate(specification).nel(),
        validate(afters().f(lifecycle, contextInstance, contextClass.getAfterSpecificationMethods())).nel(),
        validate(verifyMocks().f(lifecycle)).nel());
    if (result.isSome()) {
      return fail(startTime, specificationMethod, result.some().toList(), specification);
    } else {
      return success(startTime, specificationMethod);
    }
  }
}

Here’s the complete old and new versions of the code if you’re so inclined…

This code combined with the extracted lifecycle class is functionally equivalent to the first snippet of code I presented above. It may look verbose (it would be much simpler in Scala for example), but an interesting thing came out of it; it made explicit a bunch of places where I wasn’t handling exceptions correctly. It forced me to make a decision as to what to do in each case, so I got a much finer grained exception handling mechanism. Of course, I could get the same using try-catch (arguably more verbose), and I can choose to ignore left results (errors) if I want. The other thing it highlights is Java’s woeful generics implementation [3].

When I started down this path to error handling I had two objectives (two reported issues to resolve); to allow the runner of a specification to know which parts failed (this gives the flexibility to allow before specs to error and not be reported as expected exceptions) and to return all the errors resulting from running a specification. I didn’t initially intend to go down this path, however after talking in the office, decided that there was a better way to handle this than nested try-catch blocks. The resulting code is smaller (even using Java), simpler and much more flexible than the traditional Java method of exception handling. A win all round. There are some downsides however, firstly, the verbosity of Java’s typing leads to a mess of Either<Throwable, Unit> and this method of error handling will be foreign to a lot of Java developers today.

Epilogue

The concept of sequencing while accumulating errors has been generalised in Functional Java (from version 2.9) as validation, here is an example of it in action. Scalaz contains a similar concept, though this uses applicative functors over higher kinds (something which Java’s type system does not support), here’s a small example of its use.

Footnotes

  1. There’s no reason why you couldn’t catch an exception and wrap it up in a list, or your own data structure instead of using Either, but most of the work is already done for us (i.e. useful functions across Either have been defined) and it’s a useful convention.
  2. Java is strict, so we don’t get the benefit of lazy evaluation in this case, but could emulate it with a function.
  3. The problems I’ve encountered mainly have to do with covariance in type parameters and differences between the way methods returning types are treated vs. local variables (see the bottom of StandardSpecificationLifecycle for details).

Written by Tom Adams

August 6th, 2008 at 2:27 pm