Caching techniques in WebSphere Portal

 

+
Search Tips   |   Advanced Search

 

WebSphere Portal uses component state to optimize cache utilization and exploitation. The portal stores component responses in caches scoped to the component state. The valid lifetime and scope of application responses and static content may differ, although applications typically have a shorter lifetime and smaller scope than static content pages.

WebSphere Portal uses caches at multiple levels. WebSphere Portal's combined caching techniques, such as adaptive page caching, portlet caching, and object caching, enable Web sites that have both static and dynamic parts with high performance and improved scalability.

There is a tradeoff between the use of these different caches for performance gain in case of a cache hit, and the likelihood of cache hit occurrences. Caching a complete portal page markup by using adaptive page caching yields the best performance improvements per cache hit, but a cache hit occurs only if the requested page is identical to the cached response. For the page to be identical, all markup fragments generated by the components that make up the page need to be identical.

Decomposing the complete page into component fragments increases the chance for cache hits. With portlet caching, the portal aggregates cached portlet fragments into complete pages before responding to a request. In this case, only the requested portlet fragment needs to be identical to the stored response, which increases the likelihood of cache hits but does not provide the same performance gain per cache hit (aggregation still needs to happen on the portal). Object caching can achieve the highest rate of cache hits; data stored in the cache is valid as long as the backend does not change this data. In this case, the portlet renders the markup fragment based on the cached data, and the portal aggregates the markup into a complete portal page.

The differences in content lifetime and the scope of static content and dynamic applications can also be mitigated by heterogeneous system infrastructures, in which static content and applications are hosted in separate environments; static content is provided by HTTP servers or content management systems, and applications are hosted by appserver or portal server environments. The user experience hides from the end user the fact that two different sites are actually running. Applications and static content are linked back and forth, enabling site visitors to seamlessly transition between the two content sets. Disadvantages to this approach are apparent in the increased complexity and maintenance effort.

This article describes a sample usage scenario for caching in WebSphere Portal and provides details on the WebSphere Portal caching architecture, together with possible ways to exploit these capabilities within your portlets and portal sites.

Our sample scenario involves a company intranet portal site that provides both static content and dynamic applications. Let's take a look at how this portal site is optimized for performance and scalability, and how it makes use of the caching functionality in WebSphere Portal V5.1.

Figure 1. Example portal content topology

Figure 1. Example portal content topology

The portal site consists of two main areas, which also differ in content type:

  1. News -- Contains two levels of pages made up of portlets that provide employees with news articles on technologies, products, and customers. The news articles displayed by these portlets are provided by a content management system. This content is updated with low frequency and is shared for many users, and so content in the News area is categorized as static content .

  2. MyWork -- Contains pages made up of portlets used by employees during the work day to collaborate with their colleagues. These portlets integrate with the collaboration infrastructure that the company established to improve efficiency for their employees. This content changes frequently and is comprised of dynamic applications .

The following sections describe the design principles applied to these two areas to make the most efficient use of caching.

 

News: Static content

The News area of our portal site contains pages with portlets that provide static content delivered by a content management system. This area of the portal behaves like a static Web site, but provides employees with a single working environment integrated with their collaboration applications. All the pages in this area of the portal are provided to all intranet portal users; users do not personalize these pages and the content on these pages is the same for everyone, which is typical for a static Web site. The site content changes with different frequencies; news articles for the Tech page are provided every minute, while content to the Products pages is provided only in the morning.

Content portlets provide different views. For example, some portlets display a list of recent articles with links, and if a user follows one of these links, the corresponding article could be displayed on the same page within the same portlet, or in a special article display portlet.

Each of these pages contains a navigation area that lets users navigate within the portal. This navigation area is identical for all users. All users can share the markup for these pages delivered from caches.

The set of available pages within the MyWork area is different for each user, and so the navigation to these pages should not be included in the cacheable pages. In our portal site this is achieved by providing direct navigation to all pages within the news area of the portal, but no direct navigation to pages within in the MyWork area. To access pages in the MyWork area of the portal, users navigate first to the MyWork area main page, which is accessible directly from all pages within the News area, and then within the MyWork area directly from page to page.

WebSphere Portal V5.1 enables projecting these pages into caching proxies. Proxies are located between browsers and servers. Proxies receive requests from browsers and request content from servers on behalf of these clients. Caching proxies are proxies that cache server responses. On subsequent requests, caching proxies send matching responses back to clients directly out of their cache. By using caching proxies, each page would be delivered from the portal only once and then reside within the cache (until the content becomes invalid). Subsequent requests to the same page within the lifetime of the content are responded to directly by the caching proxy, and thus do not generate load on the portal server.

 

MyWork: Dynamic application

The MyWork area of the portal site contains portlets used by employees for collaborating in their day-to-day business. This area of the portal is optimized for dynamic applications. Portal pages are always generated for specific user requests to ensure that the most recent application data for the current user is provided by the portal.

In our sample scenario, some collaboration applications are provided to all employees, while other collaboration applications are only provided to selected groups of employees within the company. The navigation within the MyWork area should present users with only those navigation links they are authorized to access; if a user does not have access to a page, that page does not show up in the navigation. The portal generates navigation individually for each user to reflect the user's permissions.

