29 inCache for Asset Caching

The WebCenter Sites inCache framework supports asset caching by default. Asset caching can be customized.

This chapter contains the following sections:

Section 29.1, "Introduction to Asset Caching"
Section 29.2, "AssetCache Container"
Section 29.3, "Asset Caching Operations"
Section 29.4, "Types of Asset Caching"
Section 29.5, "Customizing Asset Caching"
Section 29.6, "Disabling Asset Caching"
Section 29.7, "Cache Management Tool"

29.1 Introduction to Asset Caching

Asset caching is automatically enabled on WebCenter Sites systems during installation and upgrade. Asset caching, a memory-based system, is built on the inCache framework to protect WebCenter Sites' performance by taking up load that would otherwise affect the database. Asset caching uses its own container – the AssetCache container – which functions by interacting with other inCache components, in particular the dependencyRepository and notifier caches.

To follow the discussion about asset caching, we recommend first reading Chapter 27, "inCache Framework" for a basic understanding of the inCache framework, especially how its cache containers – pageByQuery, dependencyRepository, and notifier – function in relation to each other in page caching. Note that while the pageByQuery cache is not used in asset caching, it serves to illustrate how a cache container works. Its counterpart AssetCache container works in a similar manner. Note, also, that asset caching and inCache page caching work independently of each other. Each type of caching can be enabled or disabled independently of the other.

The rest of this chapter describes the AssetCache container, discusses it functionality in terms of asset loading and invalidations, compares asset caching with page caching, and provides instructions for customizing caching of assets by asset type.

29.2 AssetCache Container

In WebCenter Sites, programmatic usage of assets consists of loading and reading their attributes. Given that assets are loaded by templates, which are stored in WebCenter Sites, AssetCache is used only on WebCenter Sites nodes.

AssetCache is a component of the inCache framework. Similar to the pageByQry cache, AssetCache is independently available in the inCache framework as its own container on each WebCenter Sites node.
The AssetCache container is enabled by default in each WebCenter Sites cs-cache.xml file, where it is named in the <cache> element. The AssetCache container functions by caching assets of all types and interacting with the inCache components listed below. Additional AssetCache containers for assets of specific types can be configured. For more information, see Section 29.4, "Types of Asset Caching" and Section 29.5, "Customizing Asset Caching."
Interaction with the dependencyRepository cache

When an asset is loaded into AssetCache, inCache logs a dependency on that asset by creating entries in the dependencyRepository cache, as shown in Table 29-1. Modifying or saving the asset removes its dependency information from the dependencyRepository cache and therefore invalidates the asset's entry in the AssetCache. In general, any save or delete operation on a cached asset invalidates that asset.

Note:
When asset caching is enabled, assets must not be saved or deleted directly in database tables via Sites Explorer or the CatalogManager API. Save and delete operations made in this manner do not invalidate the asset cache.
Interaction with the notifier cache

Invalidations that happen on any one node are reflected on other nodes by means of the notifier cache. This cache broadcasts information as to which asset was changed. If a receiving node contains the asset in its AssetCache, the node updates its own dependencyRepository cache accordingly.

Asset caching works independently of page caching, but shares various cache containers, as shown in Table 29-1.

Table 29-1 Cache Containers Used by Asset and Page Caching

Asset Caching Function	Page Caching Function	`AssetCache` Container	`pageByQry` Container	`dependency Repository` Container	`notifier` Container
Off	Off	Not used	Not used	Not used	Not used
Off	On	Not used	Used in Page Caching	Used in Page Caching	Used in Page Caching
On	Off	Used in Asset Caching	Not used	Used in Asset Caching	Used in Asset Caching
On	On	Using in Asset Caching	Used in Page Caching	Used in Asset Caching and Page Caching	Used in Asset Caching and Page Caching

29.3 Asset Caching Operations

This section contains the following topics:

Section 29.3.1, "Asset Loading"
Section 29.3.2, "Comparing Asset Caching with inCache Page Caching"
Section 29.3.3, "Flushing AssetCache"

29.3.1 Asset Loading

An asset's data can be read in several ways, by using APIs or asset:load tags.

The following APIs load assets into AssetCache in readonly-complete mode:
- AssetDataManager.read(AssetId)
- REST API GET for assets
The following tag loads assets into AssetCache in different modes:
- asset:load(objectid="cid1" option="editable")
- asset:load(objectid="cid1" option="readonly")
- asset:load(objectid="cid1" option="readonly-complete")

The option parameter determines whether an asset is cached, and how a cached asset's key is named in the AssetCache and in the dependencyRepository. Caching scenarios are summarized in Figure 29-1. Note that in scenario D, you will find multiple entries in the AssetCache container for the same asset. This is due to the fact that an asset can be loaded in two modes: readonly and read-only complete.

The following modes determine whether an asset is cached and how its key is named in the AssetCache and dependencyRepository. The mode is defined in the APIs and tags listed in Section 29.3.1, "Asset Loading."

Figure 29-1 Asset Caching Scenarios

Description of ''Figure 29-1 Asset Caching Scenarios''

29.3.2 Comparing Asset Caching with inCache Page Caching

Keys are named differently for cached assets and pages, and for their dependencies, as shown in Figure 29-2. Understanding the differences helps to interpret caching information displayed in the Cache Management tool (available under the System Tools node, in the Admin tab).

Figure 29-2 Dependence Naming Conventions in Asset Caching and Page Caching

Description of ''Figure 29-2 Dependence Naming Conventions in Asset Caching and Page Caching''

