Oracle9iAS Portal Developer Kit (PDK)
Configuring the Web Cache Sample Provider

Introduction

This document describes how to configure the Invalidation Caching sample that is included in the PDK-Java. Invalidation caching is a very flexible caching mechanism that combines the best features of expiry and validation caching.

Expiry caching causes content to be cached for a fixed period of time. If the source of the content changes, the change will only be reflected when the cached copy expires. This is a good strategy for static content, content that changes very rarely or content that changes at at a predictable time interval.

Validation, or ping-based, caching causes content to be cached, but each time the content is requested from the cache a request is sent to the originator of the content to determine in the cached content is still valid. If the content is still valid, then the cached copy is used, otherwise the originator generates a new, up-to-date, copy of the content. The new content then replaces the old or stale content in the cache. Even though the originator of the content has to be contacted with each request, performing a simple validation check is much faster then generating content and returning content. This caching approach is generally used where the content is dynamic or changes unpredicably.

Invalidation based caching is essentially expires based caching, with the added ability to "expire" or "invalidate" the contents of the cache at any time. Invalidation of cache content is usually triggered by some kind of "event" taking place.

For example, if you have a Calendar portlet that shows your appointments for the day, the content for the portlet could be generated once, the first time you show the calendar for that day. The content can remain cached until something happens to change your schedule for that day such as a new appointment being added, an existing appointment being deleted or the time of an existing appointment being changed. Each of these changes is an "event" that can be triggered by the application you use to maintain your daily calendar. When such an event takes place, your calendar application can generate an "invalidation request" that will invalidate any cached portlet content for the day that has changed. The next time you view a portal page containing your calendar portlet, the cache will not contain an entry for that day and so your web provider will be contacted to regenerate the new content with the modified schedule.

This is a very efficient way to cache content because the originator of the content, in this case your web provider, only gets contacted when new content needs to be generated, but you are not bound to a fixed regeneration schedule.

Oracle Web Cache

The Invalidation caching sample uses Oracle Web Cache to cache content for web providers. When using Web Cache, requests for content are sent via HTTP to the Web Cache and content is either returned from the cache or the HTTP request is forwarded to the originator of the content. When content is returned to Web Cache it is added to the cache before being returned to the requestor. Cache content is invalidated by sending invalidation requests directly to the Web Cache. PDK-Java uses the Java API for Web Cache (JAWC) to generate invalidation requests. This document describes how to configure Web Cache and use the invalidation caching sample that comes with the PDK-Java.

Not all requests that are sent to a Web Cache are cached. In order for the content to be cached, the content must include directives that tell Web Cache to cache the content. Usually Web Cache uses the URL associated with the request as the cache key, but you can specify additional keys by setting special HTTP headers, referred to as "surrogate control headers", on the response.

Invalidation Caching Sample

The sample provider contains a single portlet that displays the time the content was cached and includes a link to trigger an invalidation request. The first time a page request is made to the web provider via the cache, the response is cached. Subsequent requests for the portlet content will be fulfilled by returning content from Web Cache. When you click the link at the bottom of the portlet an invalidation request is generated by the provider that removes the portlet from the cache. The next request for the portlet will be forwarded to the provider and the provider will generate a new portlet with the current time.

Configuring Oracle Web Cache

For the invalidation sample to work properly it is assumed that an Oracle Web Cache instance has been configured in front of the web provider. The remainder of this document assumes you have read or have access to Web Cache documentation. This document does not attempt to explain how to install or configure Oracle Web Cache itself, just how to configure it so you can run the Invalidation Caching Sample.

Having installed Web Cache, set the following in the administration manager:

• Application Web Servers - set this to point to the host name and port of the web provider.
• Cacheability Rules - make sure that no cachability rules are set up that will cache provider content, content should be cached according to Web Cache surrogate control headers only.

Configuring the Provider

Follow these steps for successful operation of the sample portlet.

Enable invalidation caching

