Reconnect Rules

You can understand about type of rules, part of rules, part of error situation and nested exceptions through the information provided here.

The Reconnect Rule Engine makes decisions based on configured rules. Each rule describes what should be done when a given kind of error situation ensues. The engine uses two types of rules:

• Built-in rules, which are stored in the tdi.xml files of each connector file and are packaged in the connector's jar file; as a result these rules are always specific to the particular connector class and match all connector names; this list of rules is the default list of the Reconnect Rule Engine when working on an error situation for a given Connector; if you have programmed your own Connectors in Java, then for information about how to construct your own built-in rules see section "Connector Reconnect Rules definition" in the "Implementing your own Components in Java" appendix under the Reference section of IBM Knowledge Center for IBM® Security Verify Directory Integrator.
• For compatibility with previous releases of IBM® Security Verify Directory Integrator, when the Reconnect Rule Engine is set up it implicitly adds to the built-in rules, a set of rules that prescribe to attempt reconnect on all IOException-s and all CommunicationException-s (java.io.IOException and javax.naming.CommunicationException);
• User-defined rules, which are loaded from an external text file named etc/reconnect.rules; this list of rules overrides the built-in rules. See User-defined rules configuration.

Each rule applies to certain connectors and certain error situations.

A rule has the following parts:

• Connector Class: the Java Class of the connectors to which the rule applies
• Connector Name: the name of the connector component as it is specified in the configuration file of the currently executed solution
• Exception Class: the base class of the exceptions to which the rule applies
• Regular Expression: a regular expression that matches the messages of the exceptions to which the rule applies
• Action: the action, prescribed by the rule. Can be error or reconnect.

An error situation is described by the following parts:

• Connector Class: the class of the connector that raised the exception
• Connector Name: the name of the connector that raised the exception
• Exception: the exception raised by the connector - a subclass of java.lang.Throwable.

A rule applies to an error situation if all of the following conditions are fulfilled at the same time:

• the rule applies to the connector in the error situation (subclasses of the connector class, described in the rule are also matched)
• the rule applies to the name of the connector which caused the error situation
• the exception is an instance of the exception class, to which the rule applies
• the rule does not have a regular expression to match the exception message or the regular expression matches the message of the exception.

When a given error situation occurs, the reconnect rule engine finds the most specific rule that matches the error situation. First the engine searches through the user-defined rules and if no matching rule is found, it searches the built-in rules. If still no matching rule is found, the engine prescribes the default action, which is "error". If a matching rule is found in the user-defined rules, then the built-in rules are not searched, even if there exists a more specific rule in the built-in rules.

Note: If two or more rules match an error situation, the most specific rule is selected; if there are several most-specific rules and none of them is more specific than the rest, then the first rule in the list is selected. That is why the order of the rules in the rule lists matters. For example: suppose the following rules exist (this is pseudo-syntax used for clarity only):

...exceptionClass = "java.io.IOException", exceptionMessageRegExp = ".*", action = "error"...
...exceptionClass = "java.io.IOException", exceptionMessageRegExp = "\w*", action = "reconnect"...

If an exception of type java.io.Exception with message "problem" is raised, then the first rule is selected, although both rules match the error and no rule is more specific than the other (the outcome of the regular expression match is not considered for weighting purposes.)

Nested Exceptions

Some exceptions are nested inside other exceptions. When the reconnect rule engine searches through a list of rules (for example the built-in rules), the engine searches for a rule that matches the top-level exception first. If no matching rule is found, then the engine searches again the same list of rules but this time it searches for a match for the nested exception (if the top-level exception has no nested exception this search is skipped). Note that only the first-level nested exception is attempted to be matched by the reconnect rule engine; if there are more levels of nested exceptions they are ignored.

Note: Automatic Failover is not possible for Server mode Connectors.