Exception Configurations

An exception handler is defined using the <exception-handler> element. It may appear either inside the <exception-handlers> element to define a global exception handler or inside an <action> element to define a local exception handler.

The <exception-handler> element takes a mandatory class attribute, giving the name of the exception handler class, which has to implement the ExceptionHandler interface. The optional type attribute specifies the name of the exception type, that will be treated by the handler. If omitted, a java.lang.Exception will be assumed.

The <exception-handler> element may contain any number of <param> and <dispatch> elements.

An exception configuration is reflected by the ExceptionHandlerConfig interface, which defines the getParamConfig() method to lookup parameters by name.

Exception handlers are instantiated and initialized when the module gets loaded, one for each configuration. If an action invocation throws an exception, the module catches it and searches for an exception handler configuration as follows: for each class cls on the inheritance path from the exception's class up to java.lang.Exception, it first checks for a local, then for or global exception configuration whose type attribute matches the current class cls. If it finds one, it gets the corresponding ExceptionHandler instance and invokes its handle() method. Otherwise, the exception is wrapped into a ServletException and thrown again.

Examples

The following examples show some exception handler configurations. Whether a handler is selected for a concrete exception, is determined by the module's selection algorithm as explained above and also depends on whether it is defined as a local or global exception handler.

Using the simple exception handler

Calyxo Control supplies a simple exception handler implementation. This generic exception handler requires the parameters bundle and key to identify a message template. It will create and save a message object into the current request, passing the exception message as an argument. Finally, it looks up and returns a dispatch configuration in the action identified by the target parameter. 

<exception-handler
  class="de.odysseus.calyxo.control.misc.SimpleExceptionHandler">
  <param name="bundle" value="messages"/>
  <param name="key" value="exception"/>
  <dispatch path="/WEB-INF/jsp/exception.jsp"/>
</exception-handler>

The dispatch configuration may be either specified directly by a nested anonymous dispatch configuration (as above) or by the target parameter referencing a dispatch configuration visible to the action configuration, that is passed to the handle() method. 

<exception-handler
  class="de.odysseus.calyxo.control.misc.SimpleExceptionHandler">
  ...
  <param name="target" value="failure"/>
</exception-handler>

configures an exception handler to handle any type of exception.

Using a custom exception handler

The ExceptionHandler interface contains the methods init(...) and handle(...). Assume, you implemented an exception handler in org.foo.BarExceptionHandler. 

<exception-handler type="java.sql.SQLException"
  class="org.foo.BarExceptionHandler">
  <dispatch path="/WEB-INF/jsp/exception.jsp"/>
</exception-handler>

configures your exception handler to handle SQL exceptions.