Skip navigation.

eDocs Home > BEA Liquid Data for WebLogic 8.5 Documentation > Administration Guide > Configuring the Query Results Cache

Administration Guide

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents Index View as PDF   Get Adobe Reader

Configuring the Query Results Cache

This chapter describes how to set up and manage caching for data services in BEA Liquid Data for WebLogic.

The chapter contains the following sections:

Note: Caching is only available for data service function results. It does not apply to ad-hoc queries or to security XQuery functions, which are never cached.

 

Understanding Results Caching

By caching the data returned by data service functions, you can improve response times for clients and reduce the processing burden on back-end systems.

When results caching is enabled, the first time a data service function is run, Liquid Data saves the results in the query results cache. The next time the function is run with the same parameters, Liquid Data checks the cache configuration and, if the results have not expired, retrieves the results from the cache rather than from the external source. Note that a cache entry exists for the results of each function invocation with distinct parameters. In cases when a cache-enabled function is invoked twice with two different parameters, two cache entries will be created.

Caching is disabled by default. Once it is enabled, you can configure the cache for individual data service functions as needed. Configuration tasks associated with caching include the following:

The time-to-live (TTL) setting can be set individually, that is, by data service function. In general, the more dynamic the underlying data, the more frequently the cache should be set to expire. In some cases, caching should not be used at all.

For example, if the data changes frequently and real-time access to it is critical. On the other hand, for functions that return static data, you can configure the results cache so that it never expires. If the cache policy expires for a particular function, Liquid Data flushes the cache result automatically on the next invocation.

In the event of a Liquid Data Server shutdown, the contents of the results cache are retained. Upon server restart, the Liquid Data Server resumes caching as before. On first invocation of a cache-enabled function, the Liquid Data Server checks the results cache to determine whether the cached results for this function are valid or have expired, and then proceeds accordingly.

Note that a data service developer can prevent caching for a data service function by setting the Cache Enabled attribute for the function to false. (By default, caching is enabled for data service functions.) When caching is disabled in the data service design, caching cannot be enabled in the Administration Console for any of that data service's functions. For more information, see the Liquid Data for WebLogic Data Services Reference Guide.

Liquid Data also provides a cache API that allows clients to bypass cached results, getting fresh results when needed. Also, the cache API allows for client-side cache flushing. Applications should manually refresh the cache after an update to ensure access to the most recent data.

Note: Caching is particularly effective in cases when significant processing has been applied against large data sets, producing filtered results. For optimal performance, it is recommended that you not enable caching on functions that simply return large data sets directly from a relational database data source.

You can use any data source configured for WebLogic as the caching database. Liquid Data can set up the cache table in the data source for you (if the server is in development mode), or you can create it yourself as described in the following section. Note that it is recommended that Liquid Data application not share cache tables. There should be separate tables for each application.

To use results caching, you must have one of the following database servers installed and running:

Since the Liquid Data cache may contain sensitive data, it is important to maintain access control over the cache database so that only authorized users can access it. Also, it is recommended that the JDBC data source used for cache not be used for other purposes.

 

Setting Up Caching

The steps for setting up cache depend on several factors, including whether you are in development or production mode and whether you need to customize the cache table schema. Figure 7-1 shows the steps for setting up caching.

Figure 7-1 Cache Setup Steps

Cache Setup Steps


 

The steps illustrated in Figure 7-1 are described in the following sections:

Step 1: (Optional) Run the SQL Script to Create the Cache Tables

For a WebLogic server that is in development mode, you can have Liquid Data set up the cache table automatically from the Liquid Data Console using whichever data source you choose. For production environments, or if you want to customize the cache schema, you will need to run the SQL scripts manually.

You can create the cache table using SQL scripts in the subdirectory corresponding to a particular DBMS at the following location:

<WebLogicHome>/liquiddata/dbscripts/

For example:

<WebLogicHome>/liquiddata/dbscripts/oracle/dbscript.sql

To create the cache table:

  1. Open the script from the subdirectory that corresponds to your DBMS and modify the name of the created table so that it is unique for the application.

    2. It is recommended that each application keep its cached data in its own cache table. For example, you can name the table <appname>_CACHE.

  2. Make any other schema changes, as required.

    3. You should not change the column names or otherwise modify the structure of the schema tables (except in specific cases, as noted in Modifying the Cache Table Structure on page 7-6). See Table 7-1 for information about the cache table schema.

  3. Run the script.
  4. Index the table based on the CHASH column (for retrieval) and the CUID column (for record updates).

    5. When the table is created automatically by Liquid Data (as described inStep 3: Specify the Cache Data Source and Table on page 7-8), an index for CHASH is created. The automatically created name is the table name with "_INDEX" appended to it.

Note: On DB2, the name is truncated to a maximum of 18 characters.

Modifying the Cache Table Structure

Liquid Data requires that its cache tables have a specific schema. Therefore, you should generally not modify the structure of the cache table. In some cases, however, the default column sizes may need to be adjusted based on the deployment. This may be a requirement in cases when you have data services that frequently serve result sets that are larger than the content columns in the default database tables and you are using either DB2 or Pointbase as your DBMS.

