This chapter explains how to send invalidation requests to Oracle Web Cache.
This chapter includes the following topics:
As described in Section 6.7, you create expiration policies and associate them with caching rules to refresh content from the origin server. Even with expiration policies, it is often difficult to predict when exactly content becomes stale. As an alternative, Oracle Web Cache provides mechanisms for explicitly invalidating content when an administrator or application knows that such content has become stale.
With invalidation, Oracle Web Cache marks objects as invalid. When objects are marked as invalid and a client requests them, they are removed and then refreshed with new content from the origin servers. You can choose to remove and refresh invalid objects immediately, or base the removal and refresh on the current load of the origin servers.
Oracle Web Cache supports the following forms of invalidation:
Invalidation through a special invalidation port. This type of invalidation is known as an out-of-band invalidation, because such invalidation requests do not go through the Oracle Web Cache listening port. See Section 7.2.
ESI inline invalidation where the invalidation directive comes as an ESI tag through the response body to a normal request. See Section 7.3.
Response-header invalidation where the invalidation directive comes as a special (and proprietary) response header in the response to a normal request. See Section 7.4.
To invalidate objects in the cache, you can send an HTTP POST request from the invalidator
account through the invalidation listening port. The invalidator
account is authorized to send invalidation requests. As shown in Figure 7-1, you send invalidation requests using these methods:
Manually, using Fusion Middleware Control or telnet
Automatically, using database triggers, scripts, or application logic
The following sections describe the specific methods you can use:
Inline invalidation is implemented as part of Edge Side Includes (ESI) and provides a useful way for origin servers to "piggyback" invalidation messages on HTTP responses sent to Oracle Web Cache. Specifically, origin servers embed an XML invalidation document within the HTML of the response body using ESI tags.
For instance, when a customer purchases a vegetarian cookbook on an e-commerce site, the confirmation response could contain instructions for invalidating all catalog pages related to the book, its author and vegetables. The ability to send invalidation message inline reduces the connection overhead associated with sending out-of-band invalidations and is a useful tool for ESI developers.
For more information about using ESI invalidation, see Section 11.3.
Response header invalidation is Oracle Web Cache functionality that enables an origin server to return a transactional response whose response body contains something other than HTML. This is a circumstance in which ESI inline invalidation does not work; Oracle Web Cache can only use ESI invalidation tags in conjunction with a response body that contains HTML. With response header invalidation, origin servers can send invalidation directives in a proprietary invalidation response header.
In addition to its greater flexibility in terms of response body content returned, response header invalidation requires less coding effort on the part of the Web applications since building an invalidation header is a fairly lightweight task.
Response header invalidation functions similarly to inline invalidation; origin servers "piggyback" invalidation directives on responses sent to Oracle Web Cache. However, the response header invalidation enables invalidation when the response body contains something other than HTML.
The origin server adds a special invalidation header to its response. Oracle Web Cache extracts the invalidation header, invalidates the corresponding content and forwards the response to its client but without the invalidation header in the response.
Origin Servers can piggyback an invalidation response header on any random response. For example, an origin server may delay the sending of an invalidation directive and then send it later in a response to a request that has nothing to do with the request that caused the invalidation in the first place.
Oracle Web Cache strips out the invalidation response header when returning the response to a Web client. Oracle Web Cache even strips out the invalidation response header when returning the response to another member of an cache cluster, since cluster propagation forwards the invalidation to other peers in the cluster.
For more information about enabling response header invalidation, see Section 7.8.
The out-of-band mechanisms send out-of-band HTTP POST invalidation requests in Extensible Markup Language (XML) syntax. The ESI inline mechanism also uses the same syntax within the <esi:invalidate>
tag. The contents of the XML request body instructs the cache which URLs to mark as invalid.
The following sections describe invalidation request syntax:
Use the following syntax to invalidate objects 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 objects 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" 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 that 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.
Note the following:
No white space is allowed before "<?xml
".
If an application is sharing invalidation requests with a third-party XML parser, replace "internal:///WCSinvalidation.dtd"
with the following path:
"http://www.oracle.com/webcache/90400/WCSinvalidation.dtd"
The root element INVALIDATION
contains one or more of the attributes and elements described in Table 7-1.
Table 7-1 INVALIDATION Elements and Attributes
Invalidation Element/Attribute | Description |
---|---|
Required attribute in the Denote the version of the For versions 9.0. |
|
Optional element in the |
|
Required element in the The possible
|
|
Required element in the invalidation request. You can specify multiple |
|
|
|
The prefix is interpreted literally, including reserved regular expression characters. These characters include periods ( |
|
|
Regular expression characters are permitted. To interpret these characters literally, escape them with a backslash ( See Notes:
|
|
|
|
|
|
Note: When the invalidation request is sent, Oracle Web Cache performs a regular expression match of |
|
Optional element in the invalidation request. Use the following attributes:
If you specify a cookie that was mistakenly specified for both a multiple-version object and a session caching policy, invalidation is based on any occurrence of the cookie. To avoid excessive invalidation, configure distinct cookies for multiple-version objects and session caching policies. For more information, see:
|
|
Optional element in the invalidation request. Use the following attributes:
See Section 6.8.2 to create caching rules for multiple-version objects. |
|
Optional element in the invalidation request. Use the following attributes:
For more information, see:
|
Required element in the invalidation request Optional attribute of the |
|
Optional element in the invalidation request Required attribute of the [15/Oct/2008:19:26:46 +0000] [notification 11748] [invalidation] [ecid: 21085932167,0] Invalidation with INFO 'INFO_comment' has returned with status 'status'; number of objects invalidated: 'number'. |
Note:
The following special XML characters must be escaped in the fields: ampersand (&
) with "&
", greater than sign (>
) with ">
", less than sign (<
) with "<
", double quotes ("
) with ""
", and single quotes ('
) with "'
".Note:
Oracle Web Cache continues to support invalidation requests sent in the following release 1.0 format:<?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 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.1"> <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.1"> <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" 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 7-2. BASICSELECTOR
and ADVANCEDSELECTOR
are described in Table 7-1.
Table 7-2 INVALIDATIONRESULT Elements and Attributes
To test invalidation, use the following syntax to preview the list of BASICSELECTOR
objects 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"/> </INVALIDATIONPREVIEW>
Use the following syntax to preview the list of ADVANCEDSELECTOR
objects 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" TYPE="SUBSTRING|REGEX" VALUE="value"/> </ADVANCEDSELECTOR> </INVALIDATIONPREVIEW>
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 7-3. BASICSELECTOR
and ADVANCEDSELECTOR
are described in Table 7-1.
Table 7-3 INVALIDATIONPREVIEW Attributes
Invalidation Element/Attribute | Description |
---|---|
Required attribute in the invalidation preview Use |
|
Required attribute in the invalidation preview Enter the number representing the first object to be listed. Oracle Web Cache begins the count of objects with the number 0. |
|
Required attribute in the invalidation preview Enter the number of objects to be listed. If fewer objects than the number specified meet the invalidation criteria, Oracle Web Cache lists only the URLs for those objects that meet the criteria. If more objects than the number specified meet the invalidation criteria, Oracle Web Cache lists the URLs for the number of objects requested. It also returns the total number of objects that meet the invalidation criteria. To obtain the list of URLs for addition objects, send another preview request with a different |
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 that the response is an invalidation preview response using the WCSinvalidation.dtd
file as the XML document type.
Note the following:
No white space is allowed before "<?xml
".
If an application is sharing invalidation requests with a third-party XML parser, replace "internal:///WCSinvalidation.dtd"
with the following path:
"http://www.oracle.com/webcache/90400/WCSinvalidation.dtd"
The root element INVALIDATIONPREVIEWRESULT
contains one or more of the attributes and elements described in Table 7-4. BASICSELECTOR
and ADVANCEDSELECTOR
are described in Table 7-1.
Table 7-4 INVALIDATIONPREVIEWRESULT Elements and Attributes
Invalidation Element/Attribute | Description |
---|---|
Version number of the |
|
Status of the preview:
|
|
Number representing the first object to be listed |
|
Number of URLs returned in this preview result |
|
Number of URLs matching the |
|
URLs matching the |
This section contains the following invalidation request examples:
Section 7.5.5.3, "Example: Invalidating a Subtree of Objects"
Section 7.5.5.4, "Example: Invalidating All Objects for a Web Site"
Section 7.5.5.5, "Example: Invalidating Objects Using Prefix Matching"
Section 7.5.5.6, "Example: Invalidating Objects Using Substring and Query String Matching"
Section 7.5.5.7, "Example: Invalidating Objects Using Search Key Matching"
Section 7.5.5.8, "Example: Propagating Invalidation Requests Throughout a Cache Cluster"
The examples in this section require using 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.
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 an object 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 request 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.
The following request invalidates two different objects, summary.jsp
and summary.gif
. In addition, the request provides the comments "summary.jsp"
and "summary.gif"
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="/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.1"> <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:
[15/Oct/2008:19:26:46 +0000] [notification 11748] [invalidation] [ecid: 21085932167,0] Invalidation with INFO 'summary.jsp' has returned with status 'SUCCESS'; number of objects invalidated: '2'. . . . [15/Oct/2008:19:26:46 +0000] [notification 11748] [invalidation] [ecid: 21085932167,0] Invalidation with INFO 'summary.gif' has returned with status 'SUCCESS'; number of objects invalidated: '14'.
The following request invalidates all objects under the /images/
directory:
<?xml version="1.0"?> <!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd"> <INVALIDATION VERSION="WCS-1.1"> <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.1"> <OBJECTRESULT> <ADVANCEDSELECTOR URIPREFIX="/images/" HOST="www.company.com:80"/> <RESULT ID="1" STATUS="SUCCESS" NUMINV="125"/> </OBJECTRESULT> </INVALIDATIONRESULT>
The following request invalidates all objects 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.1"> <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.1"> <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>
The following request invalidates all objects under /
.
<?xml version="1.0"?> <!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd"> <INVALIDATION VERSION="WCS-1.1"> <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.1"> <OBJECTRESULT> <ADVANCEDSELECTOR URIPREFIX="/" HOST="www.company.com:80"/> <RESULT ID="1" STATUS="SUCCESS" NUMINV="17"/> </OBJECTRESULT> </INVALIDATIONRESULT>
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 Oracle 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 objects with a URI containing /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.
The following request invalidates all objects 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.1"> <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 writes to the event log:
[15/Oct/2008:19:26:46 +0000] [notification 11748] [invalidation] [ecid: 21085932167,0] Invalidation with INFO 'remove-htm-under-all-post-dir has returned with status 'SUCCESS'; number of objects invalidated: '52'.
The following request invalidates all objects 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.1"> <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 writes to the event log:
[15/Oct/2008:19:26:46 +0000] [notification 11748] [invalidation] [ecid: 21085932 167,0] Invalidation with INFO 'remove-view-building8-10th-floor' has returned with status 'SUCCESS'; number of objects invalidated: '3'.
See Section 7.7.2.2 to optimize invalidations using QUERYSTRING_PARAMETER
.
The following request invalidates all objects under /pls/publicuser/
, matching the following:
Substring /pls/publicuser/!MODULE.wwpob_page.show
HTTP request header x-oracle-cache-user
and value PUBLICUSER
Surrogate-Key
response-header field containing a search key of template_id=33,31345.
<?xml version="1.0"?> <!DOCTYPE INVALIDATION SYSTEM "internal:///WCSinvalidation.dtd"> <INVALIDATION VERSION="WCS-1.1"> <OBJECT> <ADVANCEDSELECTOR URIPREFIX="/pls/publicuser/" HOST="www.company.com:80" METHOD="POST"> <OTHER NAME="SEARCHKEY" VALUE="template_id=33,31345"/> <HEADER NAME="x-oracle-cache-user" VALUE="PUBLICUSER"/> <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="/pls/publicuser/!MODULE.wwpob_page.show"/> </ADVANCEDSELECTOR> <ACTION REMOVALTTL="0"/> </OBJECT> </INVALIDATION>
Invalidation response:
<?xml version="1.0"?> <!DOCTYPE INVALIDATIONRESULT SYSTEM "internal:///WCSinvalidation.dtd"> <INVALIDATIONRESULT VERSION="WCS-1.1"> <OBJECTRESULT> <ADVANCEDSELECTOR URIPREFIX="/pls/publicuser/" HOST="www.company.com:80" METHOD="POST"> <OTHER NAME="SEARCHKEY" VALUE="template_id=33,31345"/> <HEADER NAME="x-oracle-cache-user" VALUE="PUBLICUSER"/> <OTHER NAME="URI" TYPE="SUBSTRING" VALUE="/pls/publicuser/!MODULE.wwpob_page.show"/> <RESULT ID="1" STATUS="SUCCESS" NUMINV="3"/> </OBJECTRESULT> </INVALIDATIONRESULT>
In a cache cluster, you can enable or disable the propagation of invalidation requests to all cluster members in Fusion Middleware Control and Oracle Web Cache Manager, as described in Section 3.6.5 and Section 3.7.4, respectively.
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 Fusion Middleware Control or Oracle Web Cache Manager. If NAME
is set to WCS_PROPAGATE
and VALUE
is set to FALSE
, it reads the setting specified in Fusion Middleware Control or Oracle 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="/web_cache_host_name: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>
The following request previews up to 50 objects 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>
You can base invalidation on one or more search keys used in the Surrogate-Key
response-header field of objects in the cache.
The Surrogate-Key
response-header field enables application developers to identify search key strings for a given response object. Search keys are strings that may not appear in the URL, cookies, or HTTP request headers of objects. The intent of the search keys is to provide another criteria for invalidation. In addition to the URL of objects, Oracle Web Cache administrators can base invalidation on one or more search keys used in the Surrogate-Key
response-header field of objects in the cache.
The Surrogate-Key
response-header field supports the following syntax:
Surrogate-Key: search-key=("key" "key" "key" ...)
If search-key
is specified in this header, then at least one search key value must be present.
Search key values must be enclosed within quotes ("
).
Search key values can be of any format, such as "key_value"
or "key_name
=
key_value"
.
The maximum number of allowed search keys is 20.
Space between search keys is optional.
The search keys must remain the same.
The following examples show valid Surrogate-Key
fields. The first example shows one search key of template_id=33,31345
, and the second example shows search keys of template_id=33,31345
and category
.
Surrogate-Key: search-key=( "template_id=33,31345" ) Surrogate-Key: search-key=("template_id=33,31345" "category")
The following examples show invalid Surrogate-Key
fields. The first example shows one search key of 348
without an ending quote ("
), and the second example shows search-key
without any search key values.
Surrogate-Key: search-key=( "template_id=348 ) Surrogate-Key: search-key=( )
For more information about enabling search-key invalidation, see Section 7.9.
The following topics describe how to initiate out-of-band invalidations:
Section 7.7.2, "Using Oracle Web Cache Manager to Send Invalidation Requests"
Section 7.7.3, "Using Application Program Interfaces (APIs) for Automated Invalidation Requests"
Section 7.7.4, "Using Database Triggers for Automated Invalidation Requests"
When you send an invalidation request with an HTTP POST request, you specify the host name of Oracle Web Cache, the invalidation listening port number, and the invalidation request.
For example, if you are using telnet
, you send an invalidation request using the following procedure:
Connect to Oracle Web Cache at the invalidation listening port:
telnet web_cache_host invalidation_port
Specify a POST message header and authenticate the invalidator
account 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
The following shows an example of the Authorization
line:
Authorization: BASIC aW52YWxpZGF0b3I6aW52YWxpZGF0b3I=
In this example, aW52YWxpZGF0b3I6aW52YWxpZGF0b3I=
is the invalidator user name and password (invalidator:invalidator
) encoded.
For more information, see:
http://www.rfc-editor.org/
for information about password Base64 encoding
readme.examples.html
for further information about using the EncodeBase64.java
script to generate the Base64 string for invalidator:
invalidator_password
. This file is located in the following directories:
(UNIX) ORACLE_HOME/webcache/docs (Windows) ORACLE_HOME\webcache/docs
Section 5.2 for further information about changing the invalidation password
Enter one carriage return.
Send the invalidation request with XML syntax, as specified in Section 7.5.
Oracle Web Cache Manager provides an easy-to-use interface for invalidating cached objects. The advantage of using this interface 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 how quickly those objects should be invalidated.
Oracle Web Cache Manager enables you to send either basic invalidation request for invalidation one object, or an advanced invalidation request for multiple objects, as described in the following topics:
Note:
If you receive the following error when you submit invalidation requests from the Basic Content Invalidation or Advanced Content Invalidation pages, restart thecache
or admin
server processes.
Internal error: can't connect to Oracle Web Cache Invalidation Listening Port
If you change the property of an invalidation port, restart the cache
server process. If you change the password for the administrator
account in the Security page, restart the cache
and admin
server processes. Until you restart the cache
server process for either configuration change, invalidation requests return the error.
See Section 2.13 for restart instructions.
To send a basic invalidation request using Oracle Web Cache Manager:
From Oracle Web Cache Manager, in the navigator frame, select Operations > Basic Content Invalidation. See Section 2.7.2.
The Basic Content Invalidation page appears in the right pane.
From the For Cache list, select a cache. (The list displays multiple caches only if you configured a cache cluster. If you configured the cluster to propagate invalidation, the cache you select is designated the invalidation coordinator, which propagates the invalidation request to other cache cluster members. If you did not configure the cluster to propagate invalidation, the cache you select is the only cache from which objects are invalidated.)
In the Search Criteria section, select the search criteria:
Remove all cached objects: Select to remove all objects from the cache.
Enter exact URL for removal: Specify the URL of the objects to be invalidated. Include the complete path and file name.
Note: Because Oracle Web Cache escapes the following characters, you can enter them in this field: ampersand (&
), greater than sign (>
), less than sign (<
), double quotes ("
), and single quotes ('
).
Optionally, you can preview the list of objects to be invalidated to ensure that you are removing only the objects you want to remove. To preview the list of objects:
In the Action section, choose Preview list of objects that match invalidation criteria.
Specify the Object Range:
From: Enter the number representing the first object to be listed. Oracle Web Cache begins the count of objects with the number 0.
To: Enter the number of objects to be listed.
If fewer objects than the number specified meet the invalidation criteria, Oracle Web Cache lists the URLs for only those objects that meet the criteria.
If more objects than the number specified meet the invalidation criteria, Oracle Web Cache lists the URLs for the number of objects requested. It also returns the total number of objects that meet the invalidation criteria. To obtain the list of URLs for additional objects, send another preview request with a different From number that specifies the start of the next set of objects.
Click Submit.
Oracle Web Cache displays the Invalidation Preview Results message box, which lists the objects that meet the invalidation criteria. Oracle Web Cache Manager lists only those objects that are valid. Although the cache may contain objects that are expired or that have been invalidated, those objects are not listed.
If the listed objects are for those to invalidate, continue with the next step. If they are not, modify the invalidation criteria and preview the list again.
In the Action section, select an option to specify how to process invalid objects:
Remove immediately: Oracle Web Cache marks objects as invalid and removes them immediately. A object is refreshed from the origin server when the cache receives the next request for it.
Remove objects no later than <number> <time> after submission: Oracle Web Cache marks objects as invalid and then refreshes them based on origin server capacity. Enter the maximum time in which the objects can reside in the cache. When you select this option, Oracle Web Cache applies heuristics to determine when is best time to no longer serve the document.
Click Submit.
Oracle Web Cache processes the invalidation request, and returns the Cache Cleanup Result dialog box which shows the invalidation status. The following figure shows the dialog box:
In a cache cluster environment, if Invalidation requests sent to any cluster member will be propagated to all cluster members is enabled, Oracle Web Cache sends the invalidation request to one cluster member who acts as the invalidation coordinator. The coordinator propagates the invalidation request to other cluster members. When the invalidation has been completed for all cluster members, Oracle 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.
For more information, see Section 3.6.5 for information about enabling invalidation propagation.
To send an advanced invalidation request using Oracle Web Cache Manager:
In the navigator frame, select Operations > Advanced Content Invalidation.
The Advanced Content Invalidation page appears in the right pane.
From the For Cache list, select a cache. (The list displays multiple caches only if you configured a cache cluster.)
In the Search Criteria section, select the search criteria:
Note:
Because Oracle Web Cache escapes the following characters, you can enter them in the search criteria fields: ampersand (&
), greater than sign (>
), less than sign (<
), double quotes ("
), and single quotes ('
).URL Path Prefix: Required. Specify the path prefix of the objects to be invalidated. The path prefix 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 (\
).
Host Name: Optional. Specify the host name and port number of the site (host_name
:
port
). Port 80 is the default port for HTTP.
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 objects to be invalidated. The default value is GET.
URL Expression: Optional. Specify the URL of the objects to be invalidated under the URL Path Prefix. Then, specify how to match by selecting either substring for an exact string match or regular expression for a regular expression match.
If no value is entered, everything under the URL Path Prefix is matched.
POST Body Expression: Optional. If POST is selected for the HTTP Method, enter the HTTP POST body of the objects to be invalidated, and then specify how to match by selecting either substring for a substring string match or regular expression for a regular expression match.
Note:
If regular expression is selected for the URL Expression or POST Body Expression fields, Oracle Web Cache interprets the following reserved regular expression characters: periods (.
), question marks (?
), asterisks (*
), brackets ([]
), curly braces ({}
), carets (^
), dollar signs ($
), and backslashes (\
). To interpret these characters literally, escape them with a backslash (\
).Optionally, in the Cookie/Header Information section, specify the use of cookie names or HTTP request headers used for multiple-version objects in the search criteria:
From the list, select Cookie or Header.
Provide the following information:
Cookie: Enter the cookie name used by multiple-version objects to be invalidated in the Name field, and enter its value in the Value field.
Note:
If you specify a cookie that was mistakenly specified for both a multiple-version object and a session caching policy, invalidation is based on any occurrence of the cookie. To avoid excessive invalidation, configure distinct cookies for multiple-version objects (Rules for Caching, Personalization, and Compression > Cookie Definitions) and session caching policies (Rules for Caching, Personalization, and Compression > Session Definitions).Header: Enter the HTTP request header used by the objects to be invalidated in the Name field, and enter its value in the Value field.
See Section 6.5.1 to create caching rules for multiple-version objects.
Optionally, in the URL Parameters section, enter the name of the embedded URL parameter used by the objects to be invalidated in the Name field, enter its value in the Value field, and then specify how to match by selecting either exact strings or regular expression.
Optionally, in the Search Keys section, enter the name of a search key from the Surrogate-Key
response-header field used by the objects to be invalidated in the Key field. See Section 7.6 and Section 7.9.
Optionally, you can preview the list of objects to be invalidated to ensure that you are removing only the objects you want to remove. To preview the list of objects:
In the Action section, choose Preview list of objects to be removed.
Specify the Object Range:
From: Enter the number representing the first object to be listed. Oracle Web Cache begins the count of objects with the number 0.
To: Enter the number of objects to be listed.
If fewer objects than the number specified meet the invalidation criteria, Oracle Web Cache lists the URLs for only those objects that meet the criteria.
If more objects than the number specified meet the invalidation criteria, Oracle Web Cache lists the URLs for the number of objects requested. It also returns the total number of objects that meet the invalidation criteria. To obtain the list of URLs for additional objects, send another preview request with a different From number that specifies the start of the next set of objects.
Click Submit.
Oracle Web Cache displays the Invalidation Preview Results message box, which lists the objects that meet the invalidation criteria. Oracle Web Cache Manager lists only those objects that are valid. Although the cache may contain objects that are expired or that have been invalidated, those objects are not listed.
If the listed objects are for those to invalidate, continue with the next step. If they are not, modify the invalidation criteria and preview the list again.
In the Action section, select an option to specify how to process invalid objects:
Remove immediately: Oracle Web Cache marks objects as invalid and then removes them immediately. A object is refreshed from the origin server when the cache receives the next request for it.
Remove objects no later than <number> <time> after submission: Oracle Web Cache marks objects as invalid and then refreshes them based on origin server capacity. Enter the maximum time in which the objects can reside in the cache.
Click Submit.
Oracle Web Cache processes the invalidation request, and returns a Cache Cleanup dialog box which shows the invalidation status.
Note:
For prefix-based invalidations that require Oracle Web Cache to traverse a complex directory structure, invalidation can take some time. Therefore, do not click Submit again until the Cache Cleanup Result dialog box appears. Creating a queue of invalidation requests can degrade the performance of Oracle Web Cache.Invalidation requests can originate from a Web site's underlying application logic or from the content management application used to design Web pages.
Oracle Web Cache ships with the following Application Program Interfaces (APIs) that you can implement:
These APIs are located in the following directories:
(UNIX) ORACLE_HOME/webcache/toolkit (Windows) ORACLE_HOME\webcache/toolkit
For more information about these APIs, see readme.toolkit.html
in the following directories for further information about the APIs:
(UNIX) ORACLE_HOME/webcache/docs (Windows) ORACLE_HOME\webcache/docs
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. Use the UTL_TCP
Oracle supplied package to send invalidation requests through database triggers.
For more information, see Oracle PL/SQL documentation.
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 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 Oracle Web Cache. To achieve this result, you can modify the PERL script such that when the bulk loading operation has completed, the script sends 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 Oracle 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.
Response header invalidation is an Oracle Web Cache feature that enables an origin server to invalidate cached content through an HTTP response header.
The response-header field supports the following syntax:
Oracle-WebCache-Invalidate: ([SYNCHRONOUS=ON|OFF,] (URI="value" | ( URI_DIR="value" [(;S_KEY="value")*] ) | ( S_KEY="value" [(;S_KEY="value")*] )) ([,SYNCHRONOUS=ON|OFF,] URI="value" | ( URI_DIR="value" [(;S_KEY="value")*] ) | ( S_KEY="value" [(;S_KEY="value")*] ))* [,SYNCHRONOUS=ON|OFF]
Table 7-5 describes the control directives for response header invalidation.
Table 7-5 Control Directives for Oracle-WebCache-Invalidate
Control Directive | Description |
---|---|
|
The If an origin server appends an invalidation response header to a random request, the client sending the request should not have to wait for the invalidation to complete. In this case, the origin server should direct Oracle Web Cache to return the response before proceeding with the invalidation ( |
|
An invalidation specification with the URI option directive enables Oracle Web Cache to invalidate the entry with the specified URI; this corresponds to basic invalidation. |
|
An invalidation specification with the URI_DIR option directive enables Oracle Web Cache to interpret the specified URI as a directory and to invalidate all entries stored in the specified directory; this corresponds to URI prefix invalidation, a small but often used subset of advanced invalidation. Note that the directory URI strings must end in a slash (/) to make the URI_DIR option directive consistent with current URI prefix invalidation. |
|
An invalidation specification with the When a |
Conjoined Multiple Directives |
An invalidation response header may contain a URI directory followed by one or more search keys. In this situation, a semicolon (;) delimiter separates each directive. When this occurs, a Oracle Web Cache entry must match all the directives to qualify for invalidation. |
Multiple Invalidation Directives |
When an invalidation response header contains multiple invalidation directives with each consecutive pair of invalidation directives separated by a comma, an Oracle Web Cache entry must match at least one invalidation directive to qualify for invalidation. In other words, Oracle Web Cache treats each comma-delimited invalidation directive as an independent invalidation operation. |
Mixing Commas and Semicolons |
When an invalidation response header contains both kinds of separators, commas and semicolons, semicolons take precedence. In other words, the consecutive directives separated by semicolons must be examined; then consecutive directives separated by commas are examined. |
Multiple Invalidation Response Headers |
An origin server can store multiple invalidation response headers in its response to Oracle Web Cache. When this happens, an Oracle Web Cache entry only needs to match one header to qualify for invalidation. In other words, the content of multiple invalidation response headers in the same response are treated as if they were part of a single response header joined by commas. If a response contains at least one invalid invalidation response header, no invalidation takes place even if the response contains other valid invalidation response headers. |
An invalidation response header consists of the header name "Oracle-WebCache-Invalidate"
followed by a colon (:), followed by one or more invalidation directives with consecutive pairs of invalidation directives separated by a comma (,). Optional synchronicity directives may appear before or after any directive.
A synchronicity directive consists of the keyword "SYNCHRONOUS
" followed by an equal sign (=) followed by either the keyword "ON
"or the keyword "OFF
".
An invalidation consists of either a URI or a multi-directive specification.
A URI directive consists of a URI option directive followed by an equal sign (=) followed by a quoted string.
A URI option directive consists of the keyword URI
.
A multi-directive specification has two distinct formats:
an explicit directory
an implicit directory
The explicit directory format consists of a URI directory directive followed by zero or more search key directives with consecutive search keys separated by a semicolon (;) delimiter.
The implicit directory format consists of 1 or more search keys with consecutive search keys separated by a semicolon (;) delimiter.
A URI directory consists of a URI directory option directive followed by an equal sign (=) followed by a quoted string.
A URI directory option directive consists of the keyword URI_DIR
.
A search key consists of a search key option directive followed by an equal sign (=) followed by a quoted string.
A search key option directive consists of the keyword S_KEY
.
A quoted string contains either a URI or a search key. Case-sensitivity rules and allowable character sets for URI and search key strings are the same as for other invalidation functionality.
For fully qualified URIs, a valid scheme includes either http://
or https://
, and a valid host name (for example, www.host1.com
).
Port numbers, when specified, must be valid as well. When a URI does not contain a port number, Oracle Web Cache assumes a default port number of 80 for HTTP and 443 for HTTPS. For implicit URI directories, Oracle Web Cache determines the directory based on the site of the original request. Oracle Web Cache ensures that the resulting site definition matches the site definition associated with the original request. In other words, as a security precaution, Oracle Web Cache disallows cross-site invalidation.
Note that with site-to-server mappings involving wildcards, some requests may have no associated site definition. In this case, the principal of conservatism applies, and Oracle Web Cache disallows the response header invalidation.
The following sections provide examples of invalidation response headers.
The examples are based on the fictional Web application for Harry's Hardware store with the Web site:
http://www.HarrysHardware.com
At this site, Harry publishes descriptions (including the retail price) for all the popular items he sells. Harry improves the response time for his on-line customers by deploying a Oracle Web Cache in front of the Web server hosting his site, but to ensure his on-line customers see fresh content, he wants the application to invalidate relevant Oracle Web Cache entries whenever it updates descriptions or prices for items in the store. The examples below indicate how to use response header invalidation for various scenarios that Harry has identified.
The sections include:
Section 7.8.1.4, "Search Key Invalidation with Explicit URI"
Section 7.8.1.5, "Search Key Invalidation with Implicit URI"
Harry sells one particularly popular item called the Thor hammer, and the corresponding description page has the following URI:
http://www.harryshardware.com/products/tools/hammers/Thor.html
If Harry decides to put the Thor on sale, his Web application could invalidate the appropriate Web Cache entry with an invalidation response header containing a fully specified URI:
Oracle-WebCache-Invalidate: URI="http://www.harryshardware.com/products/tools/hammers/Thor.html"
If the original request specified the host name (www.harryshardware.com
) explicitly, the application could return an invalidation response header with a path-only URI:
Oracle-WebCache-Invalidate: URI="/products/tools/hammers/Thor.html"
If Harry decides to put all the hammers in his store on sale, his Web application could invalidate all Web Cache entries for hammers with an invalidation response header containing a fully specified URI directory:
Oracle-WebCache-Invalidate: URI_DIR="http://www.harryshardware.com/products/tools/hammers/"
If the original request specified the host name (www.harryshardware.com
) explicitly, the application could return an invalidation response header with a path-only URI directory:
Oracle-WebCache-Invalidate: URI_DIR="/products/tools/hammers/"
In the examples so far, we have not specified a synchronicity directive, so by default Oracle Web Cache would complete the invalidation before returning the response to the client.
If Harry wanted the example from Section 7.8.1.2 to proceed asynchronously, that is, if he did not want Oracle Web Cache to wait for the invalidation to complete before returning the response, his Web application could send an invalidation response header that looks like this:
Oracle-WebCache-Invalidate: SYNCHRONOUS=OFF, URI_DIR="http://www.harryshardware.com/products/tools/hammers/"
Notice that the response header above contained a fully qualified URI directory. If the original request specified the host name (www.harryshardware.com
) explicitly, the application could return an invalidation response header with a path-only URI directory:
Oracle-WebCache-Invalidate: SYNCHRONOUS=OFF, URI_DIR="/products/tools/hammers/"
Suppose that Harry wants to reduce the price of all TrueSaw saws but not the handsaws, just the power saws (for example, skill saws and chainsaws). His Web application could invalidate all the necessary entries with an invalidation response header that looks like this:
Oracle-WebCache-Invalidate: URI_DIR="http://www.harryshardware.com/products/tools/saws/";S_KEY="PowerTool"; S_KEY="TrueSaw"
Notice the addition of the S_KEY
directives to ensure the invalidation of only TrueSaw power saws.
Remember, when an invalidation response header contains multiple directives separated by semicolons, an Oracle Web Cache entry must match all directives for the invalidation to take place.
Notice also that the response header above contained a fully qualified URI directory. If the original request specified the host name (www.harryshardware.com
) explicitly, the application could return an invalidation response header with a path-only URI directory:
Oracle-WebCache-Invalidate: URI_DIR="/products/tools/saws/";S_KEY="PowerTool";S_KEY="TrueSaw"
Suppose that Harry sets up an additional site for selling large appliances (dishwashers, refrigerators, etc.). Suppose also that he defines this site using a path prefix of /products/appliances
. The following Table 7-6 are the site definitions for the Web site:
Table 7-6 Web Site Definitions
Scheme | Host | Port Number | Path Prefix |
---|---|---|---|
|
|
|
|
|
|
|
/ |
The first site pertains strictly to large appliances; the second site applies to everything else in Harry's store.
Suppose further that Harry changes the price for all KeepCold refrigerators and that the site definition for an incoming request pertains to Harry's appliance site; scheme http, host name www.harryshardware.com
, (optional) port 80 and path prefix of /products/appliances
. His Web application could invalidate all the necessary entries with an invalidation response header that looks like this:
S_KEY="KeepCold";S_KEY="Refrigerators"
Notice that the invalidation response header contains only search key directives; it does not contain a URI directory directive. When this happens, Oracle Web Cache forms an implicit URI directory from the site definition associated with the incoming request. In this case the implicit directory corresponds to:
http://www.harryshardware.com/products/appliances/
As before, with multiple directives separated by semicolons, an Oracle Web Cache entry must match all directives for the invalidation to take place.
The equivalent invalidation response header with an explicit, fully qualified URI directory would look like this:
Oracle-WebCache-Invalidate: URI_DIR="http://www.harryshardware.com/products/appliances/";S_KEY="KeepCold"; S_KEY="Refrigerators"
The equivalent invalidation response header with an explicit, path-only URI directory would look like this:
Oracle-WebCache-Invalidate: URI_DIR="/products/appliances/";S_KEY="PowerTool"; S_KEY="TrueSaw"
Suppose that Harry wants to upgrade his entire inventory of drills and wrenches. His Web application could invalidate all the necessary entries with a response containing the following invalidation response header:
Oracle-WebCache-Invalidate: URI_DIR="http://www.harryshardware.com/products/tools/drills/", URI_DIR="http://www.harryshardware.com/products/tools/wrenches/"
Remember, when an invalidation response header contains two consecutive invalidation specifications separated by a comma, an Oracle Web Cache entry only needs to match one invalidation specification for the invalidation to take place.
Notice that the response header above contained fully qualified URI directories. If the original request specified the host name (www.harryshardware.com
) explicitly, the application could return an invalidation response header with path-only URI directories:
Oracle-WebCache-Invalidate: URI_DIR="/products/tools/drills/", URI_DIR="/products/tools/wrenches/"
Suppose that Harry wants to put both the Thor hammer and all TrueSaw power saws on sale. His Web application could invalidate all the necessary entries with a response containing the following invalidation response header:
Oracle-WebCache-Invalidate: URI="http://www.harryshardware.com/products/tools/hammers/Thor.html",
URI_DIR="http://www.harryshardware.com/products/tools/saws/";S_KEY="PowerTools";S_KEY="TrueSaw"
Notice the use of both the comma and semicolon as separators. In this instance, the first directive consists of only the URI for the Thor hammer. The second directive consists of three invalidation specifications: the URI directory for saws and the search keys for Power Tools and TrueSaw tools. Semicolons take precedence over commas.
Notice also that the response header above contained a fully qualified URI and a fully qualified URI directory.
If the original request specified the host name (www.harryshardware.com
) explicitly, the application could return an invalidation response header with a path-only URI and a path-only URI directory:
Oracle-WebCache-Invalidate: URI="/products/tools/hammers/Thor.html"
URI_DIR="/products/tools/saws/";S_KEY="PowerTools";S_KEY="TrueSaw"
Returning to the example of Section 7.8.1.6, a Web application, alternatively, could invalidate all the necessary entries with a response containing two separate invalidation response headers:
Oracle-WebCache-Invalidate: URI_DIR="http://www.harryshardware.com/products/tools/drills/"
Oracle-WebCache-Invalidate: URI_DIR="http://www.harryshardware.com/products/tools/wrenches/"
The directives from two different invalidation response headers in the same response are treated as if they were separate directives in a single response header—that is, they are treated as if they were separated by commas in a single invalidation response header. Notice, too, the response headers contained a fully qualified URI directory. If the original request specified the host name (www.harryshardware.com
) explicitly, the application could return invalidation response headers with path-only URI directories:
Oracle-WebCache-Invalidate: URI_DIR="/products/tools/drills/"
Oracle-WebCache-Invalidate: URI_DIR="/products/tools/wrenches/"
To enable this feature:
Configure the HTTP response with the Surrogate-Key
response-header field as follows:
Surrogate-Key: search-key=("key" "key" "key" ...)
See Section 7.6 for a complete description of the Surrogate-Key
response-header field.
By default, Oracle Web Cache supports up to 20 search keys. To increase the limit:
Use a text editor to open the webcache.xml
file.
Locate the MAXSEARCHKEYSPERDOC
attribute in the SEARCHKEYOPTIONS
element:
<GLOBALCACHINGRULES> <SEARCHKEYOPTIONS ENABLE="YES" MAXSEARCHKEYSPERDOC="20"/> <ERRORPAGES>
Modify the value to larger value.
The following example shows a search key limit of 35.
<GLOBALCACHINGRULES> <SEARCHKEYOPTIONS ENABLE="YES" MAXSEARCHKEYSPERDOC="35"/> <ERRORPAGES>
Save webcache.xml
.
Specify the search key in the invalidation request using these methods:
For out-of-band invalidations:
Use the Search Keys section from the Advanced Content Invalidation page (Operations > Advanced Content Invalidation) of Oracle Web Cache Manager. See Section 7.7.2 for instructions on using Oracle Web Cache Manager.
Specify the OTHER
element in a manual XML invalidation request to use the ADVANCEDSELECTOR
element, and specify the NAME
and VALUE
attributes to use SEARCHKEY
and the search key value, respectively. See Section 7.5.1.
For ESI inline invalidations, specify the <esi:invalidate>
tag with the OTHER
element to use the ADVANCEDSELECTOR
element, and specify the NAME
and VALUE
attributes to use SEARCHKEY
and the search key value, respectively. See Section 11.4.6.
For response header invalidation, specify the S_KEY
option directive. See Section 7.8.
This section covers the following topics:
To invalidate objects in the cache, send an HTTP POST request from the invalidator
account through an invalidation listening port.
The invalidator
account is an administrator authorized to send invalidation requests. See Section 5.2 for further information about configuring password security.
Propagation of invalidation messages from one Oracle Web Cache server to another occurs in the following deployments:
Cache cluster with multiple Oracle Web Cache servers
Cache hierarchy whereby one Oracle Web Cache server acts as an origin server to another Oracle Web Cache server
In a cache cluster, administrators can decide whether to propagate invalidation messages to all cache cluster members or to send invalidation messages individually to cache cluster members.
When Oracle Web Cache propagates invalidation messages, the cache that received the invalidation request acts as the invalidation coordinator for that request. The coordinator propagates the invalidation messages to the other cluster members. The coordinator waits for responses from all cluster members. When the propagation completes, the coordinator returns a message to the sender that lists, for each cluster member, the cluster member name, the status of the invalidation request, and the number of objects invalidated.
If any cluster member cannot be reached, Oracle Web Cache returns an error message and does not propagate the invalidation messages.
During a cache cluster upgrade, you upgrade one cache cluster member at a time. The caches continue to respond to requests. However, because other cluster members have a different version of the configuration, the caches do not forward invalidation messages to those cache cluster members operating with a different version. Instead, if the requested object is not cached by that cache or by cluster members with the same version of the configuration, Oracle Web Cache forwards the request to the origin server.
When the cache cluster members are not running the same version of Oracle Web Cache, you can still invalidate objects, and you can propagate the invalidation to other cluster members, but the invalidation message must originate from the cache that is operating with the earlier version of Oracle Web Cache.
See the Oracle Fusion Middleware Upgrade Planning Guide for more information about upgrading Oracle Web Cache to 11g Release 1 (11.1.1), including information about upgrading cache cluster members
In a configuration with a hierarchy of Oracle Web Cache servers, a cache hierarchy, it is likely that content is cached on multiple servers.
Figure 7-2 depicts a distributed cache hierarchy. A central cache is located in the United States office, and a remote cache is located in the Japan office. While the central cache stores content from an application Web server, the remote cache stores content from the central cache. In other words, the central cache acts as an origin server to the remote cache in Japan.
The central cache uses the invalidator
account name and password of the remote or subscriber Oracle Web Cache server. The invalidation request specifies the objects to invalidate, as well as the site host name of the objects. The site host name is compared with the IP address of the cache from which the invalidation request was propagated. If there is a match, the cache processes the invalidation request. Otherwise, the request is rejected.
For automatic propagation of invalidation messages, Oracle Web Cache passes the encoded invalidator
password in the page request between the central and remote cache during the hierarchy registration process. This HTTP traffic is susceptible to network sniffing. If the network is unprotected and insecure, configure HTTPS ports as follows:
Disable the default HTTP port and configure an HTTPS port in its place for the central cache. See Section 5.4.2.
Disable the default HTTP port for invalidation and configure an HTTPS port in its place for the remote cache. See Section 5.5.1.
When an invalidation message is sent to the central cache to refresh content, the central cache automatically propagates the invalidation message to the remote cache in Japan to ensure consistency.
Figure 7-2 Invalidating Content in a Distributed Cache Hierarchy
To ensure that the central cache only invalidates its content, the remote cache checks the site host name specified in the invalidation message with the IP address of the central cache from which the invalidation message was propagated. If there is a match, the remote cache processes the invalidation request. Otherwise, the request is rejected. The site host name for the central and remote caches should be configured to be identical, making a mismatch unlikely.
See Section 10.2 for instructions on configuring a cache hierarchy.