Demystifying the WebSphere StaleConnectionException

Technote (FAQ)
Problem
What is the StaleConnectionException, why is it issued by WebSphere® Application Server, and what should be done about it?
Solution
In WebSphere Application Server 3.5.2 and all subsequent releases, including V4 and V5, the StaleConnectionException is issued when the database vendor issues an exception indicating that a connection currently in the connection pool is no longer valid. This can happen for many reasons, including:
  • The application tries to get a connection and fails, as when the database is not started.

  • A connection is no longer usable due to a database failure. When an application tries to use a connection it has previously obtained, the connection is no longer valid. In this case, all connections currently in use by an application can get this error when they try to use the connection.

  • The application using the connection has already called close() and then tries to use the connection again.

  • In WebSphere V3.5 or V4, the connection has been orphaned because the application had not used it in at most two times the orphan timeout; then the application tries to use the orphaned connection.

  • The application tries to use a JDBC resource, such as a statement, obtained on a now-stale connection.

When the StaleConnectionException is issued, WebSphere V3.5 and V4 flushes the entire connection pool and establishes a fresh pool of connections initialized to the Minimum Connection Pool Size. The behavior in WebSphere V5 is determined by the Purge Policy setting for the connection pool. If the Purge Policy is set to EntirePool, the entire pool is flushed, as in the earlier versions. But if the Purge Policy is set to FailingConnectionOnly, only the connection that caused the StaleConnectionException is purged from the pool.

An application can recover from bad connections by explicitly catching the StaleConnectionException and getting a new connection from the pool. Numerous exceptions issued by DB2®, Oracle®, DataDirect® (for connecting to SQLServer), Sybase®, and Informix® are currently mapped to the StaleConnectionException, which makes recovery easier for the application programmer. The following pseudocode provides an example of how to recover from a StaleConnectionException:

try
{
boolean retry = true;
while( retry)
{
try
{
Connection conn1 = ds1.getConnection();
Statement stmt1 = conn1.createStatement();
ResultSet res = stmt1.executeQuery(stmtString);
.......
// If all the database work was successful.
retry = false;
.......
}
catch (StaleConnectionException ex)
{
// counter to retry a limited number of times?
retry = true;
// wait?
}
catch (SQLException sqle)
{
.....
} // end try-catch
finally
{
// close result sets
// close statements
// close connection
}
} // end while
}
catch( Exception ex)
{
....
} // end try-catch
....

In addition, a StaleConnectionException might also be issued when connecting to the administrative repository database in WebSphere V3.5 or V4. Again, the connection pool is flushed when the exception is issued. A second attempt to access the repository, such as running the administrative console or WSCP, should be successful.

Further details about WebSphere connection pooling and the StaleConnectionException is located in the "WebSphere Connection Pooling" white paper, available for download at the WebSphere Application Server support Web site:
http://www-306.ibm.com/software/webservers/appserv/whitepapers/connection_pool.pdf












Document Information

Product categories: Software, Application Servers, Distributed Application & Web Servers, WebSphere Application Server, DB Connections/Connection Pooling
Operating system(s): Multi-Platform
Software version: 3.5, 4.0, 5.0
Software edition: Edition Independent
Reference #: 1063645
IBM Group: Software Group
Modified date: 2004-08-09