Oracle Application Server Portal Developer Kit (PDK)
Configuring the Web Cache Sample Provider

Introduction

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

Expiry-based 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 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 if 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 unpredictably.

Invalidation-based caching is essentially expiry-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-based 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-based 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-Based 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 are 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 is forwarded to the provider and the provider generates 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-based 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 the surrogate control headers generated by the Provider in its response.

Configuring the Provider

Follow these steps for successful operation of the sample portlet.

Enable Invalidation-Based Caching

A flag is defined at provider servlet level to switch invalidation-based caching on. The flag is set in an initialization parameter inside the JPDK web application deployment descriptor, web.xml (found in $IAS_HOME/j2ee/<OC4J instance>/applications/jpdk/jpdk/WEB-INF/web.xml). For example:

    <!--
        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-based 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

Note: If you are using an Oracle Application Server Installation Type where PDK-Java was automatically pre-installed (e.g. a "Portal and Wireless" type installation), you should find that Web Cache invalidation settings have already been preconfigured in $IAS_HOME/portal/conf/cache.xml. If this is the case, you can safely ignore the instructions in this section and proceed to the next section.

1. First, determine the username and password for the invalidation port(s) of the Web Cache instance(s) associated with your application server, and use the provided oracle.webdb.provider.v2.cache.Obfuscate Java utility to convert the username and password into an obfuscated string of the format required by the JAWC API. In a default Oracle Application Server installation, the username for the invalidation port is usually "invalidator" and the password is usually the same as the "ias_admin" administrator's password. For example, if Oracle Application Server was installed under the path "D:\as904", the invalidation port username was "invalidator", and the password was "welcome", you would run the following command:

   D:\as904\jdk\bin\java -classpath D:\as904\portal\jlib\pdkjava.jar oracle.webdb.provider.v2.cache.Obfuscate invalidator:welcome

   If successful, the command should print a Hexadecimal string such as the following:

   0510198d5df8efd5779406342be2528aa0cccb179ea6b77baf49f019f5075a3a11

Note:
• The above assumes that pdkjava.jar is present in $IAS_HOME/portal/jlib and jawc.jar is present int $IAS_HOME/webcache/jlib, as required by the PDK Java installation guide.
  
• If using a standalone OC4J installation, you would obviously need to substitute in the path to the java executable in an external Java 2 SDK installation.
2. Now, use this information to create a JAWC configuration file, cache.xml, which specifies one or more Web Cache instances and their invalidation ports. For example:

   <?xml version="1.0"> 
   <webcache> 
       <invalidation
           host=cache.mycompany.com
           port=4001
           authorization="0510198d5df8efd5779406342be2528aa0cccb179ea6b77baf49f019f5075a3a11"/> 
   </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.mycompany.com
               port=4001
               authorization="0510198d5df8efd5779406342be2528aa0cccb179ea6b77baf49f019f5075a3a11"/>
           <invalidationConnection2
               host=cache.mycompany.com
               port=4002
               authorization="0510198d5df8efd5779406342be2528aa0cccb179ea6b77baf49f019f5075a3a11"/>
       </connectionPool>
   </webcache>
   

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

   $IAS_HOME/j2ee/<OC4J instance>/applications/jpdk/jpdk/WEB-INF/providers/webcache

3. JAWC finds this configuration file using the system property oracle.http.configfile. To set this system property for an OC4J instance within an Oracle Application Server install, simply add and appropriate line to the oc4j.properties file for the particular OC4J instance in which the JPDK is installed (e.g. $IAS_HOME/j2ee/<OC4J instance>/config/oc4j.properties) and then restart that OC4J instance. For example:

   oracle.http.configfile=<fully_qualified_filename>

   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 tags in the provider's definition file, you can activate automatic invalidation-based caching for an entire portlet or some of its pages. To turn on automatic invalidation-based caching, you need to declare <useInvalidationCaching>true</useInvalidationCaching>, either at the level of the individual pages you want to use invalidation-based caching with, or at the renderer level, to indicate that invalidation-based caching should be activated for all pages.

If your portlet supports customization (via the Edit or Edit Defaults modes) you may also want to declare <autoInvalidate>true</autoInvalidate> for your renderer. This will cause all the cached content for the portlet to be automatically invalidated when the OK or Apply button is clicked in Edit mode, thus causing new markup to be generated based on the customized settings.

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 and should be automatically invalidated on customization.

   <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>40</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>
         <autoInvalidate>true</autoInvalidate>
         <showPage class="oracle.portal.provider.v2.render.http.ResourceRenderer">
            <resourcePath>/htdocs/invalidation/invalidation1.jsp</resourcePath>
            <useInvalidationCaching>true</useInvalidationCaching>
            <pageExpires>5</pageExpires>
         </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-based 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 OracleAS 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-based 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.