Pages in the MyWork area can be personalized by WebSphere Portal users by adding portlets, removing portlets, or rearranging existing portlets on a page to adapt the portal to the way they work most efficiently.

In the MyWork area, pages are not shared by multiple users. Caching these pages in a page response cache that is shared by multiple users would quickly consume the cache memory but would not result in many cache hits. Storing privately scoped pages in a browser cache is optimal with regard to memory utilization in the cache, as well as in its location as close as possible to the end user.

Page structures or page content that change with each user request impedes the use of page caches for storing page responses. More advanced caching techniques are required to improve page performance and reduce system utilization. Within dynamically changing pages, typically not all portlet fragments change with each request; some stay unchanged over multiple page requests and can therefore be cached between requests for one user or for multiple users. Markup fragments within portlets are generated from data maintained by the portlet. Part of this data may change with each request, resulting in different fragments being delivered for each request, while other parts of data may stay unchanged across a series of requests that always deliver the same markup. Structuring the data according to its change characteristic enables identification of data elements that stay constant across multiple requests or across multiple users. Data caches can be used for caching data with change rates that are below the page request rate.

WebSphere Portal provides built-in caches that can be used by portlets to improve response times for portlet fragment requests, providing portlet caches that cache portlet markup. The expiration cache configuration, as defined in the JSR 168 specification (see Resources ), provided in the portlet's deployment descriptor, defines the behavior of the portlet cache for each portlet. Additionally, portlets running in WebSphere Portal can use object caches to cache data objects that are shared across page requests of a single user, or across page requests performed by different users.

 

Caching architecture in WebSphere Portal

Here we will discuss the extended caching architecture in WebSphere Portal V5.1. Figure 2 describes the caching capabilities of WebSphere Portal on different levels as a request flows from the user's browser to the backend system. This infrastructure is defined in compliance with the caching infrastructures within the HTTP specification (see Resources ) and is described here in a simplified form.

 

Figure 2. End-to-end caching in WebSphere Portal

Figure 2. End-to-end caching in WebSphere Portal

Requests originate from the browser (beginning at the left in Figure 2):

 

Adaptive page caching

In traditional thinking, a general assumption about application servers is that there is no way that dynamically generated pages can ever be cached outside of the appserver. It is also assumed that a possibly existing caching infrastructure in the form of proxy servers or browser caches could never be leveraged. In this traditional approach, each incoming request requires application server resources to calculate a proper response every time.

With IBM's patented technology of adaptive page caching WebSphere Portal breaks these boundaries and offers the opportunity to cache dynamically generated pages in so-called remote caches, provided all the components a page consists of have signaled that they are cacheable. The advantage of this soon becomes clear: for such a cacheable page, a roundtrip to the portal server is no longer required after the first generation of that page. The performance of a complete portal infrastructure can be significantly improved if a good number of visited pages can be served from caches. Imagine pages that contain more or less static content in each of its portlets, or that show only different known views of a portlet (such as a news portlet), all of which are addressable by a specific URL. (The latter case can be implemented with render links for its different views; see above .)

WebSphere Portal can refer to a complete view of a page via the URL that is associated with it; this feature is enabled in WebSphere Portal by encoding the so-called navigational state into the URL. With this feature, cached pages can be accessed from the cache also via the URL. If the server side state of a portal resource that was once required to generate the markup for a specific page changes, this page needs to be regenerated, and thus the cached view becomes invalid. Therefore, there is a need to tell a cache how long a rendered view of page remains valid. Portlets need to publish such cache information as a contribution to the overall cache information on the page where the portlet appears. Pages with such portlets on it may be a good candidate for being stored and served from caches.

However, the advantage is not completely free. Resources maintained by WebSphere Portal need to be properly administered. Additional information needs to be provided for some of the components making up pages to get the most benefit out of this technology.

 

Remote caches

For the purpose of this article, the term remote cache refers to a cache located outside of the WebSphere Portal JVM process that can also be located outside the machine where WebSphere Portal is running. A remote cache is able to cache complete responses for a requesting URL. The only way to address such entries in the cache is the request URL. Thus, the completely rendered markup for a generated page can potentially be found in a cache.

Generally speaking, WebSphere Portal enables the usage of any implementation of a remote cache which follows the specification of HTTP 1.1 caching features (see Resources ) to better leverage the caching infrastructure. The HTTP 1.1 specification offers to invalidate cache entries (in the context of this article, this equates to remote caches) using specific HTTP request types only. Since WebSphere Portal should not have complete knowledge about the remote caching infrastructure it is running in, it cannot make use of this approach to invalidate individual cache entries. The only invalidation mechanism that WebSphere Portal uses for remote caches is expiration timeout .

Two different notions of remote caches originally introduced by the HTTP 1.1 specification need to be differentiated:

Both kinds of caches can successfully cache pages only if they are able to evaluate additional cache information that is sent along with the WebSphere Portal server response. The HTTP 1.1 specification defines such response headers, and explains how to handle a specific cached item.

Figure 3. Remote caches

Figure 3. Remote caches

WebSphere Portal provides this information in its generated responses in a way that best exploits the cache features that are potentially available in remote caches. Naturally, two informational items are required in these response headers to let caches know how to deal with a generated response markup:

