Using a stale connection checker in JBoss EAP

Environment

• Red Hat JBoss Enterprise Application Platform (EAP)
  • 6
  • 7
• All Databases

Issue

• What is the purpose of the stale connection checker?
• How does the stale connection checker relate to fault tolerance?
• How is a stale connection checker specified?

Resolution

• NOTE A stale connection checker is only relevant if the application is explicitly coded to handle org.jboss.jca.adapters.jdbc.StaleConnectionException.
  • If the application is not coded to handle StaleConnectionException, a stale connection checker class should not be specified.
• The fault tolerance mechanism does not require a stale connection checker
  • Stale connection checking is only used to raise errors to application code in a standard way allowing application code to recognize stale connection state issues in case application specific logic is required (often this is not necessary - since the standard approach to many types of failed "requests" is simply to retry the failing operation).
• Stale connection checker classes implement org.jboss.jca.adapters.jdbc.spi.StaleConnectionChecker to identify stale connection state exceptions¹
  • Implementations of StaleConnectionChecker inspect datasource-type specific error codes, etc. in SQLException to determine if they represent stale connection state errors
  • Where stale state exceptions are identified, JBoss wraps the underlying SQLException in org.jboss.jca.adapters.jdbc.StaleConnectionException before raising the exception to application code
• A stale connection checker class may be specified within the <validation> configuration for a datasource using

                    <validation>
                        ...
                        <stale-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker"/>
                        ...
                    </validation>

• See <JBOSS_HOME>/docs/schema/jboss-as-datasources_1_*.xsd

Note

• org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker tests for:
  • ORA-01014
  • ORA-01033
  • ORA-01034
• JBoss EAP ships with the following which return false for all SQLException errors:
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
• Developers may choose to implement a custom stale connection checker class unique to their chosen datasource by implementing the StaleConnectionChecker class and registering the custom classs

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.