Configuring Caching in CollectionSpace

This page describes how:

CollectionSpace allows users' browsers to cache many of the items that make up CollectionSpace's pages, thus speeding up page loading performance.
You can adjust these caching settings to meet the specific needs of your CollectionSpace implementation.

Instructions here are for CollectionSpace 3.1 and later

These instructions pertain only to CollectionSpace versions 3.1 and later. If you are using CollectionSpace versions 2.0 through 3.0, please see the earlier version of this document.

Enabling Caching

CollectionSpace can be configured so that both static files and some dynamic data, as well, can be cached in users' browers, thus improving page loading times. Caching is enabled via Cache-Control: entries in the HTTP headers returned in CollectionSpace's responses to browsers' requests for those items, which provide instructions to browsers on which items are to be cached, for how long, and under what circumstances.

The types of items that can be cached include:

Term lists (the items that appear in dropdown menus in many fields)
Autocomplete lists (the specific lists of vocabularies in which you will be searching when typing into various autocomplete fields)
Reports (the items that appear in the dropdown Reports menu on some pages)
Uploaded media
'uispec' and 'uischema' data (which are used as guides by CollectionSpace when dynamically composing page elements)
HTML pages
CSS stylesheets
JavaScript scripts
Image files used by CollectionSpace's user interface
'Message bundles' properties data (which provides nearly all of the text labels appearing on CollectionSpace pages)

A default set of caching settings are included in configuration files for each of the two demonstration tenants, core and lifesci, that ship by default with a CollectionSpace system.

When you create a new tenant for your museum, you will typically do so by 'cloning' an existing tenant's files, as per the instructions in Creating your new tenant. By doing this, you will inherit the default caching settings, which you can then change to your liking.

Each cached item has an expiration date, which determines how long the item should be cached in users' browsers. The default expiration period for all items is 1 month (expressed as 2592000 seconds in configuration settings, below).

Configuring Caching Settings

Depending on the usage of your CollectionSpace system, you may wish to change your tenant's caching settings. You can disable caching for certain categories of items altogether, or you can increase or decrease the time that these categories of items are cached in users' browsers.

You can do this via a multi-step process, as described below.

Locate or Create the Configuration File for your Tenant

For starters, locate the configuration file for your tenant, within the CollectionSpace server directory.

You can find that file here:

When running CollectionSpace on a Linux, Mac OS X, or other Unix-like server:

$CSPACE_JEESERVER_HOME/lib/tenants/{your_museum}/settings.xml

When running CollectionSpace on a Microsoft Windows server:

%CSPACE_JEESERVER_HOME%\lib\tenants\{your_museum}\settings.xml

Now you can continue with the steps below, to edit that file and apply your changes.

Configuring Expiration Times for Cached Files

If you make a lot of changes to your CollectionSpace system (code- or configuration-wise), you may want a very short caching time (or no caching at all) to be able to see your changes sooner. On the other hand, if you are not tweaking CollectionSpace, but are just using the application normally (entering, editing, retrieving data, etc) it should be safe to set a long expiration time, and doing so will speed up page loading performance.

To change the expiration values, you need to edit the caching rules that CollectionSpace uses:

Open the settings.xml file you created in the previous step, where {your_museum} represents the actual short name of your museum.

Scroll down to the section looking like this:

<settings>
    <admin>
...
        <!-- termLists, autocomplete instance lists, specs, and schemas,
             static UI elements, etc.
             will cache for a month (60*60*24*30) by default -->
        <termlist-cache-timeout>2592000</termlist-cache-timeout>
        <autocompletelist-cache-timeout>2592000</autocompletelist-cache-timeout>
        <reportlist-cache-timeout>2592000</reportlist-cache-timeout>
        <!-- This is for user-uploaded media, not static UI images -->
        <uploaded-media-cache-timeout>2592000</uploaded-media-cache-timeout>
        <uispecschema-cache-timeout>2592000</uispecschema-cache-timeout>
        <ui-html-cache-timeout>2592000</ui-html-cache-timeout>
        <ui-css-cache-timeout>2592000</ui-css-cache-timeout>
        <ui-js-cache-timeout>2592000</ui-js-cache-timeout>
        <!-- This is for static UI images like icons, not uploaded images -->
        <ui-media-cache-timeout>2592000</ui-media-cache-timeout>
        <!-- This is for the message bundles properties -->
        <ui-props-cache-timeout>2592000</ui-props-cache-timeout>
    </admin>

To edit the expiration time for any category of item, simply change its numeric value. This value is expressed as the number of seconds from when the item is first downloaded by a user's browser, until the item expires from the cache(s) in their browser and must be downloaded once again.

Examples of Expiration Time Values

For example, if you want caching of term lists to expire after just 12 hours, rather than after 1 month, you can change the <termlist-cache-timeout> value to 43200 seconds. Here's how you'd arrive at that value: 60 seconds x 60 minutes x 12 hours = 43200 seconds.

<termlist-cache-timeout>43200</termlist-cache-timeout>

Similarly, if you want caching of uploaded media to expire after just 2 days, you'd do much the same, changing the <uploaded-media-cache-timeout> value to 172800 seconds: 60 seconds x 60 minutes x 24 hours x 2 days = 172800 seconds.

<uploaded-media-cache-timeout>172800</uploaded-media-cache-timeout>

To disable caching altogether for any category of item, set its value to zero (0):

<termlist-cache-timeout>0</termlist-cache-timeout>

Applying Changes to Caching Settings

After you have changed caching settings, you can apply these changes to your CollectionSpace system in either of two ways:

Reinitializing the configuration for your tenant;
or
Shutting down, then restarting the CollectionSpace servers.

The first of these two options, reinitializing the configuration for your tenant is generally preferable. This option does not require a complete restart of the CollectionSpace system, and will display an error (even if a somewhat technical and unfriendly one) directly in your web browser if any error occurred during that process.

Configuring Caching From the Application Layer Source Code Tree (an alternative approach)

If you would prefer to deploy the configuration for your museum from the Application layer source code tree to the CollectionSpace server directory, rather than merely editing that configuration in place in the server directory - perhaps because you are maintaining your configuration changes under version control - you can do the following as an alternative to the steps above:

Within the Application layer source code tree, change to the directory for your museum within tomcat-main/src/main/resources/tenants (or equivalent path under Windows). For example, for the demonstration core tenant, that directory would be tomcat-main/src/main/resources/tenants/core
Within that directory, find the file named settings.xml
Edit that new file, as described in Configuring Expiration Dates for Cached Files.
Change your current directory to the top-level war-entry directory within the Application layer source code tree.
Enter ant deploy_cspace_config
This will copy your new file, along with any other updated configuration files, to the relevant directories within the CollectionSpace server directory.
Apply your changes, as described in Applying Changes to Caching Settings.

CollectionSpace 5.0 Documentation