+++ Release 1.0.4 is staging ... expect the newest release at Maven Central within the next hours as soon as Sonatype has done its job (10 Feb 2012 4 pm) +++

This library catches exceptions in a single line of code and makes them available for further analysis.

Usage

The most basic usage is:

import static com.googlecode.catchexception.CatchException.*;

// given: an empty list
List myList = new ArrayList();

// when: we try to get the first element of the list
// then: catch the exception if any is thrown 
catchException(myList).get(1);

// then: we expect an IndexOutOfBoundsException
assert caughtException() instanceof IndexOutOfBoundsException;

The last both lines of code can be combined in a single line of code if you like:

verifyException(myList, IndexOutOfBoundsException.class).get(1);

More information about the usage you find in the Javadoc documentation.

BDD-like

If you prefer a BDD-like approach, you can use another code style:

import static com.googlecode.catchexception.CatchException.*;
import static com.googlecode.catchexception.apis.CatchExceptionBdd.*;

// given: an empty list
List myList = new ArrayList();

// when: we try to get the first element of the list
when(myList).get(1);

// then: we expect an IndexOutOfBoundsException
then(caughtException())
        .isInstanceOf(IndexOutOfBoundsException.class)
        .hasMessage("Index: 1, Size: 0") 
        .hasNoCause();

The assertions used here are part of FEST. An example how FEST verifies exceptions can be found here.

Hamcrest

If you prefer Hamcrest matchers to express assertions, you can use the following code style:

import static com.googlecode.catchexception.CatchException.*;
import static com.googlecode.catchexception.apis.CatchExceptionHamcrestMatchers.*;

// given: an empty list
List myList = new ArrayList();

// when: we try to get the first element of the list
catchException(myList).get(1);

// then: we expect an IndexOutOfBoundsException with message "Index: 1, Size: 0" 
assertThat(caughtException(),
  allOf(
    is(IndexOutOfBoundsException.class), 
    hasMessage("Index: 1, Size: 0"),
    hasNoCause()
  )
);

Download

Go to the Installation page to get the latest release. This page provides also the Maven coordinates, prerequisites, and information about dependencies to other libraries.

Future enhancements

Nothing to do at the moment. There are no open issues and no open feature requests (last update: 10 Feb 2012).

Credits

Thanks to Szczepan Faber who made some suggestions about a BDD-like syntax for catch-exception. Finally, his ideas triggered the enhancements that came with the 1.0.4 release.

Questions, Suggestions, Issues

Questions and suggestions are welcome and can be sent to the discussion group. Issues can be reported on the Issues page of this project.

Please give me feedback of any kind. It is highly appreciated.