Scope of pureQuery Runtime properties in a WebSphere Application Server environment

You set pureQuery Runtime properties to control the operation of pureQuery Runtime. You can control the scope of pureQuery Runtime properties by setting the property in a specific WebSphere® location. If you set a property in multiple locations, pureQuery Runtime determines which value to use by an order of precedence that is based on the location.
WebSphere uses the location to determine the scope of the property and to determine the order of precedence if a property is specified in multiple locations. The levels of scope for WebSphere are in the following the order of precedence:
  • Application level: The pureQuery properties apply to the WebSphere application. The pureQuery Runtime property settings at the application level override both the global level and the data-source level settings for the same property. Otherwise, the pureQuery Runtime properties are merged with the global pureQuery properties and data-source level pureQuery properties.
  • Data source level: The pureQuery properties apply to all connections that are created from the data source. The data-source level property settings override the global level property settings if the same property is defined at both levels. Otherwise, the pureQuery Runtime properties are merged with the global-level pureQuery properties.
  • Global level: The pureQuery properties apply to all applications in the WebSphere Application Server.

You can use the pureQuery Runtime property finalRepositoryProperties to retrieve runtime properties from a file system or a repository in a database. Retrieving properties from a file system or a repository affects the order of precedence.

Specifying a file system or a repository

Before pureQuery Runtime properties retrieves and sets from the location that is specified by the finalRepositoryProperties property, pureQuery client optimization and existing pureQuery Runtime properties are reset to default values. Any property that is set at the data source level is not saved. Properties that are retrieved and set as global pureQuery properties are not affected.

The following examples show how pureQuery Runtime property settings are determined:
  • If a property is set at multiple levels, the level determines which value is used. For example, if the value of captureMode is set to OFF in the pdq.properties global properties file, the value is set to ON, NEW_STMTS, or LITE in the data source-level pdqProperties for the data source that are used by the application, and set to OFF in application level pdq.appwide.properties, then the application level setting prevails and value of the captureMode property is set to OFF .
  • If pureQuery Runtime properties are retrieved from a file system or a repository with the finalRepositoryProperties property, the value of the captureMode property that is specified in the location prevails irrespective of the property setting at the global, data source, or application levels. For example, if captureMode is set to ON, NEW_STMTS, or LITE in data-source level pdqProperties for the data source that is used by the application and the finalRepositoryProperties property is also set, pureQuery Runtime retrieves the properties from the location that is specified by the finalRepositoryProperties property. If the captureMode property is not set in the retrieved properties, the captureMode property is set to the default, OFF. If the value of the captureMode property is set as a retrieved property, that value is used.

Control the scope of pureQuery Runtime properties in a WebSphere environment

In a WebSphere environment, you set the pureQuery Runtime properties in different locations to control the level of scope of the properties. The location also affects the order of precedence when a property is set in multiple locations.

Location for global scope
Specify the pureQuery Runtime properties in a properties file pdq.properties and include the file in the WebSphere JDBC provider class path.

When using the pdq.properties file to set global properties, place the directory containing the file pdq.properties in the JDBC provider class path that contains the pureQuery JAR files. The properties that are set in the JDBC provider class path apply to all the applications that use the driver. Do not specify properties that apply to a specific application or data source here.

The pureQuery Runtime property traceFile can be specified only in a global pdq.properties file.

Set global pureQuery Runtime properties from the WebSphere Application Server Admin Console:
  1. Select the link JDBC Providers.
  2. For JDBC Provider, select either DB2 Universal JDBC Driver Provider or DB2 Universal JDBC Driver Provider (XA).
  3. If necessary, add the directory that contains the pureQuery JAR files to the field Class path.
    Note: Do not include the file name pdq.properties.
  4. Apply the changes to the selected JDBC Provider and save the changes.
  5. It might be necessary to change the field Class path for both JDBC providersDB2 Universal JDBC Driver Provider and DB2 Universal JDBC Driver Provider (XA)
  6. Place your pdq.properties file in the directory that you specified in the field Class path.

    When the pdq.properties is in the directory, both the WebSphere Application Server and pureQuery Runtime find the properties file.

  7. Depending on your application environment, you must restart either the application server or the WebSphere Application Server, or both servers for the changes to take effect.
Note: While you modify the pdq.properties file to move from executing SQL statements from dynamic to static mode, an application server restart is needed to reflect the changes. Because the properties are applied to all the data sources that uses the particular JDBC provider, all applications run with the same execution mode, and all captured SQL statements go to the same pureQueryXML file during capture.
Location for data-source-level scope

Specify the JDBC Driver custom property pdqProperties on the WebSphere data source.

Users can set the pureQuery Runtime properties for each data source. The data source level is appropriate when the setting for each data source needs to be independent from each other. For example, if the application uses multiple distinct data sources, each data source captures the SQL that is targeted for it in its own pureQueryXML file.

When the properties are set on the data source, they are applied to all the applications that are using that data source. So when applications share a data source, the captured SQL statements are captured in a common file for all applications.