The relevant HTTP 1.1 headers that will be set by WebSphere Portal for its responses in respect to caching in remote caches are:

(If there is doubt about the values provided in these response headers, they can be made visible with a tool that either acts like a proxy, sitting between the WebSphere Portal infrastructure and the browser, or is implemented as a plug-in to the browser. See Resources for more information.)

 

Contributors of cache information

How does WebSphere Portal decide whether a rendered page is actually cacheable in a remote cache? What data is required data to perform such a calculation?

To achieve this caching, WebSphere Portal visits all necessary components that make up a completely rendered page and gathers and aggregates the information those components can contribute. This also means that each component must contribute the cache information about itself if the best caching ability for such pages is to be achieved. Additionally, WebSphere Portal maintains global maximum values to limit the caching values; for example, the maximum cache expiration time, or the time to switch off caching in remote caches completely.

Figure 4. Aggregating caching information

Figure 4. Aggregating caching information

As a consequence, an administrator must provide this information in his portal setup, and a portlet developer can also add the information to the deployment descriptor and to the code of the portlets to be implemented. In case the components do not provide any of this information, WebSphere Portal relies on global default values for each of the components. The settings and algorithms around global default values are explained later .

Table 1 provides an overview of contributors and contributed data for caching in remote caches. This data is required to calculate the overall caching information.

 

Table 1. Contributors of caching information

Portal resource Cache scope (shared or non-shared) Cache expiration time (in seconds) Ignore access control in caches (true or false)
Portal (global settings) X X
Portal page X X X
Theme X X
Portlet definition X X
Portlet window X X

Contributors of caching information, as listed in the table, are the:

The ignore access control in caches setting was introduced to make sure that no pages are stored in a cache if the information published on such a page is of a sensitive nature with regard to security. If fully rendered pages are stored in shared caches, there is the possibility that users who do not have access permissions to that page could still guess the URL of such a page and load its contents from the cache. A remote shared cache typically does not provide any security mechanisms by default. In cases where this set of circumstances is really a concern, this setting must be set to false to ensure that such sensitive pages are never cached in a remote shared cache, making sure that access to information contained on such pages cannot be obtained by guessing URLs.

The portlet windows can contribute information for remote caches at render time, as they are enabled to perform some calculations based on their own internal knowledge and publish this information dynamically. This WebSphere Portal feature makes it possible for several views of a single portlet are cacheable with differing options. The portlet window itself can decide at render time whether its output is cacheable or not, and under which cache scope.

If a portlet window does not publish any information of this kind at render time, WebSphere Portal falls back to the cache-related information provided by either the portlet definition or (if none is provided by the portlet definition) the global default values.

For performance reasons, an additional (redundant) setting was introduced in the JSR 168 container that tells the container whether a portlet will provide remote cache info at render time or not. This information is available to WebSphere Portal through the deployment descriptor, so it is possible to reduce the calculation effort.

For legacy portlets, WebSphere Portal makes uses of the global default values. Legacy portlets do not contribute to the cache information for remote caches either through the deployment descriptor or at render time.

For unauthenticated pages, WebSphere Portal V5.1 maintains compatibility with earlier releases, in which these pages were cacheable and administered with only globally working parameters.

 

Calculation of cache information

All the cache information for remote caches contributed by each of the components that comprise a page needs to be aggregated and merged into two overall values for a rendered page: cache scope and cache expiration time . WebSphere Portal attaches these values to a portal response concerning caches. Remember that due to the HTTP 1.1 specification, WebSphere Portal can attach only one set of values of the chosen HTTP headers for this purpose in a response.

The general idea for the calculation is to use the minimum for both cache scope and cache expiration time to make sure that:

  1. The expiration does not exceed any of the values contributed from the components.

  2. The cache scope is correctly chosen as contributed by the components.

While the minimum of several expiration time values is easy to determine, the minimum of two possible cache scope values is less obvious.

Since the cache scope value of "non-shared" is more restrictive than "shared," the value "non-shared" is determined to be a smaller value than "shared," very similar in the way a small expiration time more restrictive than a greater one.

For portlets, there is a special mechanism that applies to the contributed value of the cache expiration and cache scope. The values contributed by the portlet window always have precedence over the value contributed by the portlet definition. This means that independent of being a higher or a lower value than that of the portlet definition, the value of the portlet window will always be used if it is contributed. If no value for either cache expiration or cache scope is contributed by the portlet window, the value from the portlet definition will then be used as the contributing value of the portlet.

(The next section discusses the default behavior that can occur if a value is not contributed by a component.)

If ignore access control in caches is set to false for a portal page, a completely rendered page will not be cacheable at all. To make sure that a portal page is not cached in a remote cache, the cache expiration either for the portal page or globally for the portal needs to be set to 0.

Global default values and global maximum values WebSphere Portal V5.1 also introduces global default values and maximum values for caching, which give WebSphere Portal capabilities to provide cacheable pages in some cases where no caching information is published by the components that make up a rendered page.

Global default and maximum values are calculated from settings provided in a property file (see How WebSphere Portal contributes global values of cache information ) and from determining whether a request is authenticated or unauthenticated; the latter information is transient and has no persistent representation in a file or database.

 

Figure 5. Flow of global RemoteCacheInfo calculation: Expiration

