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.

1 Enabling Caching
2 Configuring Caching Settings
3 Locate or Create the Configuration File for your Tenant
4 Configuring Expiration Times for Cached Files
- 4.1 Examples of Expiration Time Values
5 Applying Changes to Caching Settings
6 Configuring Caching From the Application Layer Source Code Tree (an alternative approach)
7 See Also

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.

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.