A flag is defined at provider servlet level to switch invalidation caching on. The flag is set in an initialization parameter inside the JPDK application configuration file, <j2ee_home>/applications/jpdk/jpdk/WEB-INF/web.xml, e.g:

    <!--
        Define the JPDK servlets and their parameters
    -->
    <servlet>
      <servlet-name>SOAPServlet</servlet-name>
      <display-name>SOAPServlet</display-name>
      <description>Extended Portal SOAP Server</description>
      <servlet-class>oracle.webdb.provider.v2.adapter.SOAPServlet</servlet-class>
      <init-param>
        <param-name>invalidation_caching</param-name>
        <param-value>true</param-value>
      </init-param>
    </servlet>
    <servlet-mapping>
      <servlet-name>SOAPServlet</servlet-name>
      <url-pattern>/providers</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
      <servlet-name>SOAPServlet</servlet-name>
      <url-pattern>/providers/*</url-pattern>
    </servlet-mapping>

If the flag is not defined here invalidation caching is switched off. The status of this flag may be checked by displaying the provider's test page. This can be found at:

http://<provider_hostname>:<port>/jpdk/providers/webcache

Define the Web Cache Invalidation Port

HTTP invalidation requests will be sent to the invalidation port of the web cache instance(s). A configuration file is used by JAWC to specify one or more Web Cache instances and their invalidation ports. For example:

<?xml version="1.0"> 
<webcache> 
    <invalidationConnection 
        host=cache.us.oracle.com
        port=4001
        authorization="invalidator:invalidator"/> 
</webcache>

More than one web cache may be defined in which case the same invalidation request will be made to each web cache in the configuration file, for example:

<?xml version="1.0"> 
<webcache>
    <connectionPool>
        <invalidationConnection1
            host=cache.us.oracle.com
            port=4001
            authorization="invalidator:invalidator"/>
        <invalidationConnection2
            host=cache.us.oracle.com
            port=4001
            authorization="invalidator:invalidator"/>
    </connectionPool>
</webcache>

Note: The tag names connectionPool, invalidationConnection1 and invalidationConnection2 are user defined. A template file is supplied in the directory:

<j2ee_home>/applications/jpdk/jpdk/WEB-INF/providers/webcache

JAWC finds this configuration file using the system property oracle.http.configfile. If OC4J is being used with Oracle9iAS, you need to add the following to opmn.xml.

<oc4j instanceName="<oc4j instance name>" numProcs="1" maxRetry="3">
    ....
    <java-option value="-Doracle.http.configfile=<location of cache.xml>" />
    ....
</oc4j>

The configuration file opmn.xml is located at <ias_home>/opmn/conf. If you are running OC4J standalone, you can specify the option in the command line you use to start OC4J

java -Doracle.http.configfile=<fully_qualified_filename> -jar oc4j.jar

Note: Since the location of the cache configuration file is defined as a system property, only one cache may be defined per server instance. It is not possible to have two different web provider instances behind separate web cache configurations.

Configure the Provider

Using a combination of page level tags in the provider's definition file, portlets can be set to be cached automatically by the JPDK. The maximum time for which the page will be cached will be the minimum of the following:

• - Maximum expiry time from portal - defined in the cache tab of the global settings page
• - Web provider default (24 hours) if no maximum expiry time is specified by portal
• - The time in minutes of the <pageExpires> tag, if present

So the following snippet from the provider.xml for this sample specifies that this portlet will be cached for up to 5 minutes.

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>1</id>
      <name>WebCacheInvalidation</name>
      <title>Web Cache Invalidation Sample</title>
      <description>This demonstrates the use of Oracle Web Cache with portlets</description>
      <timeout>10000</timeout>
      <timeoutMessage>Timed out..</timeoutMessage>
      <showEdit>true</showEdit>
      <showEditToPublic>true</showEditToPublic>
      <showEditDefault>true</showEditDefault>
      <showPreview>false</showPreview>
      <acceptContentType>text/html</acceptContentType>
      <defaultLocale>en.US</defaultLocale>
      <renderer class="oracle.portal.provider.v2.render.RenderManager">
         <contentType>text/html</contentType>
         <renderContainer>true</renderContainer>
         <autoRedirect>true</autoRedirect>
         <showPage class="oracle.portal.provider.v2.render.http.ResourceRenderer">
            <resourcePath>/htdocs/invalidation/invalidation1.jsp</resourcePath>
            <pageExpires>5</pageExpires>
            <useInvalidationCaching>true</useInvalidationCaching>
         </showPage>
         <editPage class="oracle.portal.sample.v2.devguide.invalidation.InvalidationEditRenderer"/>
      </renderer>
      <personalizationManager class="oracle.portal.provider.v2.personalize.PrefStorePersonalizationManager" >
         <dataClass>oracle.portal.sample.v2.devguide.invalidation.InvalidationPersonalizationObject</dataClass>
      </personalizationManager>
   </portlet>

Note: The pageExpires tag is also used for normal expiry based caching. These two forms of caching are mutually exclusive. Invalidation caching takes place in a Web Cache instance that is local to the web provider, pages stored using expiry based caching are cached in the middle tier of Oracle9iAS Portal

Registering the Web Provider

Having set up and started the cache instance and the web provider, register the web provider as usual, setting the URL host name and port number to point to the Web Cache instance. For example,

http://<cache_instance_name>:<cache_port>/jpdk/providers/webcache

Troubleshooting

Errors that occur during execution of the sample may be seen in the web server file, <j2ee_home>application-deployments/jpdk/application.log. Here is a list of the most likely errors that may be seen, along with possible solutions:

Error: The cached portlet content is not being invalidated but the portlet is working

Cause/Action:

• Confirm that invalidation caching is enabled, see here.
• Check the log to confirm that requests are being sent.
• Make sure that there are no cachability rules defined in the cache that are causing pages to be incorrectly cached.
• useInvalidationCaching tag not set in provider.xml, see here.

Error: oracle.net.http.HttpConfigurationException: "oracle.http.configfile" not found in system properties at ...

Cause/Actions:

• The cache configuration system property has not been set, see here.

Error: oracle.net.http.HttpConfigurationException: File not found: at oracle.net.http.HttpConnectionFactory.getConfigDoc

Cause/Action:

• The cache configuration system property has been set but does not point to a valid file, see here.

Error: java.net.ConnectException: Connection refused: no further information at java.net.PlainSocketImpl.socketConnect...

Cause/Action:

• For some reason a connection to the cache invalidation port can not be made. Could be due to the cache instance not being turned on or an error in the cache configuration file.