Each time changes are made to the value of the a data source's pdqProperties property, the application server needs to be restarted so that the application server can use the new values.

Location for application-level scope
Enable pureQuery Runtime properties at the application-level scope by using one or both of the following property files in the application CLASSPATH:
  • pdq.appwide.properties
  • pdq.DSName.properties

    The DSName is the value of the WebSphere DB2® Universal JDBC Driver custom property dataSourceName that is set on the data source.

The pdq.appwide.properties file specifies the application-specific pureQuery properties. All property values that are specified in this file will be applied to all the data sources that the application uses.

The pdq.DSName.properties file specifies the data-source-specific properties for an application. The properties specified in this file will be applied only to the specific data source that the application uses. The DSName is the string value of WebSphere custom property dataSourceName for the data source. This custom property is set using steps similar to the steps used to set the WebSphere custom property pdqProperties.

For applications that use the data source name DSName, the properties specified in pdq.DSName.properties have precedence over those specified by pdq.appwide.properties.

You can create a JAR file containing the pureQuery Runtime properties files and place the JAR file directly under the installed application directory in a WebSphere installation. Then you update the MANIFEST.MF file of all modules that use the pureQuery Runtime properties.

If an application uses application-specific properties files, such as pdq.appwide.properties or pdq.dsName.properties files, to make the new properties take affect when properties are changed, you must purge the WebSphere connection pool and restart the application instead of restarting the application server to make new property values to take effect.

In the following example the pureQuery Runtime properties are in pdq.appwide.properties and the dynamic web project (.war file) is part of an .ear file. After deploying the application in a WebSphere environment, the installedApps directory contains the MyAppEAR.ear directory. The following steps describe how how enable pureQuery Runtime properties at the application level:
  1. Create a JAR file that contains pdq.appwide.properties. In this example, the file is pdq_props.jar.
  2. Place pdq_props.jar in the following folder:
    WAS_ROOT/profiles/AppSrv01/installedApps/version1/MyAppEAR.ear 
  3. Edit the MANIFEST.MF file of all modules that use the pureQuery Runtime properties. In this example, the war file MyApp.war uses the properties and the MANIFEST.MF is in the following directory:
    WAS_ROOT/profiles/AppSrv01/installedApps/version1/MyAppEAR.ear/MyAppEAR.war/META-INF/MANIFEST.MF 

    Add the following Class-Path entry for the pdq_props.jar file:

    Class-Path: pdq_props.jar
    The entry is on a single line in the MANIFEST.MF file and there is a space between the property and file name.
If modules in a application use different data sources, you can specify pureQuery Runtime properties for each data source. This example assumes that a custom JCC property dataSourceName is set on the DataSource. Also in this example, two different data sources with data source names DS1 and DS2 exist in the WebSphere Application Server environment. In the example, an application consists of two modules:
  • Web module Web1 that uses data source DS1
  • EJB module EJB1 that uses data source DS2
You create two pureQuery Runtime property files for each data source.
  • pdq.DS1.properties
  • pdq.DS2.properties
You create a JAR file that contains the two files pureQuery Runtime files and place it under the installed application directory as describe previously.
Location is a file system or a repository

You specify a file system or a repository in a database with the pureQuery Runtime property finalRepositoryProperties. The property can be specified in the global level, data source level, or at the application level.

pureQuery Runtime applies the following rules when it retrieves properties from a location that is specified by the finalRepositoryProperties property:
  • Properties that are loaded from finalRepositoryProperties affect only the application that is loading them.
  • Properties that are loaded from finalRepositoryProperties that are not valid for pureQuery client optimization or pureQuery Runtime are ignored and logged if logging is enabled. This behavior is the same as data-source level or application-level properties.
  • The value for the property finalRepositoryProperties is ignored if it is retrieved from the location specified by the initial finalRepositoryProperties property. pureQuery Runtime does not support multiple levels of redirection with the finalRepositoryProperties property.
  • In addition to specifying the finalRepositoryProperties property, you specify the pureQuery Runtime property propertiesGroupId to specify the runtime group version in a repository created in a database that the application uses to retrieve the pureQuery data.

    The value for the propertiesGroupId property is ignored unless it is used with a repository created in a database. When a repository is being used, you cannot change the value of the propertiesGroupId property within the redirected properties.

  • The pureQuery Runtime properties that are retrieved from the location specified by the finalRepositoryProperties property will be enabled for automatic property refresh only if the propertiesRefreshInterval property is one of the properties retrieved from the location and is set to a positive value. Each application can have a different propertiesRefreshInterval that is defined in the properties that are retrieved from finalRepositoryProperties.

The pureQuery Runtime repositoryRequired property controls the behavior of pureQuery Runtime when using file system or a repository. You specify the property in a WebSphere location pureQuery to control the pureQuery Runtime behavior. The value of the repositoryRequired property can be overridden by setting the repositoryRequired property as one of the retrieved properties.


Feedback