I'm a little confused about the subject of throwing exceptions from JBPM work item handlers and handling the exception elsewhere in the business process. We're using JBPM 6.0.3 to run in Jboss EAP 6.1.
The JBPM User Guide implies that you should never throw exceptions from within a WorkItemHandler. Instead, the handler should catch them and either handle them some way or else convert them to an error message, signal, or similar. JBPM even provides work item handler wrappers which catch signals and converts them to messages for you. There's no discussion in the user guide about handling exceptions any other way.
Then we have the jbpm-workitems package, which contains quite a few handlers that are specifically coded to throw exceptions. Anything in that package which inherits from AbstractLogOrThrowWorkItemHandler can throw a WorkItemHandlerRuntimeException, for example. Maybe these handlers are only supposed to be used by wrapping them, but that seems like an odd design choice.
I've also found this third-party documentation page for something called Magnolia, which shows a different technique. You define an error message type where the error code value is the fully-qualified name of an exception class. Then you attach an error boundary event to the activity that calls the handler. If the handler throws that exception, it'll be caught by the error event. I've tested this method and it works fine; it even captures the exception object into a process variable.
I'm confused because the method shown on the Magnolia page is completely different from the method in the JBPM user guide, and there is nothing in the JBPM guide which even hints that the Magnolia method will work. The Magnolia method seems to be easier to use, but I'm concerned that it might not be supported.
What is the best-practice way to handle exceptions thrown by work item handlers? Is the Magnolia method something that's deprecated, or that works only by accident? Or is it something that I can count on continuing to work?
Edit: What prompted this question is that our team wanted to use the RESTWorkItemHandler from jbpm-workitems. This handler will throw exceptions in certain very ordinary circumstances. The JBPM documentation basically says not to let your work item handlers throw exceptions; catch them within the handler, or wrap the handler in a decorator that catches exceptions. That would make handlers like the REST handler finicky to construct and register properly. And I thought it strange that JBPM would maintain a bunch of standard work item handlers that couldn't be used without wrapping them in another handler.
Then I found the method described in the Magnolia documentation, which avoids having to wrap the handler in a decorator. But the method in the Magnolia documentation isn't described in the JBPM documentation.