For example, Figure 29-2 shows that in the AssetCache container, the key of a cached asset is named assettype:cid1:2, where the last integer represents the mode in which the asset was read (2 for readonly mode). If the same asset is also loaded in readonly-complete mode, its key would be assettype:cid1:3. When an asset is called in multiple modes, you will find multiple entries in the AssetCache container for that asset (see Figure 29-1).

The key of a cached page begins with pagename. Mode does not apply to pages; if a page is cached, it is cached only once.

For more information about asset loading modes, see Section 29.3.1, "Asset Loading." Information about the Cache Management tool is available in Chapter 30, "System Tools."

29.3.3 Flushing AssetCache

Assets can be flushed from the AssetCache if they are saved via the following APIs and tags:

API
- REST API PUT
- AssetDataManagerWrite
JSP Tags
- asset:save
- asset:saveall
- asset:delete
- asset:deleteassettype
- asset:void
- asset:rollback
- asset:deleterevision
- asset:undocheckout
- insite:edit
XML Tags
- INSITE.EDIT
- ASSET.VOID
- ASSET.SAVE
- ASSET.SAVEALL
- ASSET.DELETE

29.4 Types of Asset Caching

When asset caching is enabled on a WebCenter Sites node, the cs-cache.xml file on that node contains at least one of the following <cache> elements:

The default <cache> element, which specifies that assets of all types are cached in a generic cache container named AssetCache:
```
<cache name="AssetCache"
   diskPersistent="true" maxElementsInMemory="100" 
   maxElementsOnDisk="100" eternal="true" overflowToDisk="true" 
   diskSpoolBufferSizeMB="20" memoryStoreEvictionPolicy="LFU" 
   clearOnFlush="false" />
```
The generic AssetCache container is automatically configured on all WebCenter Sites nodes during the WebCenter Sites installation process.
A custom <cache> element, which specifies that assets of a given type are cached in their own container named AssetCacheAsset_type_name:
```
<cache name="AssetCacheAsset_type_name"
   diskPersistent="true" maxElementsInMemory="100" 
   maxElementsOnDisk="100" eternal="true" overflowToDisk="true" 
   diskSpoolBufferSizeMB="20" memoryStoreEvictionPolicy="LFU" 
   clearOnFlush="false" />
```
All custom, type-specific AssetCache containers must be manually configured in the cs-cache.xml files. How many type-specific containers to create depends on which types of assets must be cached in their own containers and which conditions must be applied to caching in each container.

Note that the generic AssetCache container can either co-exist or be replaced with one or many type-specific asset caches. The contents of all asset caches are mutually exclusive. That is, the generic AssetCache container excludes assets of the type that are cached in a type-specific container, and a type-specific container excludes assets of all other types.

Also note that when asset caching is enabled, the Cache Management tool (on the System Tools node of the Admin tab) displays dialogs showing the contents of AssetCache containers, corresponding entries in the dependencyRepository, and other types of information. Searches are also supported.

For more information about configuring asset caching, see Section 29.5, "Customizing Asset Caching." For more information about the Cache Management tool, see Chapter 30, "System Tools."

29.5 Customizing Asset Caching

The steps below show you how to configure type-specific asset caches.

To configure asset caching

When default asset caching is enabled on a WebCenter Sites node, you will see the following entry in the cs-cache.xml file on WebCenter Sites nodes, which specifies that assets of all types will be cached in a generic container named AssetCache (parameters, other than name, are defined in Table 28-1):
```
<cache name="AssetCache"
   diskPersistent="true" maxElementsInMemory="100"
   maxElementsOnDisk="100" eternal="true"    
   overflowToDisk="true" diskSpoolBufferSizeMB="20"
   memoryStoreEvictionPolicy="LFU" clearOnFlush="false" />
```
Note:
Given that the generic AssetCache container can either co-exist or be replaced with one or many type-specific asset caches, you have the option to do any of the following:
- You can keep the generic AssetCache container and add as many type-specific containers as necessary. Assets of all types will be cached. Assets having their own type-specific container will be cached exclusively in their own container, which can be individually tuned by use of the parameters shown in Table 28-1.
- You can replace the generic AssetCache container with one or more type-specific containers. Only assets of the named types will be cached.
How many AssetCache containers to create depends on which types of assets must be cached in their own containers and which tunings must be applied. Configuration information is available in the steps below.
To cache assets of a given type in their own container, create a <cache> element for that asset type and set name="AssetCacheAsset_type_name" (only one asset type is supported for each custom <cache> element). Configure the cache by using the parameters in Table 28-1.

For example:
```
<cache name="AssetCacheContent_C" 
   diskPersistent="true" maxElementsInMemory="100"  
   maxElementsOnDisk="100" eternal="true" 
   overflowToDisk="true" diskSpoolBufferSizeMB="20"
   memoryStoreEvictionPolicy="LFU" clearOnFlush="false" />
```
In this example, name="AssetCacheContent_C" creates a type-specific AssetCache container that holds only assets of type Content_C. If the generic AssetCache container is also configured, it will not cache assets of type Content_C.

29.6 Disabling Asset Caching

If your inCache framework is set up to support asset caching and you wish to disable asset caching, do the following:

On each WebCenter Sites node in the inCache framework, open the cs-cache.xml file (in the WEB-INF/classes/ directory) and remove the <cache> elements whose name begins with AssetCache. You can remove selected <cache> elements or all <cache> elements. Each element represents an AssetCache container. For information about the types of AssetCache containers, see Section 29.4, "Types of Asset Caching."

29.7 Cache Management Tool

When asset caching is configured, the Cache Management tool displays dialogs showing the contents of AssetCache containers and corresponding entries in the dependencyRepository, among other types of information. Searches are also supported. For more information about the Cache Management tool, see Chapter 30, "System Tools."