Figure 5. Flow of global RemoteCacheInfo calculation: Expiration

 

Figure 6. Flow of global RemoteCacheInfo calculation: Scope

Figure 6. Flow of global RemoteCacheInfo calculation: Scope

Global maximum values are contributed to the overall cache information for a rendered page. It has equal rights of other cache information contributors, such as portlets, portal pages, and themes.

Global default values are used whenever a portlet, a portal page, or a theme does not contribute any cache information .

 

Portlet caching

The adaptive page caching approach enables the caching of complete pages in remote caches. Complete pages, however, typically consist of the aggregation of many portlets. Each individual portlet produces a markup fragment that is then combined with the fragments of the other portlets on the page to produce the final markup of that page. The individual markup fragments produced by portlets, however, are also potentially cacheable. In this section, we will explain how WebSphere Portal exploits the fragment cache to cache individual portlet fragments (see Example application for portlet caching ).

The fragment cache supports two primary types of cache instances: object cache instances and servlet cache instances .

While object caching provides a Javaâ„¢ API to cache an arbitrary Java object (see Object caching and state handling ), the servlet caching feature caches the output of servlet request dispatcher includes. Portlets are invoked via the request dispatcher by the portlet container, so the portlets' markup is eligible for caching as it is for the markup of servlets. Due to the aggregated nature of the portlets and the fact that the portlet markup depends on the navigational state for that portlet -- that is not part of the URL passed to the request dispatcher -- the portlet container needs to perform additional steps when caching the portlet markup:

The approach of fragment caching, however, assumes that the cached markup is context independent; otherwise, markup from a cache that has been generated in a previous context could not be aggregated with markup in the current context.

WebSphere Portal makes sure that markup fragments that are dedicated to be cached in a fragment cache contain context independent URLs. This is achieved by applying a different URL generation mechanism for cached fragments than for non-cached fragments. Fragments that are retrieved from a cache to be aggregated into a portal page then need to be made aware of the current page context. WebSphere Portal applies a URL rewriting mechanism for cached fragments to make sure that the URLs that are contained within this fragment contain the correct navigational state context of the aggregating page.

Figure 7. Portlet caching

Figure 7. Portlet caching

Portlets can advertise their ability to be cached in the fragment cache by setting their expiry time in their portlet.xml descriptor (see Portlet descriptor example ) To use the fragment caching functions, servlet caching needs to be activated in the Web Container section of WebSphere Application Server administrative console (see Portlet descriptor example ). WebSphere Application Server also provides also a cache monitor enterprise application (CacheMonitor.ear), which is very useful for visualizing the contents of the fragment cache.

 

Object caching and state handling

Adaptive page caching and portlet caching provide powerful means for reducing the rendering time by avoiding the potentially time-consuming markup generation of portlets. An efficient use of the portlet programming model (JSR 168: Portlet Specification, see Resources ) and the exploitation of WebSphere Portal's state handling concepts can also significantly reduce the time spent on markup generation for those cases where the markup still needs to be rendered.

This section introduces these state handling concepts and explains how the DistributedMap provided by WebSphere Application Server can be used to keep the session size small and to improve both response time and scalability. An example application is also provided that illustrates the practical application of theses concepts (see Appendix E ).

State handling

WebSphere Portal V5.1 enhances its implementation of the JSR 168 programming model. which supports the following types of states that a portlet can make use of:

Figure 8. WebSphere Portal states

Figure 8.  WebSphere Portal states

Even as early as the design phase of a portlet, it is important to distinguish between the states a portlet manages and encode them appropriately. In particular, navigational state and session state should be designed to be orthogonal, since it is possible to access the same session in combination with different navigational states. This typically happens if the user uses the back button, invokes a bookmark that contains portlet specific state, or opens a new browser window that shares a session with the original window and navigates in both windows independently.

Each link that a portlet generates falls into one of two categories:

For an example of the application of these concepts see Appendix E .

 

Object caching

During the generation of markup or during the execution of an action, it is often necessary to access a slow backend or perform some type of time consuming calculation. The result of such an operation should be cached to enable subsequent requests to execute faster. The portlet session, however, is not the correct place to cache this information because it conceptually consists of non-recreatable data. The portlet container (and in the end the appserver) makes sure that session state is preserved across node failure in a clustered environment and even might get replicated across the cluster. This management requires resources. Furthermore, cached data in the session cannot be discarded automatically (that is, in case of low memory conditions) before the end of the lifetime of the session.

It is important to distinguish session state from cached state. Portlets should use a cache rather than the session to keep cached data to enhance performance while saving system resources. All data that is recreatable from navigational state, session state, or backend state is eligible for caching. The advantage of a cache vs. the session is that data in the cache may be discarded due to low memory events, a timeout, and so on, and that the caching infrastructure does not need to spend as many resources guaranteeing the availability of the cached data as it would for session data.

