8
Administering Oracle9iAS Web Cache

This chapter explains how to perform administrative tasks to Oracle9iAS Web Cache.

This chapter contains these topics:

• Starting and Stopping Oracle9iAS Web Cache

• Propagating Configuration Changes to Cache Cluster Members

• Invalidating Documents in the Cache

• Listing the Contents of the Cache

• Evaluating Event Logs

• Evaluating Access Logs

Starting and Stopping Oracle9iAS Web Cache

Anytime Oracle9iAS Web Cache's configuration is modified, you must stop and restart Oracle9iAS Web Cache. To start, stop, or restart Oracle9iAS Web Cache, use either Oracle9iAS Web Cache Manager or the webcachectl utility.

When you stop Oracle9iAS Web Cache, all objects are cleared from the cache. In addition, all statistics are cleared.

When you start Oracle9iAS Web Cache from the webcachectl utility, the admin server process, cache server process, and, if enabled, auto-restart process start.

• The admin server process manages the Oracle9iAS Web Cache Manager interface

  On Windows, the admin server process is represented by the OracleHOME_NAMEWebCacheAdmin service

• The cache server process to manage the cache

  On Windows, the cache server process is represented by the OracleHOME_NAMEWebCache service

• If enabled, the auto-restart process checks that the cache server process is running and automatically restarts the cache server process if it is not running

  Because the auto-restart process is dependent upon the cache server process, you administer it by starting, stopping, or restarting the cache server process.

  On Windows, the auto-restart process is represented by the OracleHOME_NAMEWebCacheMon service

  See Also: "Task 6: Configure Auto-Restart Process Settings" for instructions on enabling the OracleHOME_NAMEWebCacheMon service

When you start Oracle9iAS Web Cache from the Oracle9iAS Web Cache Manager, only the cache server process and, if enabled, the auto-restart process start. To initialize Oracle9iAS Web Cache for the first time, use the webcachectl utility to start all the processes.

To start, stop, or restart the processes:

webcachectl stop

webcachectl restart

On Windows, you can start or stop Oracle9iAS Web Cache through the Control Panel:

1. Select the Services icon in the Control Panel window.

   The Services window appears.

2. Select the OracleHOME_NAMEWebCacheAdmin service to start the admin server process, and then choose Start or Stop.

3. Select the OracleHOME_NAMEWebCache service to start the cache server process, and then choose Start or Stop.

   The OracleHOME_NAMEWebCache service also starts or stops the OracleHOME_NAMEWebCacheMon service, if it is enabled. You cannot select the OracleHOME_NAMEWebCacheMon service and start or stop it. It is dependent on the OracleHOME_NAMEWebCache service.

4. In the Services window, choose Close.

Propagating Configuration Changes to Cache Cluster Members

If you have made changes to the configuration of a cache cluster or if a cache cluster member is unreachable when Oracle9iAS Web Cache tries to propagate the configuration to it, you must propagate the configuration to that cluster member when it is reachable again. Then, you must restart the cache.

Oracle9iAS Web Cache keeps track of the configuration of all cluster members to ensure that all cluster members are using the same version of the configuration. It compares the configuration of the current cache (the cache to which you are connected) to that of the other cluster members.

To check that all cluster members are using the same configuration and to propagate the configuration, if necessary, perform following steps:

1. In the navigation pane, select Administration > Operations.

   The Operations page appears.

2. In the Operation Needed column of the table, check whether or not Propagate Configuration is noted for any cluster member.

   Propagate Configuration means that the configuration of the cluster member is different than the configuration of the current cache. You should verify that the configuration of the current cache is the most valid configuration before proceeding with propagation.

   If it is not, connect to the cache with the valid configuration and view the Operations page.

3. For each cluster member that needs the configuration propagated, select the cache. Then, in the Operate On field, choose Selected cache and choose Propagate. (Alternatively, to operate on all caches in the cluster, in the Operate On field, choose All caches and specify an interval to stagger the times of the operations, and then choose Propagate.)

   Oracle9iAS Web Cache propagates the configuration from the current cache to the selected cluster member. When the operation completes, the Operation Needed column in the Operations page indicates that the cache needs to be restarted.

4. To restart one cluster member:
   1. Select the cache.

   2. In the Operate On field, choose Selected cache and choose Restart. (Alternatively, to operate on all caches in the cluster, in the Operate On field, choose All caches and specify an interval to stagger the times of the operations, and then choose Restart.)

Invalidating Documents in the Cache

To invalidate documents in the cache, send an HTTP POST message from the invalidator user through an invalidation listening port.

The invalidator user is an administrator authorized to send invalidation messages. In a cache hierarchy of Oracle9iAS Web Cache servers, the central cache or provider cache uses the invalidator user name and password of the remote or subscriber Oracle9iAS Web Cache server. The invalidation request specifies the documents to invalidate, as well as the site host name of the documents.

This section contains the following invalidation-related topics:

• Sending Invalidation Requests

• Invalidation Examples

  See Also: "Invalidation in Hierarchies"

Sending Invalidation Requests

Invalidation requests are HTTP POST requests written in Extensible Markup Language (XML) syntax. The contents of the XML request body instructs the cache which URLs to mark as invalid. As shown in Figure 8-1, invalidation requests can be sent using one of the following methods:

• Manually, using either Oracle9iAS Web Cache Manager or telnet

• Automatically, using database triggers, scripts, or application logic

Figure 8-1 Invalidation

This section describes how to send invalidation requests using one of the following methods:

• Manual Invalidation Using Telnet

• Manual Invalidation Using Oracle9iAS Web Cache Manager

• Automatic Invalidation Using Applications

• Automatic Invalidation Using Database Triggers

• Automatic Invalidation Using Scripts

Manual Invalidation Using Telnet

When you send an invalidation request with an HTTP POST request, you specify the host name of Oracle9iAS Web Cache, the invalidation listening port number, and the invalidation request.

For example, if you were using telnet, you would send an invalidation request using the following procedure:

1. Connect to Oracle9iAS Web Cache at the invalidation listening port:

   telnet web_cache_host invalidation_port
   
   

2. Specify a POST message header and authenticate the invalidator user using Base64 encoding string with the following syntax.

   POST /x-oracle-cache-invalidate http/1.0|1
   Authorization: BASIC <base64 encoding of invalidator:invalidator_password> 
   content-length:#bytes
   
   

   An example of Authorization: BASIC <base64 encoding of invalidator:invalidator_password> follows:

   Authorization: BASIC aW52YWxpZGF0b3I6YWRtaW4= 
   
   

   In this example, aW52YWxpZGF0b3I6YWRtaW4= is "invalidator:admin" encoded.

   See Also: http://rfc.net/rfc1421.html for information about password Base64 encoding readme.examples.html in the $ORACLE_HOME/webcache/examples directory on UNIX and ORACLE_HOME\webcache\examples directory on Windows for further information about using the EncodeBase64.java script to generate the Base64 string for invalidator:invalidator_password "Task 2: Modify Security Settings" for further information about changing the invalidation password

3. Enter one carriage return.

4. Send the invalidation request with XML syntax.

Invalidation request syntax is described in the following sections:

• Invalidation Request Syntax

