Test connection service

WebSphere Application Server provides a test connection service for testing connections to the data sources that you configure for database access.

Verifying your scope settings

Use of a WebSphere variable in your data source definition can elicit test connection results that are incongruent with the actual run-time behavior of your data access application. In some cases, a test connection operation fails, but the data source functions normally during application run time. The reverse scenario can also occur. The cause of the potential conflict is the difference between how your application server handles WebSphere variable scope settings at run time, and how it handles those scope settings for a test connection operation. Understanding the difference helps you choose a successful configuration for your data source.

At run time, an application server resolves environment variables from the most specific scope to the broadest scope. That is, the server checks for the resolution of a variable in the server scope, then the cluster scope, then the node scope, and lastly the cell scope. When testing a connection, however, the most specific scope level at which the server checks variable definitions is determined by the scope at which the data source was created.

The test connection operation itself is performed in the JVM that corresponds with the scope of the data source. If the data source is configured at the cell scope, the test connection operation is carried out in the deployment manager process. If the data source is configured in the node scope, the test connection operation is performed in the node agent process for that node. For cluster-scoped data sources, the test connection operation is attempted in the node agent for each node that contains a cluster member. For server-scoped data sources, the test connection operation is first attempted in the server. If the server is unavailable, the test connection operation is retried in the node agent for the node that contains the application server.

Note: For any data source, regardless of scope setting, restart the associated JVM if you add or modify the authentication alias object.

Processing data source configurations in this way yields different, sometimes misleading, test connection results for different scope settings, as shown in the following table:

Data source scope	Cell level variables	Node level variables	Server level variables
Cell level	Ok^* (See the following section)	Fail	Fail
Node level	Ok	Ok	Fail
Server level	Ok	Ok	Ok

One of the scope combinations listed in the table, however, produces the reverse scenario: the test connection operation succeeds, but the data source fails at run time. This anomaly occurs in the case of a cell-scoped data source that uses a cell-scoped WebSphere variable. At run time, the cell-scoped variable is preempted by a default scope setting. In a default WAS installation, the supported database driver variables are defined and initialized to an empty string at the node scope. That empty setting effectively overrides any variable definition you provide at the cell scope level for a cell-scoped data source.

Because the run-time server checks the node scope for the variable before it checks the cell scope, it reads the empty string variable and accepts it as a value for the database driver class path. The incorrect class path elicits a classNotFound exception when the server attempts to use the data source. To make the data source work for both test connection and run time, define the driver class path variable at the cell scope (indicating the location of the driver files on the deployment manager node), as well as at each node on which the data source must function. Alternatively, one can delete the node scope definitions if the database location is the same as the cell-scoped variable.

We can bypass the environment variable lookups by changing the class path entries for the JDBC provider to hard-coded values. However, this strategy succeeds only if the class path is the same on all nodes where the data source must function.

Activating the test connection service

There are three ways to activate the test connection service: through the administrative console, the wsadmin tool, or a Java stand-alone program. Each process invokes the same methods on the same MBean.

Administrative console

WebSphere Application Server allows you to test a connection from the administrative console by simply pushing a button: the Data source collection, Data source settings, V4 data source collection, and Version 4 data source settings pages all have Test Connection buttons. After you define and save a data source, one can click this button to ensure that the parameters in the data source definition are correct. On the collection page, one can select several data sources and test them all at once. Note that there are certain conditions that must be met first. For more information, see Testing a connection with the administrative console.

WsAdmin tool

The wsadmin tool provides a scripting interface to a full range of WebSphere Application Server administration activities. Because the Test Connection functionality is implemented as a method on an MBean, and wsadmin can invoke MBean methods, wsadmin can be utilized to test connections to data sources. You have two options for testing a data source connection through wsadmin:

The AdminControl object of wsadmin has a testConnection operation that tests the configuration properties of a data source object. For information, see Testing a connection using wsadmin.

We can also test a connection by invoking the MBean operation. Use Example: Testing data source connection using wsadmin as a guide for this technique.

Java stand-alone program

Finally, one can test a connection by executing the testConnection() method on the DataSourceCfgHelper MBean. This method allows you to pass the configuration ID of the configured data source. The Java program connects to a running Java Management Extensions (JMX) server to access the MBean. In a Network Deployment installation of Application Server, you connect to the JMX server running in the deployment manager, usually running on port 8879.

The return value from this invocation is either 0, a positive number, or an exception. 0 indicates that the operation completed successfully, with no warnings. A positive number indicates that the operation completed successfully, with the number of warnings. An exception indicates that the test of the connection failed.

We can find an example of this code in Example: Test a connection using testConnection(ConfigID).

Related Tasks

Configuring WebSphere variables