WebSphere Application Server provides a powerful means with the DistributedMap interface that can be used by any Web application to store arbitrary Java objects. Using the DistributedMap interface, which is a simple interface for the dynamic cache, J2EE applications and system components can cache and share Java objects by storing a reference to the object in the cache. DistributedMaps are J2EE resources managed by the appserver that can be accessed via a Java Naming and Directory Interface (JNDI) lookup from Web applications. Portlets should do this lookup during their initialization phase and keep a reference to the cache instance as an instance variable of the portlet. It is possible to configure more than one DistributedMap instance on one server, each with different JNDI names and cache characteristics. The most important characteristics are the cache size, default timeout values for cache entries, and the sharing policy. For more information on the management and interface of the DistributedMap see the WebSphere Application Server Information Center in Resources .

The portlet must be coded such that it anticipates a cache miss; that is, it must not rely on the fact that cached information is available. In particular, it is not possible to use the cache as a means to share data between the action phase and the render phase of the request cycle of portlets. Due to low memory conditions or administrative modification of the cache size via the admin console, the cache might (temporarily) be configured such that it never caches data at all. The portlet needs to be especially prepared to recreate information during the render phase (for example, by accessing a backend). From a performance perspective, it is advantageous to do as much of the required backend interaction during the render phase as possible, since other portlets on the same page might be rendered in parallel. In the ideal case, the latency of the rendering of one page is the maximum latency over all portlets on that pages in contrast to the sum of latencies if all portlets were rendered sequentially.

When using DistributedMap, portlets need to make sure that they use keys into this cache that do not clash with keys potentially being used by other portlets on the same cache. There are several ways to ensure this:

For an example of the application of these concepts, see Appendix E .

Besides caching data, the DistributedMap also enables individual keys to be explicitly invalidated. An instance of the map can be configured to be shared or non-shared. A shared map will try to keep the content of map instances on different nodes on a cluster in sync, whereas non-shared caches contain node-specific data. Invalidations on caches, however, are always distributed across a cluster. For performance reasons, it is advantageous to configure caches to be non-shared and to explicitly invalidate cache entries. Due to the nature of portlet interaction, the invalidation of cache entries is typically done during the action phase, whereas access and population of the cache is mostly done during the render phase.

 

Conclusion

IBM WebSphere Portal V5.1 enables you to run an entire Web site -- including dynamic applications and static content -- from a single portal. Caching can be used on multiple layers within your portal. The newly introduced concept of adaptive page caching supports caching of complete portal pages. The portal automatically determines which aggregated pages can be cached and sets page headers that enable static parts of your site to be projected into caches in reverse proxies or browsers. After initial access, these pages are served from those caches at the same speed as conventional static Web sites. Highly dynamic parts of the site will automatically be rendered in pages indicating lifetime and cache scope appropriate for the component markup fragments that are contained on those pages.

For partially dynamic pages, WebSphere Portal supports portlet caching so that only the dynamic parts of such pages provided by interactive portlets, or portlets showing real-time content, have to be rendered on a per-request basis, while the static or semi-static parts of the page rendered by portlets showing content valid for a certain amount of time after initial rendering are fetched from the portlet cache until they expire.

Within portlets implementing interactive applications which must be rendered per request, object caching can be used to optimize performance of each single render operation.

Adaptive page caching, portlet caching, and object caching, together with various internal performance enhancements that were implemented across the WebSphere Portal code base, will enable you to run high performance Web sites on WebSphere Portal 5.1 entirely, reducing total cost of ownership and providing better manageability, compared to hybrid approaches built from a portal product, plus a conventional, differently managed Web server.

 

Appendices

All sample code provided is for illustration only, and is provided AS IS, without warranty of any kind.

The Appendix sections that follow provide further technical details on how each affected component may contribute cache information relevant to remote caches. You can also use this information as a to-do list of tasks that need to be done by an administrator or portlet developer to enable a set of pages in WebSphere Portal for caching in remote caches.

 

Appendix A: Components contributing values for remote caching

 

How portal pages contribute cache information

The cache scope and cache expiration time value, as well as the setting for ignoring access control in caches, can be set in the graphical user interface of WebSphere Portal with the edit page properties administration function of a portal page. It is also possible to set these values through an XML access script as shown in Listing 1:

Listing 1



<!-- Page with cache scope "shared" and cache expiration time 30 seconds --><content-node 
   action="update" 
   uniquename="wps.xmplPage" 
   ordinal="last" 
   content-parentref="parentPage" 
   themeref="xmplTheme" 
   active="true" 
   allportletsallowed="false" 
   create-type="explicit" 
   type="page"
>
   <supported-markup markup="html" update="set"/>
   <localedata locale="en">
   <title>Example Page</title>
   </localedata>

   <parameter name="remote-cache-scope" type="string" update="set">SHARED</parameter>
   <parameter name="remote-cache-expiry" type="string" update="set">30</parameter>
   <parameter name="IgnoreAccessControlInCaches" type="string"update="set">TRUE</parameter>


   <!--more content node stuff should come here -->
   . . .
   
</content-node>


The parameter names remote-cache-scope, remote-cache-expiry, and IgnoreAccessControlInCaches are reserved terms used for the purpose of providing this information.

 

How themes contribute cache information

The cache scope and cache expiration time value cannot be set in the graphical user interface of WebSphere Portal for themes. It is possible to set these values through an XML access script as shown in Listing 2:

Listing 2



<!-- Theme with cache scope "shared" and cache expiration time 40 seconds -->
<theme 
   action="update" 
   active="true" 
   objectid="xmplTheme" uniquename="wps.theme.example">  

   <parameter name="remote-cache-scope" type="string" update="set">SHARED</parameter> 
   <parameter name="remote-cache-expiry" type="string" update="set">40</parameter>