• Invalidation Preview Request Syntax

• Invalidation Response Syntax

• Invalidation Preview Response Syntax

Invalidation Request Syntax

Use the following syntax to invalidate documents contained within an exact URL that includes the complete path and file name:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
   <SYSTEM>
    <SYSTEMINFO NAME="name" VALUE="value"/>
   </SYSTEM>  
   <OBJECT>
     <BASICSELECTOR URI="URL"/>
     <ACTION REMOVALTTL="TTL"/>
     <INFO VALUE="value"/>
   </OBJECT>
</INVALIDATION>

Use the following syntax to invalidate documents based on more advanced invalidation selectors:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
   <SYSTEM>
    <SYSTEMINFO NAME="name" VALUE="value"/>
   </SYSTEM>  
   <OBJECT>
     <ADVANCEDSELECTOR URIPREFIX="prefix"
                      URIEXP="URL_expression"
                      HOST="host_name:port"
                      METHOD="HTTP_request_method"
                      BODYEXP="HTTP_body"/>
      <COOKIE NAME="cookie_name" VALUE="value"/>
      <HEADER NAME="HTTP_request_header" VALUE="value"/>
      <OTHER NAME="URI|BODY|QUERYSTRING_PARAMETER" TYPE="SUBSTRING|REGEX"
       VALUE="value"/>
     </ADVANCEDSELECTOR>
     <ACTION REMOVALTTL="TTL"/>
     <INFO VALUE="value"/>
   </OBJECT>
</INVALIDATION>

The body of a valid invalidation request must begin with the following:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">

The first line denotes version 1.0 of XML. The second line denotes the request is an invalidation request using the WCSinvalidation.dtd file as the XML document type. WCSinvalidation.dtd is the Document Type Definition (DTD) that defines the grammar of invalidation requests and responses.

The root element INVALIDATION contains one or more of the attributes and elements described in Table 8-1.

Table 8-1  INVALIDATION Elements and Attributes

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///invalidation.dtd">
<INVALIDATION>
   <URL EXP="URL" PREFIX="YES|NO">
               <VALIDITY LEVEL="validity" REFRESHTIME="seconds"/>
               <COOKIE NAME="cookie_name" VALUE="value" 
NONEXIST="YES|NO"/>
               <HEADER NAME="HTTP_request_header" VALUE="value"/>
   </URL>
</INVALIDATION>

Invalidation Preview Request Syntax

To test invalidation, use the following syntax to preview the list of BASICSELECTOR documents to be invalidated:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATIONPREVIEW SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONPREVIEW VERSION="WCS-1.1" STARTNUM="start_number" MAXNUM="max_
number">
     <BASICSELECTOR URI="URL"/>
</INVALIDATION>

Use the following syntax to preview the list of ADVANCEDSELECTOR documents to be invalidated:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATIONPREVIEW SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONPREVIEW VERSION="WCS-1.1" STARTNUM="start_number" MAXNUM="max_
number">
    <ADVANCEDSELECTOR URIPREFIX="prefix"
                      URIEXP="URL_expression"
                      HOST="host_name:port"
                      METHOD="HTTP_request_method"
                      BODYEXP="HTTP_body"
      <COOKIE NAME="cookie_name" VALUE="value"/>
      <HEADER NAME="HTTP_request_header" VALUE="value"/>
      <OTHER NAME="URI|BODY|QUERYSTRING_PARAMETER" TYPE="SUBSTRING|REGEX"
       VALUE="value"/>
    </ADVANCEDSELECTOR>
</INVALIDATION>

The body of a valid invalidation preview request must begin with the following:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATIONPREVIEW SYSTEM "internal:///WCSinvalidation.dtd">

The first line denotes version 1.0 of XML. The second line denotes the request is an invalidation preview request using the WCSinvalidation.dtd file as the XML document type.

The root element INVALIDATIONPREVIEW contains one or more of the attributes described in Table 8-2. BASICSELECTOR and ADVANCEDSELECTOR are described in Table 8-1.

Table 8-2  INVALIDATIONPREVIEW Attributes

Invalidation Response Syntax

Invalidation responses are returned in the following format for BASICSELECTOR invalidation requests:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <SYSTEM>
     <SYSTEMINFO NAME="name" VALUE="value"/>
   </SYSTEM>  
   <OBJECTRESULT>
     <BASICSELECTOR URI="URL">
     </BASICSELECTOR>
     <RESULT ID="ID" STATUS="status" NUMINV="number"/>
     <INFO VALUE="value"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

Invalidation responses are returned in the following format for ADVANCEDSELECTOR invalidation requests:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <SYSTEM>
     <SYSTEMINFO NAME="name" VALUE="value"/>
   </SYSTEM>  
   <OBJECTRESULT>
    <ADVANCEDSELECTOR URIPREFIX="prefix"
                      URIEXP="URL_expression"
                      HOST="host_name:port"
                      METHOD="HTTP_request_method"
                      BODYEXP="HTTP_body"/>
      <COOKIE NAME="cookie_name" VALUE="value"/>
      <HEADER NAME="HTTP_request_header" VALUE="value"/>
      <OTHER NAME="URI|BODY|QUERYSTRING_PARAMETER" TYPE="SUBSTRING|REGEX"
       VALUE="value"/>
     </ADVANCEDSELECTOR>
     <RESULT ID="ID" STATUS="status" NUMINV="number"/>
     <INFO VALUE="value"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

The body of a valid invalidation response begins with the following:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">

The first line denotes version 1.0 of XML. The second line denotes the response is an invalidation response using the WCSinvalidation.dtd file as the XML document type.

The root element INVALIDATIONRESULT contains one or more of the attributes and elements described in Table 8-3. BASICSELECTOR and ADVANCEDSELECTOR are described in Table 8-1.

Table 8-3  INVALIDATIONRESULT Elements and Attributes

Invalidation Preview Response Syntax

Invalidation preview responses for preview requests are returned in the following format:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONPREVIEWRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONPREVIEWRESULT VERSION="WCS-1.1" STATUS="status" NUMURLS="number" 
TOTALNUMURLS="total_number">
   <SELECTURL VALUE="URL">
   </SELECTEDURL>
</INVALIDATIONPREVIEWRESULT>

The body of a valid invalidation preview response begins with the following:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONPREVIEWRESULT SYSTEM "internal:///WCSinvalidation.dtd">

The first line denotes version 1.0 of XML. The second line denotes the response is an invalidation preview response using the WCSinvalidation.dtd file as the XML document type.

The root element INVALIDATIONPREVIEWRESULT contains one or more of the attributes and elements described in Table 8-4. BASICSELECTOR and ADVANCEDSELECTOR are described in Table 8-1.

Table 8-4  INVALIDATIONPREVIEWRESULT Elements and Attributes

Manual Invalidation Using Oracle9iAS Web Cache Manager

Oracle9iAS Web Cache Manager provides an easy-to-use interface for invalidating cached objects. The message mechanics are much like the telnet example. The advantage of using Oracle9iAS Web Cache Manager is that the administrator is isolated from the intricacies of the HTTP and XML formats, and consequently, there is less chance for error. The administrator need only specify which objects to invalidate and how invalid those objects should be.

