Setting a custom exception handler

You can set an exception handler to customize exception handling in rule conditions and actions. When you implement the CustomExceptionHandler API, exceptions can be either ignored or rethrown. To handle exceptions that occur in the ruleflow specific elements, set a custom ruleflow exception handler.

About this task

The default engine behavior is to stop when an exception is thrown. With the CustomExceptionHandler API, you can customize the processing of the exception to, for example, catch the exception or rethrow it, perform filtering on exception types, or log information.

You can set a custom exception handler subclass of CustomExceptionHandler to customize exception handling for the condition and action parts of rules by using the dedicated methods handleConditionException and handleActionException:

handleConditionException
An exception in the condition part of a rule triggers the handleConditionException method. When the method is called, the condition is unresolved, and the action part of the rule is not executed. If the method rethrows the exception, the engine stops, which is the default behavior. If the method catches the exception and does not rethrow an exception, the condition remains unresolved. However, the engine continues processing other rules if any. If automatic exception handling is activated and the condition can be resolved, the handleConditionException method is not called.
handleActionException
An exception in the action part of a rule always triggers the handleActionException method, and the execution of the action stops. If the method rethrows the exception, the engine stops, which is the default behavior. If the method catches the exception and does not rethrow an exception, the current action is not terminated but is considered executed. Then, the engine continues processing other rules if any.

If you also need to handle exceptions that occur in ruleflow specific elements such as action task bodies, transition conditions, and initial and final action bodies, you implement the CustomRuleflowExceptionHandler API and use the method handleRuleflowException. The method is called when an exception occurs in any part of the ruleflow or a rule part in which an exception was not caught before. The call to the method does not change the flow of execution for rules. Whether the exception is caught or rethrown in the method, the execution stops where the exception occurs.

Note: The custom exception handler does not have direct access to the engine, and it cannot be accessed from the engine. Therefore, it cannot reference parameters or other information found in the engine.

For compatibility with the classic rule engine, see How to store exceptions in a parameter using the decision engine custom exception handler.

Procedure

  1. Implement the CustomExceptionHandler or CustomRuleflowExceptionHandler interface in the XOM.
  2. Open Rule Designer.
  3. In the Rule Engine panel of the rule project properties window, enter the custom exception handler name. For example, enter com.acme.MyCustomExceptionHandler in the Custom exception handler field.
  4. Click OK.

Example

In the following example, the custom exception handler rethrows exceptions for NumberFormatException:

package com.acme;
import ...

public class MyCustomExceptionHandler implements CustomExceptionHandler {

  static Logger logger = Logger.getLogger(MyCustomExceptionHandler.class.getName());

  /**
   * The custom exception handler must contain a default constructor.
   */
  public MyCustomExceptionHandler() {
  }

  @Override
  public void handleConditionException(Exception e) throws Exception {
    if (e instanceof NumberFormatException) {
      // ignore number format exception
    } else {
      // rethrow the exception, it will stop the engine execution
      throw e;
    }
  }

  @Override
  public void handleActionException(Exception e, RuleInstance ruleInstance) throws Exception {
    if (e instanceof NumberFormatException) {
      // ignore number format exception and log
      if (logger.isLoggable(Level.INFO)) {
        logger.log(Level.INFO,
            "Exception while executing action of rule " + ruleInstance.getRuleName(), e);
      }
    } else {
      // rethrow the exception, it will stop the engine execution
      throw e;
    }
  }
}

In the following example, the custom ruleflow exception handler logs ruleflow exceptions:

package com.acme;
import ...
public class MyCustomRuleflowExceptionHandler implements CustomRuleflowExceptionHandler
{
  static Logger logger = Logger.getLogger(MyCustomRuleflowExceptionHandler.class.getName());
  /**
  * The custom ruleflow exception handler must contain a default constructor.
  */

  public MyCustomRuleflowExceptionHandler() {
  }

  @Override
  public void handleRuleflowException(Exception e) throws Exception {
     if (logger.isLoggable(Level.INFO)) {
        logger.log(Level.INFO, "Exception in Ruleflow: " +  e.getMessage());
     }
  }

  @Override
  public void handleConditionException(Exception e) throws Exception {
    // your implementation
  }

  @Override
  public void handleActionException(Exception e, RuleInstance ruleInstance) throws Exception {
    // your implementation
  }

}