Test connection service

The Application Server provides a test connection service for validating data source configurations. The testConnection operation instantiates the data source configuration, gets a connection, and then immediately closes the connection.

If the definition of your data source includes a WebSphere variable, you need to determine how your scope settings for both the variable and data source can affect the test connection results. Your next step is to choose which of the three ways you want to activate the test connection service: through the administrative console, the wsadmin tool, or a Java stand-alone program.

Verifying your scope settings

Associating WebSphere variables with your data source configurations can elicit test connection results that are incongruent with the run-time behavior of your application. In some cases, a test connection operation fails, but the physical data source functions normally during application runtime. The reverse scenario can also occur. The cause of the potential conflict is the difference between how your application server handles the scope settings of WebSphere variables at runtime, and how it handles those same scope settings for a test connection operation. Understanding the difference helps you create successful data source configurations.

WebSphere Application Server invokes a physical data source by resolving the appropriate variable at a scope where one of the following criteria exists:
  • The scope of the variable can contain the data source configuration; that is, the variable has the larger scope.
  • The variable and the data source have identical scopes.
Application Server meets these conditions by attempting to resolve the variable at each level of the scope spectrum. That is, the product tries to resolve the variable in the server scope, then the cluster scope, then the node scope, and lastly the cell scope.
However, Application Server tests connections at one scope only; it performs the test operation in the JVM of the same scope as that of the data source configuration. The product attempts to resolve the driver class path variable at that scope only.
Table 1. Correlation of data source scope with the test connection JVM
Data source scope JVM where the test connection operation occurs
Cell Deployment manager process
Node Node agent process (of the relevant node)
Cluster Node agent for each node that contains a cluster member
Server Server; if the server is unavailable, the test connection operation is retried in the node agent for the node that contains the application server.
If the scope of the WebSphere variable is smaller than that of the data source, the test connection operation fails. The following table shows the scenarios that produce this failure, as well as those that produce success.
Table 2. Test connection results for different data source and variable combinations
Data source scope Cell level variables Node level variables Server level variables
Cell level Ok

*(See the following section: Test connection success, but run-time failure)

Fail Fail
Node level Ok Ok Fail
Server level Ok Ok Ok

Contrary to expectations, these test connection failures generally do not translate into failures at run time. Ensure that the location of your JDBC driver files is accessible to every client that must use the data source, and configure your WebSphere variable with the full path of that location.

Test connection success, but run-time failure

However, one of the scope combinations listed in Table 2 can produce the reverse scenario: the test connection operation succeeds, but the data source fails at runtime. This anomaly occurs in the case of a cell-scoped data source that uses a cell-scoped WebSphere variable. The connection test is successful because the operation takes place in the deployment manager process (as indicated in Table 1), where Application Server can resolve the cell-scoped variable. That data source can fail at run time, because the cell-scoped variable might be overridden by a variable that is automatically defined at the node scope with a null value.

In most implementations of Application Server, the product initializes a variable for a supported JDBC driver to an empty string at the node scope. This null value generally overrides a cell scope variable definition, causing a failure at run time. Because the run-time server checks the node scope for a variable definition before it checks the cell scope, it reads the empty string variable and accepts it as a value for the JDBC driver class path. The incorrect class path elicits a classNotFound exception when the server attempts to use the data source.

You can, however, make the data source work at run time by creating the same driver class path configurations at the cell scope and at all relevant node scopes. Follow these steps precisely:
  1. Install the JDBC driver files on the deployment manager node; use that path name to define the driver class path variable for a JDBC provider at the cell scope.
  2. On each node where the data source must function, install the JDBC driver files and use the path to define the WebSphere variable for a JDBC provider at the node scope.
    Important: Ensure success by installing the driver files in locations with identical full-path names on all nodes, including the deployment manager node. Otherwise, the same scenario of a successful test connection will occur, but there is still the possibility of a failure at run time.
If you cannot install the driver files at the same full-path location on every node, including the deployment manager node, do not create cell-scoped data sources. Use the node scope as the largest scope setting for your data sources.

Bypassing variable lookups

You 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 you configure the class path identically 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, Version 4 data source collection, and Version 4 data source settings pages all have Test Connection buttons. After you define and save a data source, you can click this button to ensure that the parameters in the data source definition are correct. On the collection page, you 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.

You 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, you 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.

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




Related concepts
Variables
Related tasks
Defining WebSphere variables
Testing a connection with the administrative console
Testing a connection using wsadmin
Related reference
Administrative console scope settings
Example: Testing a connection using testConnection(ConfigID)
Concept topic    

Terms of Use | Feedback

Last updated: Aug 29, 2010 7:21:45 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=vela&product=was-nd-dist&topic=ctestcon
File name: cdat_testcon.html