9
Using Discoverer with Oracle9iAS Web Cache

9.1 Using Discoverer with Oracle9iAS Web Cache

This chapter describes how to use Oracle9iAS Web Cache to enhance Discoverer Viewer performance, and contains the following topics:

• Section 9.2, "About Oracle9iAS Web Cache"

• Section 9.3, "What are the benefits of Oracle9iAS Web Cache?"

• Section 9.4, "How does Oracle9iAS Web Cache work?"

• Section 9.5, "When to use Discoverer Viewer with Oracle9iAS Web Cache"

• Section 9.6, "How to use Discoverer Viewer with Oracle9iAS Web Cache"

• Section 9.7, "How to turn on Oracle9iAS Web Cache for Discoverer Viewer"

• Section 9.8, "How to display the Rerun Query link, hide the Preferences link, and hide the Presentation Options link"

• Section 9.9, "How to turn off Discoverer Viewer's 'sticky worksheet' behavior"

• Section 9.10, "Notes about using Discoverer Viewer with Oracle9iAS Web Cache"

9.2 About Oracle9iAS Web Cache

Oracle9iAS Web Cache is a component of Oracle9i Application Server that improves the performance, scalability, and availability of Web sites. By storing frequently accessed pages in memory, Oracle9iAS Web Cache eliminates the need to repeatedly process requests for those pages on middle tier servers and databases. You manage Oracle9iAS Web Cache using the Oracle9iAS Web Cache Administration page.

Figure 9-1 Oracle9iAS Web Cache Administration page

Text description of the illustration webcachb.gif

Oracle9iAS Web Cache sits in front of application Web servers, caching their content, and providing that content to Web browsers that request it. When Web browsers access the Web site, they send HTTP protocol or HTTPS protocol requests to Oracle9iAS Web Cache. Oracle9iAS Web Cache, in turn, acts as a virtual server to the application Web servers. If the requested content has changed, Oracle9iAS Web Cache retrieves the new content from the application Web servers. The application Web servers may retrieve their content from an Oracle database.

Figure 9-2 Oracle9iAS Web Cache overview

Text description of the illustration webcachc.gif

For more information about Oracle9iAS Web Cache, see Oracle9iAS Web Cache Administration and Deployment Guide.

Notes:

• When deploying Discoverer, you typically add the Discoverer components to an Oracle9iAS farm, and use Oracle9iAS Web Cache as a proxy server (for more information, see Section 5.1, "Installing Oracle9iAS Discoverer in a multiple machine environment").

9.3 What are the benefits of Oracle9iAS Web Cache?

Using Oracle9iAS Web Cache:

• improves performance

  Running on inexpensive hardware, Oracle9iAS Web Cache can increase the throughput of a Web site by several orders of magnitude. In addition, Oracle9iAS Web Cache significantly reduces response time to browser requests by storing documents in memory and by serving compressed versions of documents to browsers that support the GZIP encoding method.

• improves scalability

  In addition to unparalleled throughput, Oracle9iAS Web Cache can sustain thousands of concurrent browser connections, meaning that visitors to a site see fewer application Web server errors, even during periods of peak load.

• offers high availability

  Oracle9iAS Web Cache supports content-aware (Layer 4 - Layer 7) load balancing and fall-over detection. These features ensure that documents not in the cache (referred to as 'cache misses') are directed to the most available, highest-performing Web server in the cluster. Further features guarantee performance and provide surge protection when application Web server load increases.

• offers cost savings

  Fewer application Web servers are required to meet the challenges posed by traffic spikes and denial of service attacks. As a result, Oracle9iAS Web Cache offers a simple and inexpensive means of reducing a Web site's cost for each request.

• reduces network traffic

  Most requests are resolved by Oracle9iAS Web Cache, reducing traffic to the application Web servers. The cache also reduces traffic to backend databases located on computers other than the application Web server.

For more information about the benefits of using Oracle9iAS Web Cache, see Oracle9iAS Web Cache Administration and Deployment Guide.

9.4 How does Oracle9iAS Web Cache work?

