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 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 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 CLASSPATH.

When using the pdq.properties file to set global properties, place the file pdq.properties in the JDBC provider CLASSPATH with the pureQuery JAR files. The properties that are set in the JDBC provider CLASSPATH apply to all the applications that use the driver. Properties that apply to a specific application or data source should not be specified here.

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 properties, 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 place these pureQuery Runtime property files in one of the following locations in a WebSphere installation:
  • Under WEB-INF/classes for the Web application
  • Under WEB-INF/lib directory as a JAR file
  • Directly under the installed application directory
If there is a Web module in the application, only the first two options are viable. For EJB applications, you can use any of the three locations mentioned above.

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.

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