For DB2 and Pointbase, the scripts create the CINVKEY and CCONTENT columns (which store the results data) with a specific size, as shown in Table 7-1. If any serialized keys or content need to be larger than that size, the table schema should be adjusted accordingly before running the script.

Before attempting to implement customizations to the cache table, you should be familiar with the schema as shown in Table 7-1.

Table 7-1 Cache Table Schema  

Column

Description

CUID

Unique numeric identifier for the cache entry.

CHASH

Hash value of the key (CINVKEY) as a 64-bit integer. This field enables fast searches, since searching by the key itself is inefficient as the key is stored as a binary object. (In fact, searching by the key itself is impossible for any DBMS for which the scripts create the CINVKEY as a BLOB type).

CEXPIRE

Timestamp value indicating when the record expires. This value is computed during record insertion as current time plus the TTL value defined for the function.

CFID

Serialized name of the function. When the table is created automatically, VARCHAR(512) type is used. The value should be adjusted to a lower or higher size if names of all functions in an application are smaller or if some names are larger then 512 characters.

CFARITY

The number of arguments the function accepts. This is used to differentiate functions in case of function overloading (not currently used).

CINVKEY

The serialized invocation identifier consisting of the function and its arguments (created with a size of 50 kilobytes on a Pointbase DBMS).

CCONTENT

Binary data constituting the cached results. (Created with size of 1 gigabyte for DB2 and 200K for a Pointbase DBMS.)


 

Step 2: Create the JDBC Data Source for the Cache Database

After creating the cache table, you can use the WebLogic Administration Console to create a JDBC data source on the WebLogic Server that points to the database that you have set up for the Liquid Data cache.

Note: If using Oracle as your cache database, you must set the Honor Global Transactions setting to FALSE (it is set to TRUE by default). When you create the Oracle JDBC data source in the WebLogic Administration Console, you must uncheck the Honor Global Transactions box.

Once created, you can enable the result cache as described in the following section.

Step 3: Specify the Cache Data Source and Table

After configuring the table that you want to use for caching as a JDBC data source in the WebLogic Administration Console, you can set up the cache tables using the Liquid Data Console.

To specify the cache database and enable caching:

  1. Select the application node in the Navigation pane.

    2. The General tab appears, as illustrated in Figure 7-2.

    Figure 7-2 Enabling Results Caching for an Application

    Enabling Results Caching for an Application


     


     
  2. In the Cache section of the General tab, click Enable Cache.
  3. Using the Cache Data source name drop-down list, choose the JNDI name of the data source you configured for the cache table.

    4. If you did not create a cache table, choose the data source in which you want Liquid Data to create the cache table.

  4. If you created a custom cache table for the application, enter its name in the Cache table name field.

    5. Otherwise, either enter another name for Liquid Data to use when creating the table or leave the field blank, in which case the default name, <appName>_CACHE, will be used.

  5. Click Apply.

Once caching is enabled, you need to configure results caching for each function.

Step 4: Enabling Caching by Function

After enabling Cache settings for the application, you can configure data service function caching. For each function, you can specify whether caching should be enabled, and set the time-to-live (in seconds) for cache entries.

To enable caching by function:

  1. Click the data service name in the Navigation pane.

    2. The Cache page appears, as illustrated in Figure 7-3.

    Figure 7-3 Enabling Caching by Function

    Enabling Caching by Function


     


     
  2. Check the Enable Cache checkbox for each function for which you want to enable caching.
  3. Enter a time-to-live value, in seconds, for each cache-enabled function.

    4. The more dynamic the underlying data, the more frequently the cache should be set to expire.

  4. Click Apply to save your changes.

    5. Notice that you can also purge the cache by function on this page and view the current cached entries.

Note: All data service functions support caching by default, and can be enabled for caching as described in this procedure. Developers can, however, disable function caching using the WebLogic Workshop.

 

Purging Cache Entries

Purging the cache removes cached entries from the cache database. When the cache is purged, each function will execute against its data sources until it is cached again. Liquid Data flushes the cached query result for a given stored query whenever any of the following events occur:

Liquid Data flushes the cached function result on the next invocation whenever any of the following events occur:

You can also purge the cache manually, either for the entire application at once, or for individual functions. This section describes the following:

Purging the Cache for an Application

You can purge the cache for an application using the General Application Settings page. To purge the cache for an application:

  1. Select the application node in the Navigation pane of the Liquid Data Console.

    2. The General Application Settings page appears, as illustrated in Figure 7-4.

    Figure 7-4 Purging the Cache for an Application

    Purging the Cache for an Application


     
  2. Click the Purge Cache link in the Cache section of the General tab.

    3. The console asks for confirmation before purging the cache.

  3. Click Yes.

    4. The purge occurs immediately, without having to apply changes.


     

Purging the Cache for a Function

You can purge the cache for individual functions using the Cache page, as illustrated in Figure 7-5.

Figure 7-5 Purging the Cache for a Function

Purging the Cache for a Function


 


 

To purge cache by function:

  1. Click the data service for which you want to purge cache by function in the Navigation pane.
  2. Click the Trash can next the function for which you want to purge cache.


    3.  

 

Skip navigation bar  Back to Top Previous Next