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 either be ignored or rethrown.

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 an 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 (see Exception handling in rules).

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.

Procedure

Implement the CustomExceptionHandler interface in the XOM (see CustomExceptionHandler). 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;
    }
  }
}

Open Rule Designer.
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.
Click OK.

Results

The custom exception handler is created when the engine starts, and removed when the engine is reset.