Skip navigation.
Downloads | Product Documentation | Support

Administration Guide

# Configuring Data Services Platform Applications

This chapter describes how to configure application-level settings for AquaLogic Data Services Platform (DSP). The chapter contains the following sections:

- General Application Settings
- Guidelines for Setting Server Thread Count
- Monitoring Applications
- Terminating an Executing Query
- Using Administrative Properties
- Setting the Transaction Isolation Level

# General Application Settings

You can view and configure runtime settings for DSP-enabled applications, including access control, cache settings, server resources (including thread usage), and log levels.

Note: For details on accessing the Data Services Platform Console (named ldconsole) see Launching the Data Services Platform Console.

To specify general application settings:

1. Click the application name in the Navigation pane of the Data Services Platform Console.

The General settings page appears, as illustrated in Figure 5-1. Note that you must be logged into the console using a user name with administrator privileges.

Figure 5-1 General Application Settings Page

2. Specify settings, as appropriate.
3. Click Apply to save the settings.

Table 5-1 lists the application settings available under the General tab.

Table 5-1 Data Services Platform Server Configuration Settings

Section | Field | Description
--- | --- | ---
Access Control | Check Access Control | Specifies whether the configured security policy settings will be enforced for the application.
Allow default anonymous access | Enables access to the application by default (unless a more specific policy blocks it). If enabled, all users can access resources by default, even unauthenticated users. Disallowing default anonymous access disables access to the application by default (unless a more specific policy permits it). The anonymous access option works only with the WebLogic Authorization provider.
Cache | Enable Cache | Enables or disables (default) the caching of query results for stored queries. To enable results caching, enable (check) this check box. To disable results caching, clear (uncheck) this check box. For more information about caching, see Configuring the Query Results Cache.
Cache data source name | The JNDI data source name for the database where the cache is stored.
Cache table name | The name of the database table where cached data is stored. The default table name is <appName>_CACHE.
Server Resources | Max number of query plans cached | A query plan is a compilation of a query. The optimal number of query plans cached depends on the size of the queries. You will need to monitor the memory usage and performance of your server to determine whether to change this setting.
Max threads for application | The maximum number of threads in the Data Services Platform server pool used to handle query requests. The default setting is 20. The minimum setting is 1. If the specified value is invalid, the server uses the default value of 20. Note: The maximum threads value that you specify here does not affect the WebLogic Server server thread pool. The value specified here applies only to the thread pool created and used by the Data Services Platform query engine for processing requests on application view, web service, or custom function data sources. For more information on configuring thread counts, see Guidelines for Setting Server Thread Count.
Max threads for one query | The maximum number of threads allowed for a single query. Use this to limit the number of threads spawned by a single query. The actual number of threads used will not exceed the maximum number of threads specified in Maximum Threads, regardless of the Maximum Number of Threads Per Query setting. The default setting is 4. The minimum setting is 1. If the specified value is invalid, the server uses the default value of 4. Note: The maximum threads value that you specify here does not affect the WebLogic Server server thread pool. The value specified here applies only to the thread pool created and used by the Data Services Platform query engine for processing requests on application view and web service data sources. For more information on configuring thread counts, see Guidelines for Setting Server Thread Count.
Log Level | Logging | The verbosity of the events logged. The options include the following: Error. Runtime exceptions. Notice. Possible errors that do not affect runtime operation, as well as error level events. Information. Start/stop events, unsuccessful access attempts, query execute times, and so on, as well as error and notice level events. The log file is in the following location: <BeaHome>\user_projects\domains\<domainName>\ <domainName>.log

# Modifying Data Source End Points

It is frequently desirable to change the location of data sources or names of other artifacts as you move applications from development to staging to production. For example, if you are using "dummy" data sources during development in order to protect confidential or otherwise secured information, you will at some point need to substitute a new data source with the actual data for the test version. You can make these changes through the Data Services Platform Console.

In modifying end points you are not limited to the name and location of a data source. It is also possible to change the target names of subordinate artifacts. In the case of relational sources this includes catalog name, schema names, package names, table names, and stored procedure names.