</theme> 


The parameters remote-cache-scope and remote-cache-expiry are reserved terms used for the purpose of providing this information.

 

How portlet definitions contribute cache information

Portlet definitions will provide the cache information through their deployment descriptors. Only standard portlets following the JSR 168 specification are supported for publishing this information. For IBM legacy portlets, WebSphere Portal assumes the global default values which are still helpful for unauthenticated pages.

Listing 3 shows a deployment descriptor (portlet.xml) of a standard portlet which publishes the cache information:

 

Listing 3



<?xml version="1.0" encoding="UTF-8"?>
<portlet-app 
   id="XmplPortletApp"
   xmlns=http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
   version="1.0"
   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
   xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd
   http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" >
<!-- Example Portlet -->
   <portlet>
      <description>
         Remote Cache Information Example Portlet 
         with cache expiration of 100 seconds.
      </description>
      <portlet-name>Example Portlet</portlet-name>
      <display-name>Example Portlet</display-name>
      <portlet-class>com.ibm.wps.example.dzierzon.rci.RemoteCacheInfoSetterPortlet</portlet-class>

      <expiration-cache>100</expiration-cache>

      <supports>
         <mime-type>text/html</mime-type>
         <portlet-mode>edit</portlet-mode>
         <portlet-mode>help</portlet-mode>
      </supports>
      <supported-locale>en<>/supported-locale>
      <portlet-info>
         <title>Example Portlet</title>
         <short-title>XmplPortlet</short-title>
         <keywords>Remote, Cache, Performance, Test</keywords>
      </portlet-info>
   </portlet>
</portlet-app>


In the above example, given that there is a section <expiration-cache>, this section was originally defined in the JSR 168 specification as a general cache expiration time value for portal caching of portlet markup fragments. Since there is no need to distinguish internal and remote cache expiration values, WebSphere Portal uses this as the contributing value of this portlet definition for remote caching.

What is still missing here is the cache scope value (<remote-cache-scope>) and another value that was introduced by WebSphere Portal for performance reasons to give an early indication whether a portlet window will dynamically publish cache information (<remote-cache-dynamic>). With this setting, WebSphere Portal is able to shortcut some calculations in its portlet container if it is set to false.

Since the deployment descriptor is defined in the JSR 168 specification, WebSphere Portal uses an extension to this deployment descriptor to publish the missing values (ibm-portlet-portal-ext.xmi). For example:

 

Listing 4



<?xml version="1.0" encoding="UTF-8"?>
<portlet-app 
   version="1.0" 
   xmlns=http://www.ibm.com/xml/ns/portlet/portlet-app_1_0_ext.xsd
   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
 xsi:schemaLocation="http://www.ibm.com/xml/ns/portlet/portlet-app_1_0_ext.xsd
   http://www.ibm.com/xml/ns/portlet/portlet-app_1_0_ext.xsd" 
>
<!-- The href must match the portlet name in the portlet.xml file-->
   <portlet href="Example Portlet">

      <remote-cache-scope>SHARED</remote-cache-scope>
      <remote-cache-dynamic>true</remote-cache-dynamic>

   </portlet>
</portlet-app>


 

How portlet windows contribute cache information

Portlet windows may publish cache information at render time. This means WebSphere Portal introduces or extends an existing programming interface for a portlet which may decide at render time which contributing values to publish for cache scope and cache expiration time.

The JSR 168 specification defines a general cache expiration time value that a portlet may set itself at any time during rendering. Since there is no need to distinguish internal and remote cache expiration values, WebSphere Portal uses this value also as the contributing value of this portlet window for remote caching.

Listing 5 shows a fragment of a standard portlet that publishes the cache expiration time and cache scope at render time:

 

Listing 5

  
. . . 

import com.ibm.wps.util.RemoteCacheInfo;
import javax.portlet.RenderResponse;

. . .

/* Do rendering */
public void doView(RenderRequest renderRequest, RenderResponse renderResponse)
   throws PortletException, IOException {

   /* Some code might happen here */
   . . . 

   /* Publish an expiration time of 200 seconds during rendering */
   renderResponse.setProperty( 
      RenderResponse.EXPIRATION_CACHE, "200" );

   /* Publish a cache scope value of "shared" during rendering *)
   renderResponse.setProperty( 
      RemoteCacheInfo.KEY_SCOPE, RemoteCacheInfo.Scope.SHARED_STRING );

   /* Some other code might happen here */
   . . . 

}


Since the cache scope is not part of the JSR 168 specification, WebSphere Portal provides an interface, RemoteCacheInfo, which offers static strings for key and values to set the cache scope information in the render response, as shown in the above example. As an alternative, the following strings may be used directly as well:

 

How WebSphere Portal contributes global values of cache information

There are three global settings in WebSphere Portal which influence global values relevant for caching in remote caches:

All of the above attributes can be found in a property file NavigatorService.properties in the directory <portal-install-root> /shared/app/config/services. After editing this file, a restart of WebSphere Portal is required to make the settings effective. Remember that if WebSphere Portal is installed in a cluster, an update to this file in the same manner is required on each node in that cluster.

