Random bits of information by a developer

28 January 2011

Seam Catch Beta 1

Seam Catch Beta1 was released last night! I know it's been a while since I've said anything about Catch and there's been one release between now and the last blog entry, sorry for that. This release is what was scheduled for Alpha4 but we decided to call it a beta and get it setup for inclusion into the Seam 3 bundle beta scheduled shortly. This release is mostly concerned with API changes (the API should now be frozen unless there are bugs found, please see JIRA for more detailed info), but there are couple of features and tweaks that I'd like to highlight:

  • Better alignment with @Observers
  • Modification of execution of handlers
  • Special considerations for SQLExceptions

Better alignment with @Observers

Exception Handlers are becoming more closely aligned with @Observers, while still retaining the enhancements necessary to support this application; with this release the @Handles annotation can be placed on any parameter of the method! Best practice should still be to place the annotation on the first parameter as it reads a little better, but the following code sample will work just fine:

public void trickyParamHandler(@CatchResource SomeCatchResource catchResource, @Handles CaughtException<Throwable> e, SomeOtherResource resource) {
    catchResource.performActionForException(e);
    resource.someAction();
}

The other two parameters are injection points and will be looked up using the BeanManager. This follows the CDI spec according to section 10.4.

Modification of execution of handlers

See SEAMCATCH-31 and SEAMCATCH-32 are extra detail on this change. In short, there has been some confusion about when exception handlers are executed. If your handlers rely on other handlers in the chain being executed in a particular order this very likely is a breaking change. The exception stack is still unraveled and handlers are run against the actual root cause first and Catch moves up the stack from there. The major change is how the type hierarchy for a given exception is used (also note there was an API change here). The way it works now is that any handlers that handle super types of the exception and are marked as TraversalMode.BREADTH_FIRST will be invoked first, followed by handlers marked with TraversalMode.DEPTH_FIRST starting with the actual type of the exception and working up the type hierarchy. This happens for each exception in the stack, however, a handler will still only be invoked once, unless it calls unmute().

Special considerations for SQLException

For anyone that's ever looked at a stack trace that includes a SQLException and been frustrated at not actually seeing the error from the database, SEAMCATCH-37 is for you. When unwrapping an exception stack, Catch will also unwrap any underlying SQLException instances using the getNextException() method and add that to the stack. Now you can finally see what your database is trying to tell you without having to debug or add your own catch block!

Going forward

Core Catch concepts should now be frozen as far as the API goes. We may add additional functions such as filtering a stack trace or other subsidiary features, but they should not affect the core API as it currently exists in this release. If you have a feature request, please add a JIRA ticket. Happy coding!

No comments: