This topic is designed to help you troubleshoot problems you’re experiencing with the Parasoft JDBC Driver.

Sections include:

Case Sensitivity

Note that driver properties are case sensitive, so their capitalization matter. For example, VirtualizeServerUrl needs to be used instead of VirtualizeServerURL.

Understanding Driver Communications and Providers

If you’re experiencing problems, it might help to know more about how the driver communicates with Virtualize.

The default (poll) provider for the Parasoft JDBC Driver uses a simple HTTP connection to poll Virtualize, (using the Virtualize Server URL property) for JDBC connection settings at specified intervals (5000 ms by default).

If you prefer to use a JMS provider (for example, for large-scale deployments, to reduce network traffic, or to use asynchronous communication with Virtualize), set the system property parasoft.virtualize.configuration.provider to jms. After a connection is established, the Parasoft JDBC Driver and Virtualize exchange JMS messages to register the driver with Virtualize and receive configuration details (like mode changes) from Virtualize. The use of JMS allows for both ends to function independently. For example, the Parasoft JDBC Driver can remain in passthrough mode even if Virtualize Server is shut down. If the AUT is shut down, it will receive the Parasoft JDBC Driver configuration from Virtualize when it starts up again.

Alternatively, you can use the local provider (as described below).

Local Configuration

If you are unable to get the JDBC Controller associated with a Parasoft JDBC Driver to appear in the Virtualize Server view, you can configure it locally (as opposed to remotely via the Virtualize UI) as follows:

1. Set the system property parasoft.virtualize.configuration.provider to local. This enables you to specify the driver's settings using data source properties or system properties as applicable for the specific vendor. It also prevents the Parasoft JDBC Driver from registering with Virtualize Server (this means that you will not be able to control if from the Virtualize Server view or from Environment Manager).
   • Instead of specifying the driver properties (virtualizeServerUrl and virtualizeGroupID) and system properties (parasoft.virtualize.group.id and parasoft.virtualize.server.url) described in the preceding vendor-specific configuration sections, use the system properties or driver properties that are outlined below (as applicable). For details, see:
     
     • Properties for use with Driver Implementation Classes
     • Properties for use with the Generic Implementation
2. When you are ready to record, configure recording as described in Switching Between Virtualize Modes in Local Mode.

Note that each AUT can use either:

• A locally controlled Parasoft JDBC Driver
• A remotely controlled Parasoft JDBC Driver
• System properties

 Only one will work for a given AUT at a single time.

Properties for use with Driver Implementation Classes

If you are using one of the specialized driver classes (any of the implementation classes above except the “Generic/Other Driver”), then the following properties can be applied through the application server framework. The application server sets these custom properties to the Parasoft JDBC Driver (or any other driver) by attempting to invoke a set method with the same name to the provided driver class. For example, if a property named logLevel is provided, then the application server will use reflection to invoke a method named setLogLevel with a single string argument.

When configuring the Parasoft JDBC Driver, be sure to provide any properties that the original driver requires. The Parasoft JDBC Driver implementation classes either extend or delegate to the original driver implementation classes, thereby passing such properties on to the original driver. The method in which these properties are applied to a JDBC driver depends on the application server. Refer to the previous sections for instruction that pertain to certain popular application servers.

In addition to any properties that the original driver implementation might require, the Parasoft JDBC Driver needs the following properties to be provided.

virtualizeMode

record: Sets the Parasoft JDBC Driver in recording mode. The Parasoft JDBC Driver will delegate JDBC calls to the original driver implementation class while capturing SQL queries and ResultSet data that is returned from the original driver. The captured data is transmitted to the Virtualize Server located at the value of the virtualizeServerUrl property.

virtualize: Sets the Parasoft JDBC Driver in virtualization mode. JDBC calls received by the Parasoft JDBC Driver will be routed to Parasoft Virtualize Server, and the ResultSet data received from Virtualize server will be returned to the application. This mode assumes that recording has already been performed and that Virtualize Server has been configured with a virtual asset so it can respond to the Parasoft JDBC Driver (see Deploying Virtual Assets for details).

passthrough: The Parasoft JDBC Driver will delegate JDBC calls to the original driver implementation class with no data capture or recording. The intention of this mode is to effectively turn the Parasoft JDBC Driver off and have the system at a state similar to the original configuration as if the driver is not there. Note that the JDBC calls still go through the driver and are delegated to the original driver; the Parasoft JDBC Driver is still there in the middle.

hybrid: In this mode, the Parasoft JDBC Driver behavior will be the same as in virtualize mode, except when no matching virtualization data is found. For those cases, it will delegate the JDBC calls to the original driver implementation class with no data capture or recording.

failover: In this mode, the Parasoft JDBC Driver will delegate JDBC calls to the original driver implementation class unless a failure (SQL exception) occurs. If a failure occurs, JDBC calls received by the Parasoft JDBC Driver will be rerouted to the Parasoft Virtualize Server, and the ResultSet data received from the Virtualize server will be returned to the application. 

logFilePath

Applicable when logDestinationType is set to file, and logLevel values of 1 or higher. Specifies the full path to a text file where Parasoft JDBC Driver logging should be saved. It pertains to internal driver logging information, not where the database data is recorded.

This property refers to the location of the local log file that is produced for debugging purposes (for example, events and exceptions coming from the actual JDBC driver). This is NOT the location of the file that logs recorded data. That file is always stored in the Virtual Assets project.

logDestinationType

Indicates where driver logging data should be saved or sent. This pertains to internal driver logging information, not where the database data is recorded. Once this option is set, future driver logging data will be routed to the specified destination.

file: Saves into the file specified by the logFilePath property.

server: Submits the logging data to a remote Parasoft Virtualize Server so it can be viewed and analyzed there. This is convenient so that configuration debugging can be performed without having to access local log files on the application server where the Parasoft JDBC Driver is installed. The logging events are buffered, then transmitted in bursts every 5 seconds. See Configuring Logging for JDBC Operations for details.

stdout: Routes Parasoft JDBC Driver logging events to the standard console output.

stderr: Routes Parasoft JDBC Driver logging events to the standard console error output.

logLevel

Specifies the logging detail level (verbosity) for the Parasoft JDBC Driver. The logs are routed to the destination provided in the logDestinationType property.

0: OFF. No logging takes place to any destination.

1: Log errors only. Stack traces are included in such errors.

2: Log errors and informational events to help debug and analyze issues.

3: Include stack traces with each logging entry.

4: Include traffic communicated between the Parasoft JDBC Driver and the Virtualize Server, but with no stack traces.

5: Includes 3 and 4 data.
Use logging levels 3 and 5 with caution under limited circumstances and scenario runs only. Including stack traces for each informational log entry tends to grow the log file content very rapidly.

virtualizeServerUrl

Specifies the hostname of Parasoft Virtualize Server. This should have the format http://<VIRTUALIZE-SERVER-HOSTNAME-OR-IP>:9080

Port number 9080 is the default. Use a port number other than 9080 only if Virtualize Server has been configured with a different port number.

Driver-Specific Configurations

The following properties need to be specified in order for the Parasoft JDBC Driver to delegate to the original driver successfully during recording. They are specific to the vendor driver that is being used.

IBM DB2 JCC Driver

First, be sure that the configuration for JDBC Provider of the Parasoft JDBC Driver has the classpath appended to it (as copied form the original driver data source). This generally looks similar to:

