More Than 5 Seconds on Caching

Back by popular demand: a more than 5 second overview of the portal's portlet caching mechanism. Apparently my last post, with it's 5 second explanation of caching, left some people wanting more. As such, I'm back with a more than 5 second explanation of portlets, cache keys, and a somewhat practical portlet you can use to demo some of ALUI's caching behavior.

This post is mostly a (hopefully more comprehensible) rehash of the caching edocs. Without further ado, let's get into it...

Setting Up a Demo Portlet

Before I get into it, I want to show you some simple source for a JSP I wrote to test this behavior. At some point this type of thing may come in handy if you get confused. All I am really doing here is comparing a javascript timestamp (rendered on the client every time) with a server side timestamp (if the HTML is cached, this timestamp won't change). This JSP will also allow me to change HTTP headers using some variation of response.setHeader.

<%@ page language="java" import="java.util.*" pageEncoding="UTF-8"%>
<%
	// get current time for manipulation
	Date theTime = new Date();
%>

<p>This portlet tests the caching framework.
<script>var dt = new Date();</script>
<br><br>Javascript time: <script>document.write(dt.toString());</script>
<br><br>Server side time: <%=theTime.toString()%>
</p>

Caching - Step 1 - HTTP Headers

The first lines of defense in the portal for portlet caching behavior are the HTTP headers sent in a portlet response. There are a few headers you should be concerned about, and all of them will override any other cache settings configured in the portal except for the minimum cache time. If you don't send any headers, then the cache will default to the web service settings (see below) and use public caching (there will be one copy of the portlet in the cache for all users).

Here are the three major ones (anything I leave out is in the edocs):

• Expires - This is the simplest method for caching HTML in the portlet cache. Set this header to an HTTP date (i.e. Sun, 15 Jul 2007 16:00:00 GMT) and the portal will check for new content at the time specified (and cache it until then).
• Last-Modified - This header specifies the last modified date of content. Rather than setting an Expires, you can have the cache check for new content every time a request is made, but rather than make a full request, the portal will only check the HTTP header. If and only if this header changes will the cache be refreshed.
• Cache-Control - This may be the most important header of all, since it turns on and off per-user caching (set it to private to cache portlets on a per user basis -- see Step 3 for details) and allows us to turn off caching all together (set it to no-cache).

If you're still curious, and edocs adverse, you can find a great article on HTTP caching here.

Caching - Step 2 - Web Service Settings

The second lines of defense in our portlet caching framework are the web service settings configured for a portlet (don't worry about the advanced settings just yet). These settings simply tell the portal when to start making requests to refresh the cache, and when it must make a request to refresh the cache. Here's what they look like:

Remember, though, that the portal tries to respect the HTTP standard, so the HTTP headers we talked about in step 1 are still valid in between the maximum and minimum cache times. In fact, content might be cached longer than the maximum time if it uses the Expires header to indicate it is still valid.

Caching - Step 3 - Cache Keys

The third line of defense in portlet caching is the portlet cache key. This key indicates to the portal whether or not the data in the cache is bad. If the key changes, new content must be requested. If you want to think of it programmatically, the key is just a string that keeps getting appended with a bunch of data. Each time a portlet is put on a page, that string is built and associated with the portlet. If that string changes the next time a page is requested, the cache is invalid and a new copy of the HTML must be requested.

The key is built from two types of settings: those which are always part of the key, and those which are only part of the key if they are used in the portlet. How do we indicate whether or not they are used? Simple... when we choose to send them to the portlet via the web service settings, the portal automatically assumes we need to use them in the cache key. You can adjust these settings under the Advanced Settings option in the Web Service editor:

By default, if any of the following things change, the cache key will become invalid and new content will always be requested:

• Any type of setting passed to the portlet: Portlet settings, User settings, Community settings, Administrative settings, Session preferences, User Information
• Locale
• Actual URL to the portlet
• Community
• Content Mode (actually, I have no clue what content mode is, but it's in the documentation)

Additionally, the following things will affect the key if we check the boxes above:

• Time Zone
• Page ID
• Community Security (ACL)
• Experience Definition
• Portlet Alignment
• Activity Rights sent to the portlet

But What About...?

There are a few confusing things involving caching I'd like to point out here, since they initially confused me:

• 304 Redirects - What if you use a response.setRedirect or Response.Redirect? Will that screw up the caching in the portal? Nope... as long as the page you are redirecting to in the portlet doesn't change (remember our cache key is based on URI), the cache will cache whatever page you redirect to, instead of the redirect.
• Javascript and Images - These are not cached for the portlet, rather they are cached by the gateway, which basically means they just follow whatever rules your browser would normally follow for the web server (if you set an expires header for static content in apache, the gateway will respect that - if not, then it will re-request the content).
• AJAX - Any dynamic javascript requests will also lose the portlet based caching mechanism. The reason for this should be fairly obvious: the portal can't track extraneous requests on a per-portlet basis. Again, these will go through the gateway and your browser will be responsible for handling any HTTP headers.
• Default Behavior - If no headers are specified, the cache will respect the web service settings and use public caching (not per user).

That's it. As always, I guarantee something in here is inaccurate. Have a great time messing around with portlet cache settings, but remember -- use them responsibly.