Note: Once set, end point modifications are effective until they are further modified or reverted to the original name. To assign the end point name its original value, simply click Reset to original value. This option will not revert the value to the previous setting, it will directly revert it to the original name. So, if you have assigned a few names over time, the moment you click Reset to original value, the values revert to the same as those in the Original Value column.

Figure 5-2 Setting End Points for Relational Sources

Note: Whenever you change the end point for an artifact you need to ensure that the intrinsic aspects of that artifact remain identical with the old source. In the case of a relational source properties such as Vendor Type and Version must be identical.

When you change the end point of a particular object, the new end point appears in brackets next to the original name. Figure 5-3 below displays the original data source name, and the new data source name (in square brackets) adjacent to it.

Figure 5-3 End Point Settings Reflected in the Navigation Pane

Table 5-1 identifies the artifacts whose end point settings can be changed.

Table 5-1 Artifacts for Which End Points Can Be Modified Through the Administration Console

Data Source Type | Artifact
--- | ---
Relational | Data source name and location
| Catalog
| Schema
| Package
| Table
| Stored procedure
Web Service | Web service name and location
| Service
| Port
| Operation
XML Content | Data source name and location
Delimited File Content | Data source name and location

#### Physical Data Source Locations

You can view a list of data services and function libraries that use the defined relational databases. Click the Where Used tab to view the list of data services and their specific paths (Figure 5-4).

Figure 5-4 Physical Data Services Relational Dependencies

# Guidelines for Setting Server Thread Count

The optimal thread count settings you configure depends on the physical resources of the machine on which you deploy Data Services Platform, the anticipated load, and the type of application you are deploying. Increasing the number of threads can accelerate processing, but since each thread consumes memory, you must achieve a balance based on the available resources.

Use the following general guidelines for settings the thread count:

- The maximum threads set for an application should not exceed the WebLogic Server thread count.
- The total maximum application thread counts for all deployed applications should not be significantly greater than the total WebLogic Server thread count.

Data Services Platform only uses the thread pool for acquiring web service calls; threads are only spawned when web services are invoked by queries. Therefore, an application that does not rely on web service content can have a relatively low thread count setting.

For more information on tuning performance for the WebLogic Server and applications, see the following:

>     http://e-docs.bea.com/wls/docs81/perform/index.html

# Monitoring Applications

You can view statistics and status information for a Data Services Platform application, particularly relating to query activities, using the Monitor tab. You can also monitor active application processes, displaying information such as the user who initiated the process, the time is has been running, and the number of cached entries for the process type.

To monitor an application:

1. Click the name of the application node in the Navigation pane of the Data Services Platform Console.

The General settings page appears. Note that you must be logged into the console using a user name with administrator privileges.

2. Click the Monitor tab.

The monitoring information for the application appears, as illustrated in Figure 5-5.

Figure 5-5 DSP Administration Console Application Monitor Tab

Table 5-2 describes the information displayed in the Monitor tab.

Table 5-2 Monitoring Statistics for the Liquid Data Server

Section | Field | Description
--- | --- | ---
Monitoring information for... Application | Active Queries | The number of query instances currently running.
Cached Queries | The total number of XQuery plans currently cached in memory. A cache entry is made for each distinct invocation of the named function with different input parameters.
Active Updates | The number of update functions currently running.
Monitoring information for functions of... Application | Function Name | The name of the function for which the statistics apply.
Instance ID | The unique identifier assigned to the process by the Data Services Platform runtime components.
User Name | For secured data services, the name of the user that invoked the service.
Running Time | The amount of time the query has been running in milliseconds.
Server |
Terminate Query | Checkbox option allowing you to terminate an executing query associated with a function.

# Terminating an Executing Query

Once invoked, a data service function runs until either it gets a result or a time-out expires (assuming a time-out period is set). The time-out setting enables you to specify, in the query, the maximum time a query should wait for unresponsive data sources.

In some cases, it may be necessary to cancel the execution of a function. The Monitor tab enables you to view and cancel currently running queries. The page also displays the user associated with the query and cache information.

