User-defined rules configuration

Directory Integrator, Version 7.1.1

User-defined rules configuration

The list of user-defined rules is configured in a text file named reconnect.rules in the "etc" subfolder of the TDI solution folder (or the TDI installation folder, if no solution folder has been defined). Each rule is placed on a single line. The format of a rule is as follows:

<connector_class>:<connector_name>:<exception_class>:<action>:<regular_expression>

where

<connector_class> is the fully qualified name of the Java class of the Connector
<connector_name> is the name of the Connector as inserted in the AssemblyLine
<exception_class> is the fully qualified name of the Java class of the exception
<action> can be either 'error' or 'reconnect'
<regular_expression> is a Java regular expression as described in the JavaDoc of the java.util.regex.Pattern class at http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html.

Notes:

Each part except the action can be empty. If a part is empty that means "match-all".
Each part is mandatory - even if it is empty the surrounding colons must be present. (Consequently on each line there must be at least 4 colons - each colon separating two adjacent parts of the rule. At least 4, because the regular expression may contain colons too. These colons do not interfere with the rule parsing because the regular expression comes last in a rule.)
No redundant white space is allowed.
The regular expression starts just after the fourth colon and spans until the end of the line.
The user-defined rules file is not a Java properties file. The main reason is that a key for a rule must include all rule parts, except the reconnect action, in order to be unique. So the only value from using the Java properties mechanism would be the separation of the action from the other rule parts. However, it would come at the price of escaping white-spaces, colons and equal signs (requirements for a valid property key). Even if the Java property framework was used, custom parsing of the property key would still be required in order to extract the rule parts from it.
The regular expression (not the reconnect action) comes last on each line. This pattern is chosen such that it is unneccesary to escape colons (which are considered rule part delimiters) in the regular expression.
The regular expression must match the entire message text: Suppose the message text you want to match contains the words "Some Error" somewhere in the message text. A suitable regular expression might then be:
```
	.*Some Error.*
```
The character "." matches any character except new line, and the * modifier specifies 0 or more. Now suppose the message ends with a new line. If that is the case, the previous regular expression does not match. You can try a regular expression like this instead:
```
	.*Some Error.*\r?\n?
```
"\r" and "\n" specify return and new line characters, and the ? modifier specifies 0 or 1 occurrence.
You must still configure reconnect in the Connector's configuration; see General reconnect configuration.

Examples

An example, consisting of two rules:

com.ibm.di.connector.ReconnectTestConnector:myconnname:java.io.IOException:error:.*\Wfatal\W.*
::java.io.IOException:reconnect:

Reconnect with the JDBC Connector

Tivoli® Directory Integrator's JDBC connector is configured in Iterator mode to iterate a table from DB2 and is enabled for the reconnect feature. However, at the time of running the solution, DB2 instance is not started yet. In order to have reconnect working, the following exception details need to be mentioned in the reconnect.rules file:

com.ibm.di.connector.JDBCConnector::com.ibm.db2.jdbc.DB2Exception:reconnect:

Reconnect with the RAC Connector

Tivoli Directory Integrator's RAC connector is configured in Iterator mode and is enabled for the reconnect feature. In case the Agent Controller server is down, in order for the RAC connector to try to reattempt (reconnect), the following exception details need to be mentioned in the reconnect.rules file:

com.ibm.di.connector.RACConnector::org.eclipse.tptp.platform.execution.exceptions.AgentControllerUnavailableException:reconnect:

Exception considerations

Every environment and solution created for a particular environment using Tivoli Directory Integrator is typically unique. User-defined rules are custom-built and the functionality is made available so solutions can automatically attempt to reconnect based on the exceptions specific to the environment or solution. Refer to the Tivoli Directory Integrator Java API documentation for information about specific exceptions that are returned by the Tivoli Directory Integrator APIs for each Connector.

Additionally, some Tivoli Directory Integrator components rely on underlying libraries and the APIs of these libraries throw exceptions for specific situations. Below we list a few core TDI components where you can look for additional information on exceptions and what may be the cause of the exceptions. This information is helpful when deciding if you want to attempt to create custom reconnect rules for specific exceptions that may be encountered:

LDAP Connector - The LDAP Connector depends on the JNDI libraries shipped with the JRE. For more information on the JNDI interface, its APIs, and the exceptions it may throw, see http://java.sun.com/j2se/1.5.0/docs/api/javax/naming/package-summary.html.
JDBC Connector - The JDBC Connector depends on the configured JDBC Driver. The Java API documentation or reference material for the configured JDBC driver should be consulted for more information on the possible exceptions that may be thrown. The "Understanding JDBC Drivers" subsection in the JDBC Connector chapter in IBM Tivoli Directory Integrator V7.1.1 Reference Guide contains links to the JDBC Driver documentation for a set of commonly used JDBC drivers.

IBM Tivoli Directory Integrator 7.1.1