${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc.jar

${UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cu.jar

${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cisuz.jar

Similarly, the native library path needs to be copied. By default, this is:

${DB2UNIVERSAL_JDBC_DRIVER_NATIVEPATH} 

Second, ensure that the Custom Properties in the Parasoft JDBC Driver Data Source configuration has the following properties defined (at minimum): 

• databaseName (string)
• driverType (integer)
• portNumber (integer)
• serverName (string)

The values for these properties can be obtained from the original driver JDBC Provider configuration. For more information about DB2 driver properties, see http://publib.boulder.ibm.com/infocenter/db2luw/v8/index.jsp?topic=/com.ibm.db2.udb.doc/ad/rjvdsprp.htm.

Apache Derby

The Custom Properties in the Parasoft JDBC Driver Data Source configuration needs to have the following property defined (at minimum):

• databaseName (string)

The value can be obtained from the original driver JDBC Provider configuration custom properties section.

Properties for use with the Generic Implementation

If you are using one of the “Generic/Other Drivers” then the Parasoft JDBC Driver Implementation uses the following system properties:

For details on each property, see the corresponding equivalent driver property using the table and the previous section (Properties for use with Driver Implementation Classes).

parasoft.virtualize.configuration.provider

This must be set to local if you want to configure the Parasoft JDBC Driver locally (as opposed to remotely via the Virtualize UI).   

parasoft.virtualize.driver.proxy.direct

Defaults to false. This flag determines how the Parasoft JDBC Driver establishes the delegation behavior to the original driver (when in record mode). This option depends on whether:

• The application uses a java.sql.DriverManager to create an instance of java.sql.Driver (in which case false is the common setting).
• A Driver is instantiated directly (in which case the flag should be set to the true).

parasoft.virtualize.driver.register.jdbcproxydriver.in.drivermanager

Defaults to false. This flag determines whether the Parasoft JDBC Driver should register itself in the runtime's java.sql.DriverManager using the DriverManager.registerDriver() method. This option depends on whether: 

• The application uses a java.sql.DriverManager to create an instance of java.sql.Driver (in which case true is the common setting). This applies to the ParaBank sample application, where this property should be set to true.
• The driver is being used in a Web application environment (such as WebSphere or WebLogic). In this case, this property should be left false.

Switching Between Virtualize Modes in Local Mode

In local mode, the procedure for switching Virtualize modes varies depending on what application server you’re using:

• WebSphere
• WebLogic 9.2
• webMethods
• WebLogic 10.3 (11g)
• Stand-Alone Applications or Other Application Servers

WebSphere 

Once a data source is configured with the Parasoft JDBC Driver, the mode can be switched between virtualize and record modes. After switching modes, you will need to restart the application server (or take additional steps to eliminate the need for a restart).

The WebSphere application server data source creates a pool of JDBC connections. Thus, while it is possible to switch modes instantly, doing so would affect only new connections requested from the driver. Existing connections would maintain their existing mode. To get around this and allow for instant Parasoft JDBC Driver mode changes to take effect without having to wait for the connections to get recycled or for the server to be restarted, you can reduce the frequency at which idle connections are destroyed in a development environment.

1. In the WebSphere administrative console, navigate to the Parasoft JDBC Driver Data Source.
2. Click Connection Pool Properties.
3. Reduce the Reap time and Unused timeout properties to a much smaller amount (such as 15 seconds), then click OK.
   
4. Reboot the server so this change will take effect.

Once these connection pool property changes take effect, the Parasoft JDBC Driver mode (modifying the custom property virtualizeMode) can be applied without a reboot, as long as:

• Test connection is clicked in order to apply the new properties to the driver.
• No JDBC activity takes place through that data source for at least 15 seconds, allowing any existing connections with the old mode to be destroyed.

WebLogic 9.2

Server restart is required in WebLogic 9.2.

1. Shut down WebLogic.
2. Edit the startWebLogic startup script that you edited in step 2 of WebLogic Environment Setup.
   
3. Switch the parasoft.virtualize.mode property value to the desired mode (for details, see Properties for use with Driver Implementation Classes).
4. Restart the WebLogic server using that startup script.

webMethods

Once a JDBC Adapter is configured with the Parasoft JDBC Driver, you can follow these steps to change the mode (or any of the other driver properties):

1. Go to the IS administration web interface.
2. Expand the Adapters section, then click JDBC Adapter.
3. Disable the JDBC Adapter connection.
4. Click the Edit icon.
5. Modify properties as needed.
   • The virtualizeMode property controls the mode (record/virtualize/passthrough/hybrid/failover). See virtualizeMode for details.
6. Re-enable the JDBC Adapter connection.

You do NOT need to restart the server.

WebLogic 10.3 (11g)

Server restart is not required in WebLogic 10.3.

1. Under the Data Sources section, click the newly created data source.
   
2. Open the Connection Pool tab and change the virtualizeMode property (or any of the other properties) as needed.
   
3. After you see this message
   
   proceed to the Change Center in order to restart the data source.
   
   The changes should then become active.
   
   

Stand-Alone Applications or Other Application Servers

After performing the necessary configuration, you can switch between record and virtualize modes by changing the parasoft.virtualize.mode property.

Configuring the Parasoft JDBC Driver Using System Properties

If your data source container does not allow you to set custom properties, you can configure the Parasoft JDBC Driver settings using system properties. The Parasoft JDBC Driver will still register with the Virtualize server. You will be able to control it from the Virtualize Server view or from Environment Manager.

To configure the Parasoft JDBC Driver settings using system properties:

1. Set the system property parasoft.virtualize.configuration.provider to property.

2. Specify the parasoft.virtualize.group.id and parasoft.virtualize.server.url system properties. For details, see Properties for use with the Generic Implementation.

3. When you are ready to record, switch the Parasoft JDBC Driver mode using the Virtualize Server view or Environment Manager (as explained in Switching Parasoft JDBC Driver Modes).

Configuring Parasoft JDBC Driver Data Sources Using the JDBC URL

If your application server does not allow custom properties to be set, you can configure a JDBC Data Source by adding properties into the JDBC URL. The driver/system properties that are required for all environments can be set into the JDBC URL using the following pattern:

jdbc:parasoft:proxydriver:<property name>=<property value>&<property name>=<property value>:@<original jdbc url>

• The url must be changed to start with

   jdbc:parasoft:proxydriver:

• Properties are name value pairs that are separated using an ampersand (&). Parasoft properties must be terminated with a colon and at sign (:@).
• The original JDBC URL should be the final item in the URL.

For example, a URL for connecting to Oracle using a data source with properties might look like the following (assuming that the required properties virtualizeGroupId and virtualizeServerUrl have been set):

jdbc:parasoft:proxydriver:virtualizeGroupId=parasoft&virtualizeServerUrl=http://localhost:9080:@jdbc:oracle:thin:scott/tiger@localhost:1521:orcl