Another attribute that may contribute to the overall cache information is whether or not a request is unauthenticated. This information has no persistent representation in a file or database and needs to be inspected for each incoming request to WebSphere Portal.

 

Appendix B: Example for calculation of remote cache information

As an example, we assume the following portal page and setup is assumed:

Figure 9. Example page for remote caching

Figure 9. Example page for remote caching

There is a portal page which contributes the values:

This page is associated with a theme which contributes the values:

On that portal page, there are two JSR 168 standard portlets. Both portlets have set the value of remote-cache-dynamic to true to inform the portlet container that they will also provide remote cache information at render time.

The portlet definition of the first portlet contributes the values:

The portlet window of this first portlet contributes the values:

The portlet definition of the second portlet contributes the values:

The portlet window of this second portlet also contributes the values:

The portal globally contributes the following values through the settings in NavigatorService.properties file:

The request to this page is:

 

Step 1: Calculating global values

In the first step, WebSphere Portal calculates global default values and global maximum values, as given in the flow graphs in Global default values and global maximum values .

This algorithm leads to:

In the given example, this also leads to:

Note that values for global default values and global maximum values may not necessarily be equal. As shown in the graphs, there are cases where they differ.

Since all of our relevant contributors (the portal page, the theme, and the portlets) contribute there own remote cache information, there is no need to fall back to the global default values, and so further calculations are not necessary.

 

Step 2: Calculating remote cache expiration

In the second step, WebSphere Portal calculates the minimum of the remote cache expiration of the information contributed by all of the components.

As mentioned earlier, there is a special mechanism for portlets for the contributed value of the cache expiration. The cache expiration value contributed by the portlet window always has precedence over the value contributed by the portlet definition, regardless of whether it is a higher or a lower value than that of the portlet definition. If no value for cache expiration is contributed by the portlet window, the value from the portlet definition will be used. In our example, this leads to a contributed cache expiration value which is higher than that specified in the portlet definition for the first portlet.
Portlet definition of first portlet 15 seconds
Portlet window of first portlet 20 seconds
Resulting value for first portlet 20 seconds

Portlet definition of second portlet 100 seconds
Portlet window of second portlet 100 seconds
Resulting value for second portlet 100 seconds

Now the minimum of all contributed values is calculated.
Portal page 100 seconds
Theme 40 seconds
Global maximum 50 seconds
First portlet 20 seconds
Second portlet 100 seconds
Resulting value 20 seconds

 

Step 3: Calculating remote cache scope

In the third step, WebSphere Portal calculates the minimum of the remote cache scope of the information contributed by all of the components.

As for cache expiration, there is a special mechanism for the contributed value of cache scope for portlets as well. The cache scope contributed by the portlet window always has precedence over the value contributed by the portlet definition, regardless of which is the higher or lower value. If no value for cache scope is contributed by the portlet window, then the value from the portlet definition will be used. In our example, this mechanism is not explicitly shown since the cache scope of the portlet window is the same as the cache scope of the portlet definition.
Portlet definition of first portlet SHARED
Portlet window of first portlet SHARED
Resulting value for first portlet SHARED

Portlet definition of second portlet NON_SHARED
Portlet window of second portlet NON_SHARED
Resulting value for second portlet NON_SHARED

Now the minimum of all contributed values is calculated.
Portal page SHARED
Theme SHARED
Global maximum SHARED
First portlet SHARED
Second portlet NON_SHARED
Resulting value NON_SHARED

After all calculations have been processed by WebSphere Portal, appropriate headers for the completely rendered page are written back to the HTTP response. In our example, these headers would be:

 

Appendix C: Checklist for caching in remote caches

When the portal setup has been modified for adaptive page caching, you may wish to be ready to analyze the system in case the portal produces unexpected responses. Here is a list of items to look at first for troubleshooting:

  1. Check the HTTP response headers with a tool. The response headers are the only additional information that WebSphere Portal provides for caching in remote caches.
  2. If the response headers are correctly set, then investigate why the browser or proxy server may not be working as expected.

If response headers are not set as expected check the following:

  1. Are all portlet definitions on that specific page actually contributing cache information? Check the deployment descriptor and extension to the deployment descriptor.
  2. Does one of the portlets override the settings of the deployment descriptor in an unexpected way? Trace any custom portlets for this possibility.
  3. Does the portal page contribute the correct information? Check the settings in the graphical user interface or in the output file of an XML access export for that portal page.
  4. Does the theme contribute the correct information? Check the settings in the output file of an XML access export for that theme.
  5. Is the request to WebSphere Portal authenticated or unauthenticated? Global default values may vary upon whether a request is authenticated or not. Use a tool (see Resources ) to determine whether a response contains a session cookie, in which case the request is considered to be authenticated.
  6. Are the globally provided values correct? Note the special behavior and the calculation to keep compatibility with previous WebSphere Portal releases. Check the algorithm as explained in Global default values and global maximum values .

 

Appendix D: Example application for portlet caching

This sample application illustrates portlet caching, as discussed in Portlet caching .

 

Introduction

The example application consists of a portlet made up of multiple pages that displays the current page number, a timestamp, three links to browse the available pages, and an "Invalidate me !" ACTION url. The random number is for demonstration purposes.

 