To invalidate documents with Oracle9iAS Web Cache Manager:

1. Start Oracle9iAS Web Cache Manager.

   See Also: "Starting Oracle9iAS Web Cache Manager"

2. In the navigator pane, select Administration > Content Invalidation.

   The Content Invalidation page appears in the right pane.

3. From the For Cache list, select a cache. (More than one cache is listed only if you configured a cache cluster.)

4. Specify which documents to invalidate:

   Note: When using Oracle9iAS Web Cache Manager, the following characters are permitted in the Enter exact URL for removal, URL Path Prefix, and URL Regular Expression fields: ampersand (&), greater than sign (>), less than sign (<), double quotes ("), and single quotes (').

   Basic Invalidation
   Remove all cached documents.	Select to remove all documents from the cache.
   Enter exact URL for removal	Specify the URL of the documents to be invalidated. Include the complete path and file name.
   Advanced Invalidation
   URL Path Prefix	Required. Specify the prefix path of the documents to be invalidated. The prefix path must begin with http|https://host_name:port/path/filename or with "/" and end with "/". host_name:port is optional. You can also specify the site host name and port in the Host Name field. The prefix is interpreted literally, including reserved regular expression characters. These characters include periods (.), question marks (?), asterisks (*), brackets ([]), curly braces ({}), carets (^), dollar signs ($), and backslashes (\).
   URL Regular Expression	Optional. Specify the URL of the documents to be invalidated underneath the URL Path Prefix. If no value is entered, then everything under the URL Path Prefix will be matched. Regular expression characters are permitted. To interpret these characters literally, escape them with a backslash (\).
   Host Name	Optional. Specify the host name and port number of the site (host_name:port). Port 80 is the default port for HTTP and port 443 is the default port for HTTPS. This field is required if the URL Path Prefix does not include http:https://host_name:port/path/filename.
   HTTP Method	Optional. Select the HTTP request method (GET or POST) of the documents to be invalidated.
   POST Body Expression	Optional. If POST is selected for the HTTP Method, enter the HTTP body of the documents to be invalidated.
   Cookie Information	Optional. Enter the cookie name for the documents to be invalidated in the Name field, and enter its value in the Value field.
   Header Information	Optional. Enter the HTTP request header for the documents to be invalidated in the Name field, and enter its value in the Value field. The name must match the header associated with a cacheability rule associated for the URL.

5. Optionally, you can preview the list of documents to be invalidated to ensure that you are removing only the documents you want to remove.

   To preview the list of documents:

   1. In the Action section, choose Preview list of documents to be removed.

   2. Specify the Document Range:

      Start number

      Enter the number representing the first document to be listed. Oracle9iAS Web Cache begins the count of documents with the number 0.

      Maximum number of documents to be listed

      Enter the number of documents to be listed. If fewer documents than the number specified meet the invalidation criteria, then Oracle9iAS Web Cache lists the URLs for only those documents that meet the criteria. If more documents than the number specified meet the invalidation criteria, then Oracle9iAS Web Cache lists the URLs for the number of documents requested. It also returns the total number of documents that meet the invalidation criteria.

   3. Choose Submit.

      Oracle9iAS Web Cache displays the Invalidation Preview Results message box, which lists the documents that meet the invalidation criteria. Oracle9iAS Web Cache Manager lists only those documents that are valid. Although the cache may contain documents that are expired or that have been invalidated, those documents are not listed.

      If the documents listed are those that you want to invalidate, then continue with the next step. If they are not, then modify the invalidation criteria and preview the list again.

6. In the Action section, specify how to process invalid documents.

   Remove immediately	Select this option to have Oracle9iAS Web Cache mark documents as invalid and then remove them immediately. A document is refreshed from the application Web server when the cache receives the next request for it.
   Refresh on demand as application Web server capacity permits AND no later than <time> after submission	Select this option to have Oracle9iAS Web Cache mark documents as invalid and then refresh them based on application Web server capacity. Enter the maximum time in which the documents can reside in the cache.

   Note: Performance assurance heuristics apply when you configure documents to be refreshed based on when the application Web servers can refresh them; performance assurance heuristics do not apply when documents are immediately removed.

7. Choose Submit.

Oracle9iAS Web Cache processes the invalidation request, and returns a Cache Cleanup dialog box that the shows the invalidation status and the number of objects invalidated. For example:

Text description of the illustration invalid.gif

For prefix-based invalidations that require Oracle9iAS Web Cache to traverse a complex directory structure, invalidation can take some time. Therefore, do not choose Submit again until the Cache Cleanup Result dialog box appears. Creating a queue of invalidation requests can degrade the performance of Oracle9iAS Web Cache.

In a cache cluster environment, if Propagate Invalidation is enabled, Oracle9iAS Web Cache sends the invalidation requests to one cluster member who acts as the invalidation coordinator. The coordinator propagates the invalidation requests to other cluster members. When the invalidation has been completed for all cluster members, Oracle9iAS Web Cache returns a Cache Cleanup box, that lists, for each cluster member, the cache name, the status of the invalidation request, and the number of objects invalidated.

Automatic Invalidation Using Applications

Invalidation requests can originate from a Web site's underlying application logic or from the content management application used to design Web pages.

Oracle9iAS Web Cache ships with the following Application Program Interfaces (APIs) that you can implement:

• jawc.jar for a Java invalidation API

  jawc.jar is located in the $ORACLE_HOME/webcache/jlib directory on UNIX and ORACLE_HOME\webcache\jlib directory on Windows

• wxvutil.sql and wxvappl.sql for a PL/SQL invalidation API

  wxvutil.sql and wxvappl.sql are located in the $ORACLE_HOME/webcache/examples directory on UNIX and ORACLE_HOME\webcache\examples directory on Windows

  See Also: Invalidation API Reference (Javadoc) in the documentation library readme.examples.html in the $ORACLE_HOME/webcache/examples directory on UNIX and ORACLE_HOME\webcache\examples directory on Windows for further information about wxvutil.sql and wxvappl.sql

Oracle9iAS Web Cache also ships with the following sample code for generating invalidation requests. You can create invalidation tools following these examples and use them with your applications.

• Invalidate.java for Java source

• invalidate.c for C source

• invalidate.sh for a shell script that invalidates documents with a telnet session

• invalidate.sql for PL/SQL source

These files are located in the $ORACLE_HOME/webcache/examples directory on UNIX and ORACLE_HOME\webcache\examples directory on Windows.

Automatic Invalidation Using Database Triggers

Database triggers are procedures that are stored in the database and activated ("fired") when specific conditions occur, such as adding a row to a table. You can use triggers to send invalidation requests. To do this, use the UTL_TCP Oracle supplied package to send invalidation requests through database triggers.

Automatic Invalidation Using Scripts

Many Web sites use scripts for uploading new content to databases and file systems. A large online book retailer, for instance, might run a PERL script once a day in order to bulk load new book listings and price changes into its catalog database. The retailer would want the price changes and availability listings to be reflected in the item views and search results currently cached in Oracle9iAS Web Cache. To achieve this, the PERL script can be modified such that when the bulk loading operation has completed, the script will send an invalidation request to the cache invalidating all catalog views and search results. (Note that the invalidation request need not list every individual search page or item view that might be effected by the data change.) The performance assurance feature of Oracle9iAS Web Cache enables administrators to use broad brush strokes when invalidating content, making it safe to invalidate all catalog content even if only a fraction of that content has changed.

Invalidation Examples

This section contains the following invalidation request examples:

• Example: Invalidating One Document

• Example: Invalidating Multiple Objects

• Example: Invalidating a Subtree of Documents

• Example: Invalidating All Documents for a Web Site

• Example: Invalidating Documents with the Prefix

• Example: Invalidating Documents Using Substring and Query String Matching

• Example: Propagating Invalidation Requests Throughout a Cache Cluster

• Example: Previewing Invalidation

The examples in this section require utilizing the POST method which also requires sending the number of bytes (or characters) in the content_length: #bytes portion of the header. Please note that one carriage return is required after the content_length: #bytes line and before the XML request or BODY information.

Example: Invalidating One Document

The following request invalidates the file /images/logo.gif:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
   <OBJECT>
     <BASICSELECTOR URI="http://www.company.com:80/images/logo.gif"/>
     <ACTION/>
   </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.1">
   <OBJECTRESULT>
     <BASICSELECTOR URI="http://www.company.com:80/images/logo.gif"/>
     <RESULT ID="1" STATUS="SUCCESS" NUMINV="1"/>
     </OBJECTRESULT>
</INVALIDATIONRESULT>

The following request invalidates a document exactly matching /contacts/contacts.html using the BASICSELECTOR element:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
  <OBJECT>
    <BASICSELECTOR URI="http://www.company.com:80/contacts/contacts.html"/>
    <ACTION REMOVALTTL="0"/>
  </OBJECT>
</INVALIDATION>
    

This is equivalent to the following request using the ADVANCEDSELECTOR element. This request specifies the site information in the HOST attribute.

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/contacts/" URIEXP="^/contacts/contacts\.html$" 
HOST="www.company.com:80"/>
    <ACTION REMOVALTTL="0"/>
  </OBJECT>
</INVALIDATION>

The second request specifies the site information in the URIPREFIX attribute

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="http://www.company.com/contacts/" 
URIEXP="^/contacts/contacts\.html$"/>
    <ACTION REMOVALTTL="0"/>
  </OBJECT>
</INVALIDATION>
    

The ADVANCEDSELECTOR element uses the URIPREFIX attribute. This attribute is used to traverse the directory structure. The quicker invalidation reaches the right tree level, the quicker the invalidation process is done. The request with the BASICSELECTOR element is the more efficient of the two examples because there is no directory structure traversal involved.

Example: Invalidating Multiple Objects

The following request invalidates two different objects, summary.jsp and summary.gif. In addition, the request provides the comments "summary.jsp" and "summary.jsp" to be included in the invalidation result and event log.

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/global/sales/" URIEXP="summary.jsp\?year=2001" 
HOST="www.company.com:80"/>
      <COOKIE NAME="group" VALUE="asia"/>
    </ADVANCEDSELECTOR>
    <ACTION />
    <INFO VALUE="summary.jsp"/>
  </OBJECT>
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/image/" URIEXP="summary.*\.gif$" 
HOST="www.company.com:80"/>
    <INFO VALUE="summary.gif"/>
    <ACTION />
  </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
  <OBJECTRESULT>
    <ADVANCEDSELECTOR URIPREFIX="/global/sales/" URIEXP="summary.jsp\?year=2001" 
HOST="www.company.com:80"/>
      <COOKIE  NAME="group"  VALUE="asia"  />
    </ADVANCEDSELECTOR>
    <RESULT ID="1" STATUS="SUCCESS" NUMINV="2"/>
    <INFO VALUE="summary.jsp"/>
  </OBJECTRESULT>
  <OBJECTRESULT>
    <ADVANCEDSELECTOR URIPREFIX="/image/" URIEXP="summary.*\.gif$" 
HOST="www.company.com:80"/>
    </ADVANCEDSELECTOR>
    <RESULT ID="2" STATUS="SUCCESS" NUMINV="14"/>
    <INFO VALUE="summary.gif"/>
  </OBJECTRESULT>
</INVALIDATIONRESULT>

The following messages are written to the event log:

01/Oct/2001:23:51:48 +0000 -- Information: <Invalidation>Invalidation with info 
'summary.jsp' has returned with status 'SUCCESS'; number of documents 
invalidated: '2'.
.
.
.
01/Oct/2001:23:51:48 +0000 -- Information: <Invalidation>Invalidation with info 
'summary.gif' has returned with status 'SUCCESS'; number of documents 
invalidated: '14'.

Example: Invalidating a Subtree of Documents

The following request invalidates all documents under the /images/ directory:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
   <OBJECT>
     <ADVANCEDSELECTOR URIPREFIX="/images/" HOST="www.company.com:80"/>
     <ACTION REMOVALTTL="0"/>
   </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/images/" HOST="www.company.com:80"/>
     <RESULT ID="1" STATUS="SUCCESS" NUMINV="125"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

The following request invalidates all documents under the /contacts/ directory whose file names end in .html and uses cookie name cust with a value of oracle:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/contacts/" URIEXP="\.html$" 
HOST="www.company.com:80"/>
      <COOKIE NAME="cust" VALUE="oracle"/>
    </ADVANCEDSELECTOR>
    <ACTION REMOVALTTL="0"/>
  </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/contacts"/> URIEXP="\.html$" 
HOST="www.company.com:80"/>
      <COOKIE NAME="cust" VALUE="oracle"/>
     </ADVANCEDSELECTOR>
      <RESULT ID="1" STATUS="SUCCESS" NUMINV="45"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

Example: Invalidating All Documents for a Web Site

The following request invalidates all documents under /.

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.0">
   <OBJECT>
     <ADVANCEDSELECTOR URIPREFIX="/" HOST="www.company.com:80"/>
     <ACTION REMOVALTTL="0"/>
   </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/" HOST="www.company.com:80"/>
      <RESULT ID="1" STATUS="SUCCESS" NUMINV="17"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

Example: Invalidating Documents with the Prefix

To better understand the relationship of the URIPREFIX and URIEXP attributes, consider the examples that follow.

The following syntax invalidates sample.gif files within the /cec/cstage/graphic* directories:

<ADVANCEDSELECTOR URIPREFIX="/cec/cstage/"
   URIEXP="graphic.*/sample\.gif">
</ADVANCEDSELECTOR>

Note that ".*" in "graphic.*/sample\.gif" are regular expression characters that match all directories starting with graphic. The "." in "sample\.gif" is escaped for a literal interpretation.

The following syntax instructs Oracle9iAS Web Cache to locate a directory named graphic*:

<ADVANCEDSELECTOR URIPREFIX="/cec/cstage/graphic*/" URIEXP="sample\.gif" 
HOST="www.company.com:80"/>
</ADVANCEDSELECTOR>

The following syntax invalidates documents contained within /cec/cstage?ecaction=viewitem:

<ADVANCEDSELECTOR URIPREFIX="/cec/" URIEXP="cstage\?ecaction=viewitem" 
HOST="www.company.com:80"/>
</ADVANCEDSELECTOR>

Note that "?" is escaped with a backslash.

URLs such as /cec/cstage?ecaction=viewitem&zip=94405 and /cec/cstage?ecaction=viewitem&zip=94305 match and are invalidated, but /usa/cec/cstage?ecaction=viewitem&zip=94209 does not match and is not invalidated.

Example: Invalidating Documents Using Substring and Query String Matching

The following request invalidates all documents under / matching the substrings /post/ and htm. In addition, the request provides the comment "remove-htm-under-all-post-dir" to be included in the invalidation result and event log.

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/"
                      HOST="www.company.com:80">
      <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="/post/"/>
      <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="htm"/>
    </ADVANCEDSELECTOR>
    <ACTION REMOVALTTL="0" />
    <INFO VALUE="remove-htm-under-all-post-dir"/>
  </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/" HOST="www.company.com:80"/>
       <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="/post/"/>
       <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="htm"/>      
      <RESULT ID="1" STATUS="SUCCESS" NUMINV="52"/>
      <INFO VALUE="remove-htm-under-all-post-dir"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

The following message is written to the event log:

01/Oct/2001:23:51:48 +0000 -- Information: <Invalidation>Invalidation with info 
'remove-htm-under-all-post-dir' has returned with status 'SUCCESS'; number of 
documents invalidated: '52'.

The following request invalidates all documents under /corporate/asp/, matching the substring /view_building.asp/ and the embedded URL parameter value pairs of building=8 and floor=10. In addition, the request provides the comment "remove-view-building8-10th-floor" to be included in the invalidation result and event log.

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
  <OBJECT>
    <ADVANCEDSELECTOR URIPREFIX="/corporate/asp/"
                      HOST="www.company.com:80">
      <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="/view_building.asp"/>
      <OTHER NAME="QUERYSTRING_PARAMETER" TYPE="SUBSTRING" VALUE="building=8"/>
      <OTHER NAME="QUERYSTRING_PARAMETER" TYPE="SUBSTRING" VALUE="floor=10"/>
    </ADVANCEDSELECTOR>
    <ACTION REMOVALTTL="0" />
    <INFO VALUE="remove-view-building8-10th-floor"/>
  </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULT VERSION="WCS-1.0">
   <OBJECTRESULT>
     <ADVANCEDSELECTOR URIPREFIX="/" HOST="www.company.com:80"/>
       <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="/view_building.asp"/>
       <OTHER NAME="QUERYSTRING_PARAMETER" TYPE="SUBSTRING" VALUE="building=8"/>
       <OTHER NAME="QUERYSTRING_PARAMETER" TYPE="SUBSTRING" VALUE="floor=10"/>     
      <RESULT ID="1" STATUS="SUCCESS" NUMINV="3"/>
      <INFO VALUE="remove-view-building8-10th-floor"/>
   </OBJECTRESULT>
</INVALIDATIONRESULT>

The following message is written to the event log:

01/Oct/2001:23:51:48 +0000 -- Information: <Invalidation>Invalidation with info 
'remove-view-building8-10th-floor' has returned with status 'SUCCESS'; number of 
documents invalidated: '3'.

Example: Propagating Invalidation Requests Throughout a Cache Cluster

In a cache cluster, you can enable or disable the propagation of invalidation requests to all cluster members. You specify the setting on the Cluster Configuration page (Administration > Cluster Configuration) of Oracle9iAS Web Cache Manager.

You can override the setting by using a pair of name/value attributes of the SYSTEMINFO element. If NAME is set to WCS_PROPAGATE and VALUE is set to TRUE, it overrides the setting specified in Oracle9iAS Web Cache Manager. If NAME is set to WCS_PROPAGATE and VALUE is set to FALSE, then it reads the setting specified in Oracle9iAS Web Cache Manager.

The following request invalidates the file /images/logo.gif and propagates the request to all cluster members. In this example, there are three cluster members:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATION VERSION="WCS-1.1">
   <SYSTEM>
      <SYSTEMINFO NAME="WCS_PROPAGATE" VALUE="TRUE"/>
   </SYSTEM>
   <OBJECT>
     <BASICSELECTOR URI="/hostname:port/images/logo.gif"/>
     <ACTION/>
   </OBJECT>
</INVALIDATION>

Invalidation response:

<?xml version="1.0"?> 
<!DOCTYPE INVALIDATIONRESULTDETAIL SYSTEM "internal:///WCSinvalidation.dtd">
<INVALIDATIONRESULTDETAIL VERSION="WCS-1.1">
  <INVALIDATIONRESULT VERSION="WCS-1.1">
     <SYSTEM>
       <SYSTEMINFO NAME="WCS_CACHE_NAME" VALUE="Cache_A"/>
     </SYSTEM>
     <OBJECTRESULT>
       <BASICSELECTOR URI="http://www.company.com:80/images/logo.gif"/>
       <RESULT ID="1" STATUS="SUCCESS" NUMINV="1"/>
     </OBJECTRESULT>
  </INVALIDATIONRESULT>
  <INVALIDATIONRESULT VERSION="WCS-1.1">
     <SYSTEM>
       <SYSTEMINFO NAME="WCS_CACHE_NAME" VALUE="Cache_B"/>
     </SYSTEM>
     <OBJECTRESULT>
       <BASICSELECTOR URI="http://www.company.com:80/images/logo.gif"/>
       <RESULT ID="1" STATUS="SUCCESS" NUMINV="1"/>
     </OBJECTRESULT>
  </INVALIDATIONRESULT>
  <INVALIDATIONRESULT VERSION="WCS-1.1">
     <SYSTEM>
       <SYSTEMINFO NAME="WCS_CACHE_NAME" VALUE="Cache_C"/>
     </SYSTEM>
     <OBJECTRESULT>
       <BASICSELECTOR URI="http://www.company.com:80/images/logo.gif"/>
       <RESULT ID="1" STATUS="SUCCESS" NUMINV="1"/>
     </OBJECTRESULT>
  </INVALIDATIONRESULT>
</INVALIDATIONRESULTDETAIL>

Example: Previewing Invalidation

The following request previews up to 50 documents ending in *.htm:

<?xml version="1.0"?>
<!DOCTYPE INVALIDATIONPREVIEW SYSTEM
"internal:///WCSinvalidation.dtd">
<INVALIDATIONPREVIEW VERSION="WCS-1.1" STARTNUM="0" MAXNUM="50">
  <ADVANCEDSELECTOR URIPREFIX="http://company-sun/"
                    URIEXP=".*\.htm" >
  </ADVANCEDSELECTOR>
</INVALIDATIONPREVIEW>

Invalidation response:

"<?xml version="1.0"?>
<!DOCTYPE INVALIDATIONPREVIEWRESULT SYSTEM
"internal:///WCSinvalidation.dtd">
<INVALIDATIONPREVIEWRESULT VERSION="WCS-1.1" STATUS="SUCCESS"
                           STARTNUM="0" NUMURLS="2" TOTALNUMURLS="2">
  <SYSTEM>
    <SYSTEMINFO NAME="WCS_CACHE_NAME" VALUE="server-cache"/>
  </SYSTEM>
  <SELECTEDURL VALUE="/company-sun:80/index.htm "/>
  <SELECTEDURL VALUE="/company-sun:80/dtd.htm "/>
</INVALIDATIONPREVIEWRESULT>

Listing the Contents of the Cache

With Oracle9iAS Web Cache Manager, you can list the contents of the cache, generating the following types of lists:

• A list of the URLs of the most popular documents stored in the cache since the cache was last started

  You specify the number of objects and Oracle9iAS Web Cache Manager displays the list in the Cache Contents page.

• A list of the URLs of the objects currently in the cache

  You specify a file name and Oracle9iAS Web Cache writes the list of URLs to the file. You can use this list to verify that the cacheability rules are caching the objects that you want cached.

  Note: Oracle9iAS Web Cache Manager lists only those documents that are valid. Although the cache may contain documents that are expired or that have been invalidated, those documents are not included in these lists.

Listing Popular Documents

To view the list of URLs of the most popular documents, perform following steps:

1. Start Oracle9iAS Web Cache Manager.

   See Also: "Starting Oracle9iAS Web Cache Manager"

2. In the navigation pane, select Administration > Cache Contents.

   The Cache Contents page appears in the right pane.

3. From the For Cache list, select a cache. (More than one cache is listed only if you configured a cache cluster.)

4. For List Most Popular Objects in Cache, enter the number of URLs to display in the Number of Objects field.

5. Choose Update.

   Oracle9iAS Web Cache Manager displays a table containing the list of URLs of the most popular objects since the cache was last started. The table contains the following columns:

   Rank	A ranking, from 1 to 100, based on the score of the object. A rank of 1 represents the object with the highest score; that is, the most popular object.
   Object Name	The URL of the object. The URLs may contain additional descriptive information, such as cookie or session information.
   Size	The size of the object. The size is represented in bytes, kilobytes (KB), or megabytes (MB).
   Cacheability Rule	If there is a cacheability rule associated with the object, then this column displays a link to the Cacheability Rule Details page that shows the regular expression and site information for the URL.

Listing All Contents

You can also generate a list of all of the objects in the cache. However, to maintain the performance of the cache, Oracle Corporation recommends that you perform this operation during non-peak hours. While writing the list of URLs to the text file, performance may degrade somewhat.

To generate a list of the URLs of all of the documents currently in the cache:

1. Start Oracle9iAS Web Cache Manager.

   See Also: "Starting Oracle9iAS Web Cache Manager"

2. In the navigation pane, select Administration > Cache Contents.

   The Cache Contents page appears in the right pane.

3. From the For Cache list, select a cache. (More than one cache is listed only if you have a cache cluster.)

4. For List All Contents in Cache, choose Export to File.

   The Export Cache Contents dialog box appears. It lists the file to which it will write the URLs. By default, the file is written to the Oracle9iAS Web Cache log directory and is named webcache_contents.txt.

5. To write the list to a different location, enter a complete file specification in the text box.

6. Choose Submit.

   Oracle9iAS Web Cache writes the list of URLs to the text file you specified. Each time you generate the list, Oracle9iAS Web Cache appends the data to the existing file. It lists the date that the data was appended to the file, followed by the URLs of the objects currently cached. The following example shows an excerpt of the webcache_contents.txt file:

   Cache Contents at Wed Aug 22 11:47:03 2001
   www.company.com:80/images/lnav/lnav_products.gif
   www.company.com:80/images/rnav/rnav_red_line_1.gif
   www.company.com:80/images/bullets_and_symbols/blk_line_bullet_10.gif
   .
   .
   .
   Cache Contents at Wed Aug 22 13:01:24 2001
   www.company.com:80/images/white_spacer_xp.gif
   www.company.com:80/images/white_spacer.gif
   www.company.com:80/images/miniappsnet.gif
   .
   .
   .
   

Evaluating Event Logs

Oracle9iAS Web Cache events and errors are stored in an event log. The event log can help you determine which documents or objects have been inserted into the cache. It can also identify listening port conflicts or startup and shutdown issues. The event log has a file name of event_log and is stored in $ORACLE_HOME/webcache/logs on UNIX and ORACLE_HOME\webcache\logs on Windows.

This section contains the following topics:

• Format of the Event Log File

• Event Log Examples

• Finding Errors in the Event Log

• Configuring Event Logs

  See Also: Appendix E for descriptions of the most common event log messages

Format of the Event Log File

Events are formatted into the following fields:

Timestamp -- Information|Warning|Error: Message

Event Log Examples

Example: Event Log with Startup Entries

The following shows an event log excerpt with successful startup entries:

13/Nov/2001:19:26:59 +0000 -- Information: Maximum number of file/socket 
descriptors set to 910.
13/Nov/2001:19:26:59 +0000 -- Information: Maximum connections possible are 750
13/Nov/2001:19:26:59 +0000 -- Information: Listening on ADMINISTRATION port 4000 
address 0.0.0.0
13/Nov/2001:19:26:59 +0000 -- Information: The admin server started successfully
13/Nov/2001:19:26:59 +0000 -- Information: Maximum number of file/socket 
descriptors set to 910.
13/Nov/2001:19:26:59 +0000 -- Information: Maximum connections possible are 750
13/Nov/2001:19:27:00 +0000 -- Information: Listening on NORM port 7777 address 
0.0.0.0
13/Nov/2001:19:27:00 +0000 -- Information: Listening on NORMSSLV3_V2H port 4443 
address 0.0.0.0
13/Nov/2001:19:27:00 +0000 -- Information: Listening on INVALIDATION port 4001 
address 0.0.0.0
13/Nov/2001:19:27:00 +0000 -- Information: Listening on STATISTICS port 4002 
address 0.0.0.0
13/Nov/2001:19:27:00 +0000 -- Information: A 1 node cluster successfully 
initialized
13/Nov/2001:19:27:00 +0000 -- Information: The cache server started successfully
13/Nov/2001:19:27:00 +0000 -- Information: The cache server is started by the 
admin server at startup
13/Nov/2001:19:27:00 +0000 -- Information: Auto-Restart: WXE-00800 Auto-restart 
started successfully

Example: Event Log with Unsuccessful Startup Entries

The following shows an event log excerpt with unsuccessful startup events. Oracle9iAS Web Cache is unable to listen on port 7777, because it is already in use. This can occur if Oracle9iAS Web Cache is already running and listening on that port or another application is using that port.

13/Nov/2001:19:34:27 +0000 -- Information: Maximum number of file/socket 
descriptors set to 910.
13/Nov/2001:19:34:27 +0000 -- Information: Maximum connections possible are 750
13/Nov/2001:19:34:27 +0000 -- Information: Listening on ADMINISTRATION port 4000 
address 0.0.0.0
13/Nov/2001:19:34:27 +0000 -- Information: The admin server started successfully
13/Nov/2001:19:34:28 +0000 -- Information: Maximum number of file/socket 
descriptors set to 910.
13/Nov/2001:19:34:28 +0000 -- Information: Maximum connections possible are 750
13/Nov/2001:19:34:28 +0000 -- Error: Unable to listen on port 7777
13/Nov/2001:19:34:28 +0000 -- Error: Failed to start the server.
13/Nov/2001:19:34:28 +0000 -- Error: The server could not initialize
13/Nov/2001:19:34:28 +0000 -- Information: The server is exiting
13/Nov/2001:19:34:28 +0000 -- Warning: The admin server couldn't start the cache 
server, running in admin-only mode.

Example: Event Log with an Invalidation Entry

The following shows an event log excerpt with an event associated with an invalidation request for the removal of document cache.htm:

14/Nov/2001:23:58:23 +0000 -- Information: <Invalidation>1 URLs with
prefix /cache.htm have been successfully invalidated.
14/Nov/2001:23:58:23 +0000 -- Information: <Invalidation>Invalidation
with info 'remove cache static page' has returned with status
'SUCCESS'; number of documents invalidated: '1'.

Examples: Event Log with Invalidation Request Errors

The following shows an event log excerpt with an XML invalidation request error. In this example, Oracle9iAS Web Cache is unable to parse the request:

15/Nov/2001:00:00:11 +0000 -- Error: XML Parsing Error in NULL. Error
code 115. LPX-00115: Warning: element "BASICSELECTOR" missing required
attribute "URI"
15/Nov/2001:00:00:11 +0000 -- Error: WebCache failed to parse XML.
Error code 115
15/Nov/2001:00:00:11 +0000 -- Error: <Invalidation>Invalidation XML
Buffer cannot be parsed.

The following shows an event log excerpt with invalidation request for nonexisting documents:

15/Nov/2001:00:04:29 +0000 -- Information: <Invalidation>Requested URI
/cache.htm is not found in the cache.  URI is not invalidated.
15/Nov/2001:00:04:29 +0000 -- Information: <Invalidation>Invalidation
with info 'remove cache static page' has returned with status 'URI NOT
FOUND'; number of documents invalidated: '0'.

Example: Event Log with Shutdown Entries

The following shows an event log excerpt with typical shutdown entries:

13/Nov/2001:19:28:21 +0000 -- Information: SIGTERM caught - program will shut 
down once all connections are complete.
13/Nov/2001:19:28:21 +0000 -- Information: The server is exiting
13/Nov/2001:19:28:22 +0000 -- Information: SIGTERM caught - program will shut 
down once all connections are complete.
13/Nov/2001:19:28:22 +0000 -- Information: The server is exiting

Finding Errors in the Event Log

To list just the errors in the event log, use grep on UNIX. For example:

grep  " Error:" event* 

To list errors by the current day, enter grep " Error:" event_log | grep "dd/mon/yyyy". For example:

grep  " Error:" event_log | grep "19/Sep/2001" 

To list errors by the current day and hour, enter grep " Error:" event_log | "dd/mon/yyyy:hh".

Configuring Event Logs

To establish event log configuration settings:

1. Start Oracle9iAS Web Cache Manager.

   See Also: "Starting Oracle9iAS Web Cache Manager"

2. In the navigator pane, select Cache-Specific Configuration> Event Log.

   The Event Log page appears in the right pane.

3. In the Event Log page, select a cache and choose Edit.

   The Change Options for Event Logging dialog box appears.

4. In Time Format, select either Local or GMT (Greenwich Mean Time) to modify the time stamp style associated with entries in the event log file.

   Note: Oracle Corporation recommends using GMT whenever possible. Local can be CPU-intensive, because of the conversion process from GMT to Local time. This conversion process is supplied by the operation system. As such, Oracle9iAS Web Cache has no mechanism to improve the performance of the conversion process.

5. From the Rollover Frequency list, select how often you want to change the frequency at which Oracle9iAS Web Cache will save current log information to event_log.yyyymmdd and write new log information to event_log.

   If you have a high-volume site, increase the frequency.

6. In Verbose Mode, select either No to log typical events or Yes to log typical events, plus application Web server events.

   Verbose event logs are used for debugging purposes. Therefore, select Yes if recommended by Oracle Support Services.

7. Choose Submit.

8. Apply changes and restart Oracle9iAS Web Cache:
   1. In the Oracle9iAS Web Cache Manager main window, choose Apply Changes.

   2. In the navigator pane, select Administration > Operations.

      The Operations page appears in the right pane.

   3. In the Operations page, choose Restart to restart Oracle9iAS Web Cache.

Evaluating Access Logs

Oracle9iAS Web Cache generates an access log with the information about the HTTP requests sent to Oracle9iAS Web Cache. The access log has a file name of access_log and is stored by default in $ORACLE_HOME/webcache/logs on UNIX and ORACLE_HOME\webcache\logs on Windows. Note that Oracle9iAS Web Cache uses buffered logging for the access log, that is, it writes to the access log after the buffer is full.

This section contains the following topics:

• Format of the Access Log Files

• Access Log Examples

• Configuring Access Logs

Format of the Access Log Files

You can configure the content of the access log files by defining the fields to appear for each HTTP request event. Table 8-5 lists the fields you can enter.

Table 8-5  User-Specified for Access Logs

Usage Notes

• Separate fields by a space

• The order in which fields are entered determines the order in which the fields are logged

• If no fields are specified, then the following Common LogFile Format (CLF) fields are used by default:

  c-ip - c-auth-id [clf-date] "request line" sc-status bytes
  
  

  Entered fields are not added to the CLF default. You must either enter no fields to use the default or enter the fields specified in Table 8-5.

cs(request_header) and sc(response_header) Access Log Fields

Table 8-6 lists examples of HTTP/1.1 headers that can be used for the cs(request_header) and sc(response_header) fields. This table lists only some of the possible headers. It is not an exhaustive list.

Table 8-6  Examples of HTTP/1.1 Header Fields

Table 8-7 lists examples of cookie-related headers that can be used for the cs(request_header) and sc(response_header) fields.

Table 8-7  Supported Cookie-Related Header Fields

Table 8-8 lists examples of Oracle9iAS Web Cache headers that can be used for the cs(request_header) and sc(response_header) fields.

Table 8-8  Supported Oracle9iAS Web Cache Header Fields

Access Log Examples

The access logs that follow uses default fields c-ip - c-auth-id [clf-date] "request line" sc-status bytes.

In the first line of the first output:

• 138.2.213.146 is the browser's IP address (c-ip)

• [19/Nov/2001:10:27:42 -0500] is the date ([clf-date])

• "GET /~ssandrew/personal.htm HTTP/1.0" is the request line ("request line")

• 200 is the HTTP status code (sc-status)

• 2438 is the size of the document sent (bytes)

138.2.213.146 - - [19/Nov/2001:10:27:42 -0500] "GET /~ssandrew/personal.htm 
HTTP/1.0" 200 2438 
138.2.213.146 - - [19/Nov/2001:10:27:54 -0500] "GET 
/~ssandrew/personal.htm?UserName=Bob HTTP/1.0"
200 2438 
138.2.213.146 - - [19/Nov/2001:10:47:30 -0500] "GET /~ssandrew/count.sh 
HTTP/1.0" 403 289 
138.2.213.146 - - [19/Nov/2001:10:47:34 -0500] "GET /~ssandrew/sbin/count.sh 
HTTP/1.0" 200 321 
138.2.213.146 - - [19/Nov/2001:10:47:41 -0500] "GET /sbin/count.sh HTTP/1.0" 200 
321 
138.2.213.146 - - [19/Nov/2001:11:34:23 -0500] "GET /cache.htm HTTP/1.0" 200 250 
138.2.213.146 - - [19/Nov/2001:11:38:23 -0500] "GET /cache.htm HTTP/1.0" 304 0 
138.2.213.146 - - [19/Nov/2001:11:38:48 -0500] "GET /cache.htm HTTP/1.0" 304 0 
206.223.27.37 - - [19/Nov/2001:15:14:29 -0500] "GET 
/~ssandrew/personal.htm?UserName=Joe HTTP/1.0"
200 2438 
206.223.27.37 - - [19/Nov/2001:15:17:12 -0500] "GET 
/~ssandrew/personal.htm?UserName=Shehzaad
 HTTP/1.0" 200 438 
144.25.223.39 - - [19/Nov/2001:15:30:34 -0500] "GET /htdocs/coelist.html 
HTTP/1.0" 200 4219 
144.25.223.39 - - [19/Nov/2001:15:30:34 -0500] "GET /images/redheaderbanner.gif 
HTTP/1.0" 200 1226 
138.2.213.146 - - [19/Nov/2001:10:49:44 -0500] "GET /pls/coe/find_via_post 
HTTP/1.0" 200 1119 
138.2.213.146 - - [19/Nov/2001:10:49:44 -0500] "GET /ows-img/chalk.jpg HTTP/1.0" 
404 284 
130.35.35.21 - - [20/Nov/2001:00:36:35 -0500] "GET /images/support.jpg HTTP/1.0" 
206 3106 
130.35.35.21 - - [20/Nov/2001:00:36:35 -0500] "GET /images/ani_coe.gif HTTP/1.0" 
206 73118 

Example: Access Log with Reload Entries

The following shows an access log excerpt in which there are two Web browser reloads, followed by two shift reloads, and two more reloads:

138.2.213.146 - - [19/Nov/2001:11:04:24 -0500] "GET /cache.htm HTTP/1.0" 200 250 
138.2.213.146 - - [19/Nov/2001:11:04:26 -0500] "GET /cache.htm HTTP/1.0" 200 250 
138.2.213.146 - - [19/Nov/2001:11:29:24 -0500] "GET /cache.htm HTTP/1.0" 304 0 
138.2.213.146 - - [19/Nov/2001:11:29:25 -0500] "GET /cache.htm HTTP/1.0" 304 0 
138.2.213.146 - - [19/Nov/2001:11:29:30 -0500] "GET /cache.htm HTTP/1.0" 200 250 
138.2.213.146 - - [19/Nov/2001:11:29:35 -0500] "GET /cache.htm HTTP/1.0" 200 250

The third and forth entries return an HTTP status code of 304, indicating that document has not been modified and does not need to be returned again.

Example: Access Log with Status Code 404 Entry

The following shows an access log excerpt in which Oracle9iAS Web Cache cannot find any objects matching the requested URL /ows-img/chalk.jpg. This error is indicated by HTTP status code 404.

138.2.213.146 - - [19/Nov/2001:10:49:44 -0500] "GET /pls/coe/find_via_post 
HTTP/1.0" 200 1119 
138.2.213.146 - - [19/Nov/2001:10:49:44 -0500] "GET /ows-img/chalk.jpg HTTP/1.0" 
404 284 

Example: Access Log Host Name

The following shows an access log excerpt in which the following fields are specified:

c-ip c-auth-id clf-date cs(Host) req-line sc-status bytes 

cs(Host) displays the output of Host request-header field, which specifies the site information. In this examples, requests are sent to Oracle9iAS Web Cache for site www.company.com:80.

148.87.1.180    -       [11/Dec/2001:18:42:04 +0000]    "www.company.com:80"     
GET / HTTP/1.1  200     1456
148.87.1.180    -       [11/Dec/2001:18:42:07 +0000]    "www.company.com:80"     
GET / HTTP/1.1  200     1456
148.87.1.180    -       [11/Dec/2001:18:42:08 +0000]    "www.company.com:80"     
GET / HTTP/1.1  200     1456
148.87.1.180    -       [11/Dec/2001:18:42:08 +0000]    "www.company.com:80"     
GET /apache_pb.gif HTTP/1.1     200     2326
148.87.1.180    -       [11/Dec/2001:18:42:09 +0000]    "www.company.com:80"     
GET / HTTP/1.1  200     1456
148.87.1.180    -       [11/Dec/2001:18:42:18 +0000]    "www.company.com:80"     
GET / HTTP/1.1  200     1456
148.87.1.180    -       [11/Dec/2001:18:42:18 +0000]    "www.company.com:80"     
GET /apache_pb.gif HTTP/1.1     200     2326

Configuring Access Logs

To enable access logging:

1. Start Oracle9iAS Web Cache Manager.

   See Also: "Starting Oracle9iAS Web Cache Manager"

2. In the navigator pane, select Cache-Specific Configuration > Access Log.

   The Access Log page appears in the right pane.

3. In the Access Log page, choose Edit.

   The Change Options for Access Logs dialog box appears.

4. In Logging Enabled, select Yes.

5. In the Logging Directory field, enter the directory path where you want the log file written.

6. In Time Format, select either Local or GMT (Greenwich Mean Time) to modify the time stamp style associated with entries in the access log file.

   Note: Oracle Corporation recommends using GMT whenever possible. Local can be CPU-intensive, because of the conversion process from GMT to Local time. This conversion process is supplied by the operation system. As such, Oracle9iAS Web Cache has no mechanism to improve the performance of the conversion process.

7. From the Rollover Frequency list, select how often you want to change the frequency at which Oracle9iAS Web Cache will save current log information to access_log.yyyymmdd and write new log information to access_log.

   If you have a high-volume site, increase the frequency.

8. In the User-Specified Fields field, enter the fields to log.

   Separate fields by a space. Do not attempt to copy and paste the default format displays in the online help into the field. If you do, then an error will display.

9. Choose Submit.

10. Apply changes and restart Oracle9iAS Web Cache:
    1. In the Oracle9iAS Web Cache Manager main window, choose Apply Changes.

    2. In the navigator pane, select Administration > Operations.

       The Operations page appears in the right pane.

    3. In the Operations page, choose Restart to restart Oracle9iAS Web Cache.

To disable access logging:

1. Start Oracle9iAS Web Cache Manager.

   See Also: "Starting Oracle9iAS Web Cache Manager"

2. In the navigator pane, select Cache-Specific Configuration > Access Log.

   The Access Log page appears in the right pane.

3. In the Access Log page, choose Edit

   The Change Options for Access Logs dialog box appears.

4. In Logging Enabled, select NO.

5. Choose Submit.

6. Apply changes and restart Oracle9iAS Web Cache:
   1. In the Oracle9iAS Web Cache Manager main window, choose Apply Changes.

   2. In the navigator pane, select Administration > Operations.

      The Operations page appears in the right pane.

   3. In the Operations page, choose Restart to restart Oracle9iAS Web Cache.