IBM Tivoli Directory Integrator
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 we 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. We 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.
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
TDI'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
TDI'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:
Every environment and solution created for a particular environment
using TDI 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 TDI Java API documentation for information
about specific exceptions that are returned by the TDI APIs for each
Connector.
Additionally, some TDI 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 we can look for additional
information on exceptions and what may be the cause of the exceptions.
This information is helpful when deciding if we 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 TDI V7.1 Reference Guide contains links to the JDBC Driver documentation
for a set of commonly used JDBC drivers.