When you terminate a process, the operation in progress finishes, then the process completes without executing subsequent nodes.

Note: The submit query is rolled back only in cases when you are using the XA driver.

To terminate function execution:

1. Click the name of the application in the Navigation pane.

The General settings page appears. (Note that you must be logged into the console using a user name with administrator privileges.)

2. Click the Monitor tab.

The list of functions currently running appears in the functions table.

3. Select the check box in the Terminate Query column for the appropriate function, and click Apply to terminate the query.

A confirmation dialog box is displayed.

4. Click OK to confirm, or Cancel to dismiss the dialog and cancel the action.

Note: Terminating a query triggers a weblogic.xml.query.exceptions.XQuerySystemException on the client.

# Using Administrative Properties

An administrative property is a user-defined property that you can configure using the DSP Console. The value of an administrative property can be used in XQuery functions, either in data service functions or security XQuery functions.

Note: For information on security XQuery functions, see Securing Data Services Platform Resources.

An administrative property is a convenient way of having function parameters that can be easily changed by the administrator, without having to modify the body of either the data service function or security XQuery function.

The administrative property has application scope — any data service in the application can use the property value. The property value can be accessed using XQuery with the BEA function `get-property()`. The function takes the name of the property as an argument and returns the value as a string. It also takes an argument that serves as the default value for the parameter. This value is used if the property is not configured in the console.

The following shows a complete example of an XQuery Function Library function using an administrative property:

>     declare function f1:getMaximumAccountViewable() as xsd:decimal {
>        let $amount := fn-bea:get-property("maxAccountValue", "1000.00")
>                                        cast as xsd:decimal
>        return $amount
>     };

To manage administrative properties:

1. Click the name of the application in the Navigation pane. The General Settings page appears. (Note that you must be logged into the console using a user name with administrator privileges.)
2. Click the Administrative Properties tab. The list of property names currently defined appears in the table, as illustrated in Figure 5-6.

Figure 5-6 Administrative Properties Tab

Table 5-3 describes the information displayed in the Administrative Properties tab:

Table 5-3 Administrative Properties

Column | Description
--- | ---
Property Name | The name of the administrative property.
Property Value | The current value of the property.
Delete Property | A Trash icon enabling you to delete the property.

1. To add a property, complete the following:

1. Enter a name for the property in the Property Name field.

The name must match the name property passed to the `get-property()` function used to access the properties value. For example:

>     fn-bea:get-property("maxAccountValue", "1")

2. Optionally, enter an initial value for the property.

You can change this value later, if required.

3. Click Add Property.

The property appears in the list.

2. To change a property value:

1. Enter a new value in the Property Value field (in the list of currently defined properties).
2. Click Apply.

3. To delete a property:

1. Click the delete icon ( ) next to the property.
2. Confirm the delete when prompted.

Note that the default value for the property is used in any `get-property()` call using the deleted property.

# Setting the Transaction Isolation Level

In some instances, Data Services Platform may not be able to read data from a database table because another application has locked the table, causing queries issued by Data Services Platform to be queued until the application releases the lock. To prevent this, you can set the transaction isolation to read uncommitted in the JDBC connection pool on your WebLogic Server.

To set the transaction isolation level:

1. Start the Administration Console in a web browser by opening the following URL:

>     http://<HostName>:<Port>/console

For example, to start the Administration Console for a local instance of WebLogic Server (running on your own machine), type the following URL in a web browser address field:

>     http://localhost:7001/console/

2. Expand Services —>JDBC —>Connection Pools under the domain in which the Data Services Platform application runs, and click the name of the connection pool you want to configure.

The Connections tab appears, as illustrated in Figure 5-7.

Figure 5-7 Connections Tab

3. Click Show in the Advanced Options section of the page.

The page expands to include the Advanced Options section.

4. Scroll to the bottom of the section, and enter the following in the Init SQL field:

`SQL SET TRANSACTION ISOLATION LEVEL READ UNCOMMITTED`

5. Click Apply.