Oracle9iAS Web Cache uses cacheability rules to determine which documents to cache. A cacheability rule indicates whether you want the documents specified within a particular URL to be cached or not cached. Cacheability rules are defined using regular expressions (for more information about Oracle's implementation of regular expressions, see Oracle9iAS Web Cache Administration and Deployment Guide).

The document specified within a URL included in a cacheability rule is not actually cached until a browser requests it.

Figure 9-3 The URL and document request process

Text description of the illustration webcacha.gif

Key to figure:

1. The first time a browser requests a particular URL, Oracle9iAS Web Cache detects that the required document is not in the cache (referred to as a cache miss). Oracle9iAS Web Cache therefore forwards the request to an application Web server, which sends the request to the database.

2. The database returns the data to the application Web server, which forwards a document and its URL to Oracle9iAS Web Cache. If the URL is specified as one of the URLs to cache, Oracle9iAS Web Cache caches the document for subsequent requests.

3. The next time a browser requests the URL, Oracle9iAS Web Cache detects that the document is already in the cache (referred to as a cache hit).

4. Oracle9iAS Web Cache serves the document from the cache to the browser.

9.5 When to use Discoverer Viewer with Oracle9iAS Web Cache

With Oracle9iAS Release 2, using Discoverer Viewer with Oracle9iAS Web Cache to improve Web site performance, scalability, and availability will be most appropriate in the following cases:

• web sites that only use public workbooks

• web sites where data is relatively static

• where the Discoverer manager and/or workbook creator has access to Oracle9iAS Web Cache and can refresh the cache after changes to workbooks

Oracle9iAS Web Cache is particularly suitable for optimizing Discoverer Viewer performance when controlling access to data is relatively unimportant (e.g. where the same public connections are used by several users to access workbooks). Oracle9iAS Web Cache is less suitable in restricted environments where controlling access to data is an issue (e.g. where private connections are used by individuals to access their own workbooks). If you are considering using Oracle9iAS Web Cache in a restricted environment, note that a malicious user might be able to access pages that have been cached for another user.

In Oracle9iAS Release 2, using Discoverer Viewer and Oracle9iAS Web Cache together requires a number of compromises, as follows:

• the removal of the following links from Discoverer Viewer:
  • the Preferences link, which enables users to configure how Discoverer Viewer behaves

  • the Presentation Options link, which enables users to change the appearance of Discoverer Viewer

• the inconsistent behavior of sticky worksheet functionality (for more information about sticky worksheet functionality, see Section 9.9, "How to turn off Discoverer Viewer's 'sticky worksheet' behavior")

• data synchronization issues might arise where cached data is not purged after changes in underlying database tables

Notes:

• For more information about Oracle9iAS Discoverer security in general, see Section 13.1, "Maintaining data security with Discoverer".

9.6 How to use Discoverer Viewer with Oracle9iAS Web Cache

To use Discoverer Viewer with Oracle9iAS Web Cache, you must perform the following configuration tasks:

• you must turn on Oracle9iAS Web Cache for Discoverer Viewer by editing the configuration.xml file (for more information, see Section 9.7, "How to turn on Oracle9iAS Web Cache for Discoverer Viewer").

• you must edit the ui_config.xml file to:
  • display the Rerun Query link, hide the Preferences link, and hide the Presentation Options link (for more information, see Section 9.8, "How to display the Rerun Query link, hide the Preferences link, and hide the Presentation Options link").

  • turn off Discoverer Viewer's 'sticky worksheet' behavior (for more information, see Section 9.9, "How to turn off Discoverer Viewer's 'sticky worksheet' behavior").

Having specified that you want to use Discoverer Viewer with Oracle9iAS Web Cache, you might want to perform the following maintenance tasks:

• you might want to remove files from the cache because workbook data has changed (for more information, see Section 9.10.1, "How to remove Discoverer Viewer documents from the cache")

• where you deploy multiple browsers with multiple languages, you might want to check that the correct language and rendered page is delivered to each user's browser (for more information, see Section 9.10.2, "How to check that the correct languages are being deployed")

• although Oracle9iAS Web Cache is pre-configured to use Discoverer Viewer's authentication mechanism, you might want to:
  • specify that multiple documents with the same URL can be cached (for more information, see Section 9.10.3.1, "How to specify that multiple documents with the same URL can be cached")

  • create a session/personalized attribute related caching rule (for more information, see Section 9.10.3.2, "How to create a session/personalized attribute related caching rule")

Notes:

• Oracle9iAS Web Cache cacheability rules are specifically pre-configured for Discoverer Viewer and automatically installed with Oracle9iAS Web Cache.

9.7 How to turn on Oracle9iAS Web Cache for Discoverer Viewer

Although Oracle9iAS Web Cache is installed with Oracle9iAS, it is turned off by default. To make use of Oracle9iAS Web Cache, you must turn it on.

To turn on Oracle9iAS Web Cache for Discoverer Viewer:

1. Open the configuration.xml file in an XML editor or text editor (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

2. Change the value of the 'webcache' attribute of the Discoverer configuration element from 'false' to 'true' (i.e. webcache="true").

   For example, after the change the configuration element might look like this:

   <disco:configuration xmlns:disco="http://oracle.com/xmlns/discoverer/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://oracle.com/xmlns/discoverer/configuration configuration.xsd" locale="en" webcache="true" rmi="true">

3. Save the configuration.xml file and close the text editor.

4. Shut down and restart OC4J (for more information, see Oracle9iAS Containers for J2EE (OC4J) User's Guide).

   Oracle9iAS Web Cache is now turned on.

9.8 How to display the Rerun Query link, hide the Preferences link, and hide the Presentation Options link

When you use Discoverer Viewer with Oracle9iAS Web Cache, you must modify the Discoverer Viewer user interface by:

• displaying the Rerun Query link

• hiding the Preferences link

• hiding the Presentation Options link

Figure 9-4 Discoverer Viewer showing Rerun Query link, Preferences link, and Presentation Options link

Text description of the illustration wc1.gif

Key to figure:

1. Rerun Query link

2. Preferences link

3. Presentation Options link

Removing these links prevents Discoverer Viewer end users accessing parts of the Discoverer Viewer user interface that interfere with Oracle9iAS Web Cache.

Notes:

• Displaying the Rerun Query link is recommended where data changes frequently and users will therefore want to execute a new server request instead of using cached data.

• Hiding the Preferences link and the Presentation Options link is recommended because Oracle9iAS Web Cache does not recognize changes in these values. Any such changes could therefore result in inconsistent workbook behavior and appearance.

To display and hide links:

1. Open the ui_config.xml file in a text editor (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

2. Locate the <appearance> tag in the file.

3. Change the value of the following <appearance> tags:
   • change the value of the display_rerun_query_link tag to true

   • change the value of the display_preferences_link tag to false

   • change the value of the display_presentation_options_link tag to false

   After the change the tags will look like this:

   .
   .
     <option id="display_rerun_query_link" state="true"/>
     <option id="display_preferences_link" state="false"/>
     <option id="display_presentation_options_link" state="false"/
   

4. Save and close the ui_config.file.

When end users next run Discoverer Viewer, the user interface will be updated accordingly.

9.9 How to turn off Discoverer Viewer's 'sticky worksheet' behavior

Discoverer Viewer enables worksheet drills and pivot operations to be remembered between worksheet visits in a single session. This functionality is sometimes referred to as Discoverer Viewer's 'sticky worksheet' behavior. Discoverer Viewer's sticky worksheet behavior is not supported when used with Oracle9iAS Web Cache. You must therefore turn off this behavior.

To turn off Discoverer Viewer's sticky worksheet behavior:

1. Open the ui_config.xml file in a text editor (for more information about the location of configuration files, see Section A.2, "List of Discoverer file locations").

2. Locate the <behavior> tag in the file.

3. Change the value of the sticky_worksheets tag true to false.

   After the change the element will look like this:

   .
   .
     <option id="sticky_worksheets" state="false"/>
   .
   .
   

4. Save and close the ui_config.file.

When end users next run Discoverer Viewer, the sticky worksheet behavior will be turned off.

9.10 Notes about using Discoverer Viewer with Oracle9iAS Web Cache

This section contains miscellaneous information about using Oracle9iAS Web Cache with Oracle9iAS Discoverer.

9.10.1 How to remove Discoverer Viewer documents from the cache

You might want to remove Discoverer Viewer cached documents for a number of reasons, including:

• because the data in a workbook has changed

• because a calculation shared by multiple workbooks has changed

To remove a Discoverer Viewer document from the cache:

1. If it is not already running, start Oracle9iAS Web Cache Manager and login.

   If you are not sure of the username and password to use, contact your Oracle9iAS system administrator.

2. Select the Content Invalidation link to display the Content Invalidation page.

3. In the Advanced Invalidation section:
   1. Type http://discoverer/ in the URL Path Prefix field.

   2. Enter an appropriate regular expression in the URL Regular expression field.

   The regular expression to enter will depend on the Discoverer Viewer document you want to remove from the cache. The table below gives some examples:

   URL regular expression	Description
   viewer	This will remove all cached Discoverer documents.
   viewer.+(wbk=X)	Where X is the name of the workbook. This will remove cached Discoverer documents that have X as the workbook name.
   viewer.+(eul=X)	Where X is the name of the EUL. This will remove cached Discoverer documents that have X as the EUL name.
   viewer.+(ac=X)	Where X is the account name. This will remove cached Discoverer documents that have X as the account name.
   viewer.+(nlsl=en-us)	This will remove all United States English cached documents.

4. Click the Submit button to clear the selected documents from the cache.

9.10.2 How to check that the correct languages are being deployed

If you are using multiple browsers with multiple languages, it is important that the correct language and rendered page is delivered to each user's browser.

To make sure that there are as many copies of a cached page based on the same URL as there are different browsers and languages, the Accept-Language and User-Agent Oracle9iAS Web Cache options are automatically selected for the Discoverer Viewer cacheability rules.

To confirm that these options are selected:

1. If it is not already running, start Oracle9iAS Web Cache Manager and login.

   Note: If you are not sure of the username and password to use, contact your Oracle9iAS system administrator.

2. Select the Cacheability Rules link.

3. Select the radio button beside the cacheability rule you want to verify.

4. Click the Edit... button to display the Edit Cacheability Rule page.

5. Confirm that the following check boxes in the Multiple Documents with Same URL by Other Headers section are selected:
   • Accept-Language

   • User-Agent

6. Click the Cancel button to close the Edit Cacheability Rule page.

9.10.3 How to prevent unauthorized users accessing cached pages

It is likely that Oracle9iAS Web Cache will cache HTML pages for different Discoverer Viewer users. To prevent unauthorized users accessing cached pages, Oracle9iAS Web Cache is pre-configured to use Discoverer Viewer's authentication mechanism, and requires no further configuration.

However, if you need to configure Oracle9iAS Web Cache manually, you follow a two step process:

• specify that multiple documents with the same URL can be cached (for more information, see Section 9.10.3.1, "How to specify that multiple documents with the same URL can be cached")

• create a session/personalized attribute related caching rule (for more information, see Section 9.10.3.2, "How to create a session/personalized attribute related caching rule")

9.10.3.1 How to specify that multiple documents with the same URL can be cached

To specify that multiple documents with the same URL can be cached:

1. If it is not already running, start Oracle9iAS Web Cache Manager and login.

   If you are not sure of the username and password to use, contact your Oracle9iAS system administrator.

2. Select the Multiple Documents with Same Selector by Cookies link to display the Multiple Documents with Same Selector by Cookies page.

3. Click the Add... button to display the Edit/Create Multiple Documents with the Same Selector by Cookies Rule page.

4. Type oracle-disco-account in the Enter cookie name: field as the name of the Discoverer Viewer cookie name.

5. Select the Yes radio button in response to the question Also cache documents whose requests do not contain this cookie?

6. Click the Submit button.

   You must now associate the Discoverer Viewer cookie with a 'selector' (cacheability rule).

7. Select the radio button beside the new entry in the Edit/Create Multiple Documents with the Same Selector by Cookies Rule page.

8. Click the Change Selector Association... button to display the Change Policy-Selector Association page.

9. From the list of selectors (cacheability rules), select all of the Discoverer selectors.

10. Click the Make Association button.

    The Edit/Create Multiple Documents with the Same Selector by Cookies Rule page now shows the cacheability rules you have associated with the Discoverer Viewer cookie.

11. Click the Apply changes button to save the changes you have made.

9.10.3.2 How to create a session/personalized attribute related caching rule

To create a session/personalized attribute related caching rule:

1. If it is not already running, start Oracle9iAS Web Cache Manager and login.

   If you are not sure of the username and password to use, contact your Oracle9iAS system administrator.

2. Select the Session/Personalized Attribute Definitions link to display the Session/Personalized Attribute Definitions page.

3. Click the Add... button to display the Create Session/Personalized Attribute Definition page.

4. Select the This site only radio button.

5. Type ViewerCookie in the Session/Attribute Name field.

6. Type oracle-disco-account in the Cookie Name field.

7. Type Oracle Discoverer Viewer authentication related cookie in the Comment field.

8. Click the Submit button to close the Create Session/Personalized Attribute Definition page.

9. Click the Apply Changes button to save the changes you have made.

10. Select the Session/Personalized Attribute Related Caching Rules link.

11. Click the Create button (or the Add button if one or more rules already exist) to display the Add Session/Personalized Attribute Related Caching Rule page.

12. Select options on the Add Session/Personalized Attribute Related Caching Rule page as follows:
    1. Select ViewerCookie in the Please select a session/attribute: drop down list.

    2. Select the Yes radio button in response to the question Cache documents whose requests contain this session/attribute?

    3. Select the Yes radio button in response to the question Cache documents whose requests do not contain this session/attribute?

    4. Select the Yes radio button in response to the question Can the document whose request doesn't contain this attribute be derived from the document whose request does contain this attribute by using the default value of the attribute?

13. Click the Submit button to close the Add Session/Personalized Attribute Related Caching Rule page.

    The Session/Personalized Attribute Related Caching Rules page displays the rule you have just created. You must now associate this rule with a URL.

14. Select the radio button beside the new entry in the Session/Personalized Attribute Related Caching Rules page.

15. Click the Change Selector Association... button to display the Change Policy-Selector Association page.

16. From the list of selectors (cacheability rules), select all of the Discoverer selectors.

17. Click the Make Association button.

    The Session/Personalized Attribute Related Caching Rules page now shows the cacheability rules you have associated with the Discoverer Viewer cookie.

18. Click the Apply changes button to save the changes you have made.

19. Restart Oracle9iAS Web Cache as follows:
    1. Click the Operations link to display the Operations page.

    2. Select the radio button beside the name of the cache that you want to restart.

    3. Click the Restart button.

9.10.4 List of the Oracle9iAS Web Cache cacheability rules that are pre-configured for Discoverer Viewer?

A number of Oracle9iAS Web Cache cacheability rules are pre-configured for Discoverer Viewer. These cacheability rules are processed by Oracle9iAS Web Cache in the following order:

• do not cache the Rerun Query page

• do not cache the Scheduled Workbooks page (and any workbooks derived from it)

• do not cache Discoverer Plus pages

• do not cache query pages containing cached query parameters

• do not cache query pages containing cached drill specifications

• do not cache RMI commands

• do cache all pages served by the Viewer servlet (i.e. pages that the previous cacheability rules have not identified as not to be cached)

Each cacheability rule comprises a regular expression. Oracle9iAS Web Cache evaluates each expression to a string, and tests whether a particular URL contains that string. If the URL does contain the string, Oracle9iAS Web Cache performs the actions specified by the cacheability rule (e.g. cache or do not cache the page). If the URL does not contain the string, Oracle9iAS Web Cache evaluates the expression in the next cacheability rule.

Notes:

• Cacheability rules are configured automatically when you install Oracle9iAS. The following cacheability rules are included for reference only. Do not change the Web Cache configuration unless explicitly advised to do so by Oracle Corporation.

9.10.4.1 Cacheability rule to not cache the Rerun Query page

If data changes frequently, Discoverer Viewer users will want to rerun queries to get the latest data. However, if Discoverer Viewer's Rerun Query page is cached, users will never see any additional or changed data.

This cacheability rule therefore forces the Rerun Query link to execute a new server request instead of using cached data.

Cacheability rule - discoverer\/viewer.+(qv=[0-9]+)

Rule Details	Value
Method	GET, GET with query string
POST Body Expression
Cache/Don't Cache	Don't Cache
ESI Output Permission	YES
Compression	On for non-Netscape browsers
Comment	This will not cache the ReRun query page

9.10.4.2 Cacheability rule to not cache the Scheduled Workbooks page (and any workbooks derived from it)

A Discoverer scheduled workbook contains data that is expected to change when the workbook is processed. However, if a scheduled workbook is cached, users will never see any additional or changed data.

This cacheability rule therefore prevents the caching of scheduled workbooks.

Cacheability rule - discoverer\/viewer.+in=swb

Rule Details	Value
Method	GET, GET with query string
POST Body Expression
Cache/Don't Cache	Don't Cache
ESI Output Permission	YES
Compression	On for non-Netscape browsers
Comment	This will not cache Scheduled Workbooks page or workbooks derived from it

9.10.4.3 Cacheability rule to not cache Discoverer Plus pages

This cacheability rule prevents the caching of the Discoverer Plus applet. Oracle9iAS Web Cache cannot be used with Discoverer Plus.

Cacheability rule - discoverer\/viewer. .release=true)

Rule Details	Value
Method	GET, GET with query string
POST Body Expression
Cache/Don't Cache	Don't Cache
ESI Output Permission	YES
Compression	On for non-Netscape browsers
Comment	This will not cache any page whose URL contains the Discoverer Plus parameter

9.10.4.4 Cacheability rule to not cache query pages containing cached query parameters

This cacheability rule prevents the caching of query pages containing servlet-side cached query parameters.

In some cases, a URL including parameters can exceed the maximum allowed length. In these cases, the parameters and their values are stored in the Discoverer servlet for the current session only. When the current session ends, the parameters and their values are discarded. Any cached pages that reference the stored parameters will be invalid.

Cacheability rule - discoverer\/viewer.+cqp=[0-9]+)

Rule Details	Value
Method	GET, GET with query string
POST Body Expression
Cache/Don't Cache	Don't Cache
ESI Output Permission	YES
Compression	On for non-Netscape browsers
Comment	Discoverer: do not cache query pages containing cached query parameters

9.10.4.5 Cacheability rule to not cache query pages containing cached drill specifications

This cacheability rule prevents the caching of query pages that contain cached drill specifications.

In some cases a URL including drill specifications can exceed the maximum allowed length. In these cases, the drill specifications are stored in the Discoverer servlet for the current session only. When the current session ends, the drill specifications are discarded. Any cached pages that reference the stored drill specifications will be invalid.

Cacheability rule - discoverer\/viewer.+cds=[0-9]+ yCacheability rule to not cache RMI commands

This cacheability rule prevents the caching of RMI commands issued by the Discoverer Plus applet. Oracle9iAS Web Cache cannot be used with Discoverer Plus.

Cacheability rule - discoverer\/viewer.+rmicmd=.+

Rule Details	Value
Method	GET, GET with query string
POST Body Expression
Cache/Don't Cache	Don't Cache
ESI Output Permission	YES
Compression	On for non-Netscape browsers
Comment	Discoverer: do not cache RMI commands

9.10.4.6 Cacheability rule to cache all pages served by the Viewer Servlet

This cacheability rule caches all Discoverer Viewer pages (i.e. pages that the previous cacheability rules have not identified as not to be cached).

Cacheability rule - discoverer\/viewer

Rule Details	Value
Method	GET, GET with query string
POST Body Expression
Cache/Don't Cache	Cache
Expiration Policy	Default: Never Expire
Multiple Documents with the Same Selector by Cookies*	Cache based on value of cookie "oracle-disco-account", also cache documents whose requests don't contain this cookie
Multiple Documents with the Same Selector by Other Headers*	Accept-Language, User-Agent
Session/Personalized Attribute Related Caching Rules	For session/attribute "ViewerCookie": cache documents whose requests contain this session, AND cache documents whose requests don't contain this session.
Simple Personalization	NO
HTTP Error Caching
ESI Output Permission	YES
Compression	On for non-Netscape browsers
Comment	Caches all pages served by the Viewer servlet

* For more information about this option, see Section 9.10.3, "How to prevent unauthorized users accessing cached pages".