Test connection service

Test connection service

The test connection service for validating data source configurations...

Uses a testConnection operation to instantiate the data source configuration.
Gets a connection
Immediately closes the connection

If you have a data source under a cluster scope, after creating a new data source, restart the node with stopNode.sh/startNode.sh.

Verifying the scope settings

Associating WebSphere variables with the data source configurations can elicit test connection results that are incongruent with the run-time behavior of the application. In some cases, a test connection operation fails, but the physical data source functions normally during application runtime. The cause of the potential conflict is the difference between how the appserver 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.
At runtime, WAS invokes a physical data source by resolving the appropriate variable at a level 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, WAS 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.

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.

Data source scope Cell level variables Node level variables Server level variables
Cell level Ok Fail Fail
Node level Ok Ok Fail
Server level Ok Ok Ok

Contrary to expectations, these test connection failures generally do not translate into run-time failures. Verify the location of the JDBC driver files is accessible to every client that must use the data source, and configure the 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 dmgr process (as indicated in Table 1), where Application Server can resolve the cell-scoped variable. That data source can fail at runtime because the cell-scoped variable might be overridden with a null value.
When you create a node, Application Server creates environment variables for all supported JDBC drivers at the node scope, and initializes each variable with an empty string. Because an appserver attempts to resolve variables from the low end of the scope spectrum to the high end, the node scope variable overrides the cell scope variable at runtime. The server reads the empty string and accepts it as the JDBC driver class path. The null class path elicits a classNotFound exception when the server attempts to use the data source.
Use either one of the appserver admin options, we can prevent the empty string from becoming the final value for the driver class path variable.

Use the WAS admin console: The data source wizard program copies the value of the cell-scoped variable (which you specify in the JDBC provider creation wizard) to the node-scoped variable of the same name. The wizard program performs this copy operation only if the node-scoped variable has the empty string value; thus the program does not change a valid class path specified earlier.To ensure that the data source works with the node-scoped variable at runtime, follow these steps:

Install the JDBC driver files on the dmgr node, as well as every node where the data source must function.
Use the driver file path on the dmgr to define the WebSphere variable for a JDBC provider at the cell scope.
Verify the data source is associated with the dmgr JDBC provider, and has the same cell scope.
Ensure success by installing the driver files in locations with identical full-path names on all nodes, including the dmgr node. Otherwise, the same scenario of test connection success, but run-time failure, is likely to reoccur.

Use the wsadmin scripting tool: To make the data source work for both the test connection operation and runtime, create the same driver class path configurations at the cell scope and at all relevant node scopes. Follow these steps:

Install the JDBC driver files on the dmgr node; use that path name to define the driver class path variable for a JDBC provider at the cell scope.
Verify the data source is associated with the dmgr JDBC provider, and has the same cell scope.
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. Each of these providers must have the same configuration.
Ensure success by installing the driver files in locations with identical full-path names on all nodes, including the dmgr node. Otherwise, the same scenario of test connection success, but run-time failure, is likely to reoccur.

Use cell scope resources only if all nodes that need access to the data source, including the dmgr node, run on the same platform and have the JDBC drivers installed in the same location. Otherwise, use the node scope as the largest scope setting for the 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 we 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 admin console, wsadmin, or a Java stand-alone program. Each process invokes the same methods on the same MBean.
Administrative console
WAS allows you to test a connection from the admin 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, we can click this button to verify the parameters in the data source definition are correct. On the collection page, we can select several data sources and test them all at once. Note that there are certain conditions that must be met first.

The following exception occurs when you click Test Connection to connect a Sybase data source from the admin console.
Test connection failed for data source isagent on server server1 at node svtaix24Node01 with the following exception: java.lang.Exception: java.sql.SQLException: JZ006: Caught IOException: java.net.ConnectException: A remote host refused an attempted connect operation.DSRA0010E: SQL State = JZ006, Error Code = 0
This exception occurs when the Sybase data source port number is not matched to the port configured in Sybase server. The default port number is 5000. Check the port number of the Sybase server in the interfaces file under /<sybase install directory>.
WsAdmin tool
The wsadmin tool provides a scripting interface to a full range of WAS 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. we 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 the topic, Testing a connection using wsadmin.
We can also test a connection by invoking the MBean operation. Use the example in the topic, Example: Testing data source connection using wsadmin, as a guide for this technique.
Java stand-alone program
Finally, we 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 an ND installation of Application Server, you connect to the JMX server running in the dmgr, 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 the topic, Example: Test a connection using testConnection(ConfigID).

Related concepts

WebSphereТЎ Variables

Related tasks

Creating, editing, and deleting WebSphereЎ variables
Testing a connection with the admin console
Testing a connection using wsadmin
Testing data source connections using scripting
Administrative console scope settings
Example: Testing a connection using testConnection(ConfigID) Т Т Т

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.