Figure 10. Portlet caching example

Figure 10. Portlet caching example

The whole content is a fragment provided by WebSphere Applications Server's Dynacache engine. If the user reloads the portlet, the Random number will not change unless the cache expires between two requests.

Figure 11. Portlet caching example

Figure 11. Portlet caching example

Caching multiple views for the same portlet is possible because the cache key contains the relevant information from the navigational state parameters.

 

Portlet descriptor

Listing 6



<?xml version="1.0" encoding="UTF-8"?>
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd 
	http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">
    <portlet>
        . . .
<!-Expiration value is in seconds, -1 = no time limit, 0 = deactivated-->
	<expiration-cache>3600</expiration-cache> <!- 1 Hour cache -->
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>VIEW</portlet-mode>
        </supports>
        . . .
    </portlet>
</portlet-app>


AdminConsole

 

Figure 12. Admin console

Figure 12. Admin console

 

Appendix E: Example application for object caching

This sample application illustrates object caching and the exploitation of JSR168 state handling concepts, as discussed in Object caching and state handling .

 

Introduction

The example application consists of a portlet that displays IBM's current stock quote and that enables the user to add a number of stocks to his shopping cart. The portlet consists of two screens, the first of which displays the current stock quote and the number of stocks in the cart, and the second of which provides an input field that lets the user enter the desired number of stocks to be added to the cart. The portlet uses a Web service to query the current stock price. This service is hosted by an Internet market data provider and has a potentially long latency time.

 

Figure 13. CacheTest portlet

Figure 13. CacheTest portlet

 

Figure 14. CacheTest portlet

Figure 14. CacheTest portlet

 

State handling

The example application stores the type of the screen to display as a render parameter, and the content of the shopping cart (the number of stocks) as a session parameter. This enables the user to use the back button to switch between both screens while displaying the number of stocks in the cart. (The back button will not alter the content of the cart.) The "click here" links that switch between the screens are encoded as render links and directly encode the ID of the target screen as a parameter on the link itself.

In the first screen:

Listing 7



<% url = renderResponse.createRenderURL();
url.setParameters(renderRequest.getParameterMap());
url.setParameter(Constants.KEY_VIEW, Constants.VALUE_VIEW_BUY);
 %>

<p>Click <a	href="<%=url %>" title="Go Shopping">here</a>
to add stocks to your shopping cart.</p>

In the second screen:

Listing 8



<% url = renderResponse.createRenderURL();
url.setParameters(renderRequest.getParameterMap());
url.setParameter(Constants.KEY_VIEW, Constants.VALUE_VIEW_STOCK);
 %>

<p>Click <a	href="<%=url %>" title="Go Home">here</a>
to go to the main view without buying.</p>


Note that the render link contains the complete set of render parameters for the next request, not only the modification with respect to the current render parameters. This is why code first associates the current set of render parameters with the render URL, url.setParameters(renderRequest.getParameterMap());, and then modifies this set to represent the next screen.

In this very simple example it is possible to calculate the new set of render parameters by copying the current set and overriding only one key. In more complex scenarios, the generation of a render URL might require more sophisticated calculation. If this calculation takes a significant amount of time, the portlet should cache the sets of render parameters for the URLs and should use the current set as a key (see the next section). However, the portlet must never cache the URL itself.

 

Object caching

For the example application, the latency during rendering is caused by access to the remote stock quotes service. For the purpose of this example, it is not necessary to display live stock information and is preferable to trade stale stock prices for faster display performance. The portlet uses the DistributedMap provided by the appserver and deploys its own cache by providing a distributedmap.properties file:

Figure 15. Distributed maps

Figure 15. Distributed maps

with the following content:

/services/cache/StocksCache

cache.instance.0.cacheSize=1000

The cache is then resolved during the init phase of the portlet and kept as an instance parameter:

Listing 9



public class CacheTestPortlet extends GenericPortlet implements Constants {

	protected DistributedMap cache;
. . .
	public void init(final PortletConfig cfg) throws PortletException {
		// lookup the dynacache
		try {
			final InitialContext ic = new InitialContext();
			cache = (DistributedMap)
                           ic.lookup("services/cache/StocksCache");
		} catch (NamingException ex) {
			throw new PortletException(ex);
		}
		// default handling
		super.init(cfg);
	}


During the render phase, the portlet fills a bean with all information required by the JSP to generate the markup. One piece of information is the stock quote, which either comes out of the cache or is retrieved from the backend.

Listing 10



final String cacheKey = resp.getNamespace() + "IBM";
// try to get the stocks value from the cache
final Float cachedValue = (Float) cache.get(cacheKey);
if (cachedValue != null) {
	aBean.setFromCache(true);
	aBean.setValue(cachedValue.floatValue());
} else {
	// get the value from the Web service
	final StockquoteStockQuoteServiceLocator loc = new StockquoteStockQuoteServiceLocator();
	final StockquoteStockQuotePortType port = loc					
		.getStockquoteStockQuotePort();
	final float fValue = port.getQuote(aSymbol);
	// update the bean
	aBean.setFromCache(false);
	aBean.setValue(fValue);
	// update the cache
	cache.put(cacheKey, new Float(fValue));
}


 

Resources

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.