30 Using The inCache Framework

The caching system, the inCache framework, or simply inCache is built on top of Ehcache, an open source, standards-based product from Terracotta. WebCenter Sites relies on multicast support to provide inCache replication across nodes in a clustered environment.

• Overview

• Understanding How inCache Works

• Restarting a Node

• Regenerating Pages During RealTime Publishing

• Double-Buffered Caching

• Configuring Your System for inCache Page Caching

• Tuning Options

• Working with the AssetCache Container

• Working with Asset Caching Operations

• Types of Asset Caching

• Customizing Asset Caching

• Disabling Asset Caching

• Using the Cache Management Tool

• Using inCache Features for Remote Satellite Server

30.1 Overview

inCache is a memory-based page and asset caching system that eliminates the requirement to cache WebCenter Sites data in a central, shared repository and shared file system. inCache is based on Ehcache, an open source Java caching framework from Terracotta, and can be implemented on top of any caching system. (For more information about Ehcache, see http://ehcache.org/.)

Note:

WebCenter Sites uses ehcache to cache the content at various levels. Ehcache may become out of sync if one of the nodes in the Sites cluster faces network outage. It is recommended to restart the node which faces the network outage to keep the cache in sync at various nodes.

This section contains the following topics:

• Overview of the Caching Framework

• Overview of Page Caching

• Overview of Asset Caching

30.1.1 Overview of the Caching Framework

The inCache framework replaces the legacy page caching framework. inCache also supports asset caching by default. The inCache framework offers the following benefits:

• High performance. Fast response allows for more frequent publishing sessions. Efficient page and asset invalidation ensures updated content is quickly served.

• Decentralized architecture. Nodes maintain their own local caches. The inCache framework eliminates database caching and shared disks.

• Broadcasting system. Each individual node no longer needs a complete view of the entire cache. Nodes listening for changes to content respond to broadcasts as necessary, depending on their individual content.

• Improved linear scalability, enhanced for data on disk and in memory.

• Failover and persistence. Nodes that are shut down retain data in their local caches and update themselves upon restart against a centrally managed record of invalidations.

• On-demand page evaluation and invalidation. Nodes validate and update their currently cached content only when the content is requested.

This chapter describes mainly page caching. Throughout, the term "page" is used to mean rendered page rather than page asset. To follow the discussion of asset caching, we recommend first reading the rest of this chapter, especially Understanding How inCache Works, for a basic understanding of cache containers and how they function in relation to each other.

30.1.2 Overview of Page Caching

inCache supports disk striping and affects RealTime publishing by deactivating the donoteregenerate flag. The option to enable page regeneration during RealTime publishing requires populating the FW_RegenCriteria table, on the delivery system, with the URLs of pages to be crawled and regenerated. Page propagation is also an option, used to ensure that all nodes host the same pages without each node having to regenerate the pages. In addition, remote Satellite Server can be configured to continue serving stale pages for a short duration while their replacements are being regenerated.

Note:

You can return to the legacy page caching method, as necessary, by:

1. Setting the VM argument on all and Satellite Server nodes as follows: –Dcs.useEhcache=false

2. Reconfiguring all and Satellite Server nodes to use the database and shared file system.

3. Purging the legacy page cache before resuming operations, given that it is likely to have become outdated since the time it was disabled.

In general, switching between caching methods requires you to reconfigure the and Satellite Server nodes to use the same cache, and to purge the cache before its use, as recommended by best practices.

30.1.3 Overview of 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 the 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.

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 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.

Working with the AssetCache Container 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.

30.2 Understanding How inCache Works

In a clustered environment, inCache is implemented in a decentralized architecture outside the cluster's database. Each node has its own local cache, as shown in the following figure. Each WebCenter Sites node keeps its local cache current by listening for broadcasts from other WebCenter Sites nodes and communicates updates to remote Satellite Server through HTTP.

Figure 30-1 Local Caches

Description of "Figure 30-1 Local Caches"

A node's local cache is partitioned:

• The pageByQry cache stores the node's web pages.

• The dependencyRepository cache stores identifiers of the assets that make up the web pages.

  Note:

  The pageByQry cache is also called page cache. The dependencyRepository cache is also called dependency cache.

• The notifier cache broadcasts identifiers of assets that have been modified by editorial or publishing processes. Broadcasts are initiated by the nodes on which assets are modified. How a listening node responds to a broadcast depends on the node. For example:

  1. A WebCenter Sites user at node A edits asset A.

  2. The notifier cache on node A broadcasts a notice of change to all other nodes.

  3. Every WebCenter Sites node that contains asset A responds by invalidating the asset in its own local cache. Each node sees its own dependencyRepository cache, marks the asset's identifier as invalid, and increments the dependency generation counter for the entire cache. Because the invalidated asset is no longer available to pages that reference the asset, the pages themselves are invalidated. However, the node does not evaluate the pages until they are requested. Herein lies the performance benefit.

     When a node responds to a request for a page that has a dependency on the invalidated asset, the node sees its pageByQry cache, evaluates the page, determines the page to be invalid, flushes it, generates the new page, serves the page to the visitor's browser, and records the new page and its dependencies in the local cache (dependencies are recorded as identifiers of the assets that make up the page). From then on, the page is served from the node's local cache until the page expires or its assets are again invalidated.

WebCenter Sites and Satellite Server use the same caching framework, though Satellite Server nodes still communicate with WebCenter Sites nodes through HTTP.

Note:

While the pageByQuery cache is used only for page caching, it illustrates how a cache container works. For asset caching, the inCache framework introduces a counterpart container called AssetCache. It works in a similar manner to pageByQuery and interacts with the dependencyRepository and notifier caches. See Working with Asset Caching Operations.

30.3 Restarting a Node

When a or Satellite Server node is shut down, data in its cache persists, but can become quickly outdated as the active nodes continue to invalidate assets. As a result, restarting a node requires updating its cache. Update on restart is ensured by a common invalidation memory, which is stored as a table in the database of the cluster and kept available to all nodes in the cluster for use upon restart. The table is named FW_InvalidationMemory.

The invalidation memory stores records of asset invalidations, specifically identifiers of assets that were modified or deleted during a content management or publishing process. Table growth is checked by a cleanup mechanism that runs at 15-minute intervals to purge invalidation records for the oldest period of time.

When a node is restarted, it attempts to recover information that it missed during its inactive period and therefore sees the invalidation memory:

• If invalidation records exist for the node's inactive period, the node replays them on itself.

• If no assets were invalidated during the inactive period, the node continues to operate as if it were never shut down.

• If invalidation records were purged by the cleanup mechanism while the node was inactive, the node's cache self-destructs and must be rebuilt.

When a remote Satellite Server is restarted, it obtains the information it missed by sending a request to for an update.

30.4 Regenerating Pages During RealTime Publishing

Enabling inCache deactivates the donotregenerate flag for the RealTime publishing process. Because the flag is no longer recognized, crawling is used to regenerate pages during RealTime publishing sessions. If crawling is not implemented, pages are regenerated only when they are requested.

The crawling option requires specifying a set of URLs for the page regenerator to analyze. Typically, they are the URLs of the home page and other high-traffic pages. You can also specify the depth those pages are crawled. For example, a depth of 1 means that the specified pages and pages they link to are crawled, while 0 means that only the specified pages are crawled. Crawled pages are regenerated only if their component assets have been invalidated during the publishing session, or the pages are not cached. All pagelets on the specified pages are regenerated in the process.

The list of URLs and the crawl depth must be specified in the FW_RegenCriteria table, which is created on the delivery system during the first publishing session after inCache is configured. The ft_ss parameter can be included in the URL to specify that requests are handled either directly by WebCenter Sites or by remote Satellite Server. See Working with Asset Caching Operations.

30.5 Double-Buffered Caching

The double-buffered page caching method of Webcenter Sites uses the and Satellite Server caches in tandem on live web sites. Double buffering ensures that pages are always kept in cache, either on or Satellite Server, to protect from an overload of page requests and prevent the live web site from displaying blank pages and broken links.

To maintain the traditional system of double-buffered caching for the inCache framework, we ensured that remote Satellite Server continues to communicate with through http requests. Satellite Server still reads page data through http requests and caches in the usual way. However, page data now includes dependency information in the form of a comma-separated list of asset identifiers which is also streamed to remote Satellite Server.

30.6 Configuring Your System for inCache Page Caching

The configuration process consists of a set of required steps and optional optimization steps. For example, you enable multiple WebCenter Sites nodes to communicate with each other, and set storage properties for each local cache on the WebCenter Sites and remote Satellite Servers.

To configure your system for inCache page caching:

1. Ensure that inCache for page caching is enabled. Look for the VM argument –Dcs.useEhcache and verify that it is either set to true or not set (in which case its value is assumed to be true).

2. Configure each WebCenter Sites and Satellite Server node to retain cache content on system restart. Pass the following VM argument:

   –Dnet.sf.ehcache.enableShutdownHook=true
   

3. Optional optimization. Set the diskStore path for each WebCenter Sites and Satellite Server node. If multiple nodes are on the same system (vertical cluster) ensure that each node has a unique diskStore path. In the cs-cache.xml and ss-cache.xml files, set the property diskStore path="<path to disk store>". Both xml files are stored on each WebCenter Sites node: cs-cache.xml for WebCenter Sites and ss-cache.xml for co-resident Satellite Server. Only the ss-cache.xml file is stored on remote Satellite Server. The files are located under the WEB-INF/classes folder.

   For more information about the diskStore property, see the documentation on the Ehcache web site:

   http://ehcache.org/documentation/configuration.html

   Note:

   inCache exists on WebCenter Sites, remote Satellite Servers, and co-resident Satellite Server. Architecturally and functionally inCache is identical on co-resident and remote Satellite Servers. However, the following recommendations are applied to co-resident Satellite Server:

   • Disk persistence is turned off.

   • The size of each cache is kept smaller than the size of WebCenter Sites cache. This is to prevent overloading memory. We recommend keeping the sizes small except under special circumstances, such as the requirement for full double-buffered caching on co-resident Satellite Server.

4. Configuring inCache Ports. inCache relies on Ehcache's RMI-based transport mechanism for communication between cluster members. While ordinarily this requires no additional setup, it is possible to specify the exact ports for Ehcache to use. This is particularly important when there is a firewall between cluster members.

   It is recommended that you don’t use cache replication for Satellite servers to avoid network overhead. To enable cache replication, set the multicastGroupPort property in each ss-cache.xml file to the same value.

   For more information about configuring Ehcache to use specific ports, see the documentation on the Ehcache website:

   http://ehcache.org/files/documentation/EhcacheUserGuide-1.6.pdf

5. Required for multiple nodes. Configure automatic node detection for WebCenter Sites clusters (Satellite Server nodes cannot be clustered). As an example, this step uses three WebCenter Sites nodes named CS1, CS2, and CS3.

   Note:

   In some instances, firewalls on the inCache node network prevent communication between nodes. Disable those firewalls when installing and configuring inCache for multiple nodes. Once verified the System Administrator/Network Administrator should monitor the ports during inCache testing and page propagation to Remote Satellite Server and adapt their firewalls accordingly.

   1. On each WebCenter Sites node ensure that cs-cache.xml and ss-cache.xml (in WEB-INF/classes) specify a cacheManagerPeerListenerFactory, which is used to create a CacheManagerPeerProvider. The provider detects other nodes in the cluster. Configure automatic detection as shown in the following example:

      <cacheManagerPeerProviderFactory
         class="net.sf.ehcache.distribution.RMCacheManagerPeer
         ProviderFactory"
         properties="peerDiscovery = automatic, 
         multicastGroupAddress = 230.0.0.1, 
         multicastGroupPort = 4444, timeToLive = 32"/>
      

      Note:

      The multicastGroupPort property must be set identically across cluster members. For example, if CS1 specifies multicastGroupPort=4444 in its cs-cache.xml file, then CS2 and CS3 must specify the same setting in their files.

      The timeToLive property specifies the number of hops allowed to a packet, which determines how far the packet propagates. Valid values range between 0 and 255 with the following restrictions:

      • 0 - same host

      • 1 - same subnet

      • 32 - same site

      • 64 - same region

      • 128 - same continent

      • 255 - unrestricted

   2. On all Satellite Servers, co-resident and remote, do either:

      • Set the multicastGroupPort property in each ss-cache.xml file to a unique value.

      • To support cache replication, set the multicastGroupPort property in each ss-cache.xml file to the same value.

        Note:

        The value(s) that you set in the ss-cache.xml files must be different from the value for WebCenter Sites' multicastGroupPort property in the cs-cache.xml files.

      When inCache is configured, the system will start using the configurations specified in cs-cache.xml and ss-cache.xml. Caches are initialized upon the first call to any page in WebCenter Sites, cached or not.

6. Optional optimization. Configure the local caches as necessary, using using-incache-framework.html#GUID-669C4A7B-9BAE-49F6-A5A9-16D8F7684035__BABEGHHE as a property reference. The local cache for each WebCenter Sites and remote Satellite Server node is partitioned. Each part is defined in its own <cache> tag in the cs-cache.xml and ss-cache.xml files. The parts are named as follows:

   • pageByQry: This is the cache for the page data itself, keyed by the query URL.

   • dependencyRepository: This is the cache of dependencies on which the pages are built. When pages are added to the pageByQry cache, entries are automatically created in the dependencyRepository cache. Each entry in this cache is an asset id or unknowndep or unknowndep-<type>. Therefore, this cache contains at most the number of assets in the system and a handful of items for different variations of unknowndeps.

     When a page with no dependencies is cached, that page logs a dependency on _NODEP_ (a single item in the dependencyRepository cache used to identify pages with no dependencies). The _NODEP_ item remains associated with the page until that page either expires or is manually flushed. On remote Satellite Servers, you can disable caching of pages without dependencies by setting the JVM option:

     -Dignore_nodep_pages to true (per Satellite Server).

   • notifier: This cache is used by active WebCenter Sites cluster members to notify other WebCenter Sites cluster members of changes to content.

7. Restart all configured WebCenter Sites and Satellite Server nodes.

8. Verify that all active cluster members are in the caching network and recognize each other. Use the Cluster Info diagnostic tool, which lists all WebCenter Sites members that have a notifier cache. To call Cluster Info:

   1. Bootstrap inCache by rendering a cacheable page.

   2. Log in to the WebCenter Sites Admin interface as a general administrator (fwadmin/xceladmin, by default).

   3. Verify that WebCenter Sites cluster members and co-resident Satellite Servers are communicating with each other. In the General Admin tree, expand the Admin node, expand the System Tools node, expand the Cache Management node, expand the Sites Cache node, and then double-click Cluster Info.

      Figure 30-2 Cluster Info Form

      
      Description of "Figure 30-2 Cluster Info Form"

      Various types of page caching statistics are available in the Cache Configuration tool.

9. If you wish to stripe disks, enable page regeneration during RealTime publishing, or enable page propagation, see Tuning Options.

   Table 30-1 Cache Configuration Properties

   Property	Required?	Description
   name	Y	Specifies the name of the cache. Legal Values: pageByQry dependencyRepository notifier For descriptions, see step 5.
   diskPersistent	N	Specifies whether to persist data on disk between restarts of the JVM. Default / recommended value: true Note: The diskPersistent setting must be consistent across the PageByQry, dependencyRepository, and notifier caches to prevent potential conflicts in generation count.
   maxElementsInMemory	Y	Specifies the maximum number of objects to store in memory. Default value: 200000
   maxElementsOnDisk	Y	Specifies the maximum number of objects to store on disk. Disks can be striped. See Striping the Disk Cache. Default value: 1000000
   eternal	Y	Specifies whether cache is cleared by WebCenter Sites (it is never cleared by inCache). Default value: true Do not change the value of this property.
   overflowToDisk	Y	Specifies whether the memory cache is allowed to overflow to disk-based cache. Default value: true Do not change the value of this property.
   diskSpoolBufferSizeMB	N	Specifies the size of the disk buffer, in megabytes. If you expect many disk I.Os (that is, disk cache is much larger than memory cache) set the buffer to 20MB. Default value: 5
   memoryStoreEvictionPolicy	N	Specifies how to remove items from cache. The recommended and default value is LFU (Least Frequently Used). LRU (Least Recently Used) is also a legal value. Default / recommended value: LFU
   clearOnFlush	N	Specifies whether to clear memory as it is flushed to disk. Default value: false Do not change the value of this property.

30.7 Tuning Options

There are many options in the inCache framework which can be optimized to your system. This section is a collection of those options.

• Striping the Disk Cache

• Configuring for Page Regeneration During RealTime Publishing

• Setting Up Page Propagation

• Configuring for Pagelet Regeneration in the Background

30.7.1 Striping the Disk Cache

The inCache framework supports striping of the pageByQry cache to reduce the contention that occurs when a large portion of the cache must be written to disk.

Complete the following steps on WebCenter Sites nodes and remote Satellite Servers in the inCache framework.

To stripe the pageByQry cache:

1. To enable striping, add the following VM argument where X is the number of stripes:

   –DnumOfDiskStores=X
   

   Set the number of stripes to the number of unique spindles that are available to stripe over (for instance if you have 5 drives, then set X to 5).

   Note:

   Drives used for striping the disk-based cache should not be used for any other purpose.

   The size of each DiskStore is the size specified by the property maxElementsOnDisk in the xml configuration file (see using-incache-framework.html#GUID-669C4A7B-9BAE-49F6-A5A9-16D8F7684035__BABEGHHE). For example, if you are using 5 stripes and maxElementsOnDisk is set to 100000 items, a total of 500000 items can be stored.

2. Create a symbolic link or else mount the drive physically in the correct location so that the stripes are properly distributed.

   For each defined cache, the system creates a directory under the diskStore path (configured in step 3 in Setting Up Page Propagation). Under each directory it also creates a group of numbered directories, starting at 0. Each directory points to a different drive.

   For example, items would be stored as follows in a disk-based cache on WebCenter Sites for –DnumOfDiskStores = 5:

   <custom_path>/cs-cache: 
      Directory: 0
      Directory: 1
      Directory: 2
      Directory: 3 
      Directory: 4
      File: dependencyRepository.data
      File: dependencyRepository.index
      File: notifier.data
      File: notifier.index
   <custom_path>/cs-cache/0:
      File: pageByQry.data
      File: pageByQry.index
   <custom_path>/cs-cache/1: 
      File: pageByQry.data
      File: pageByQry.index
   <custom_path>/cs-cache/2: 
      File: pageByQry.data
      File: pageByQry.index
   <custom_path>/cs-cache/3: 
      File: pageByQry.data
      File: pageByQry.index
   <custom_path>/cs-cache/4: 
      File: pageByQry.data
      File: pageByQry.index
   

In this example, the root cache contains dependency and notifier caches. Spread among the directories 0 through 4 are the stripes of the pageByQry cache. The directories 0 through 4 in this example were placed on five separate drives by the use of symbolic links.

30.7.2 Configuring for Page Regeneration During RealTime Publishing

Pages are regenerated only when they are requested.

To configure page regeneration during RealTime publishing:

1. By default, the PageCacheUpdater is set by the installer to use ParallelCacheRegenerator:

   Open the AdvPub.xml file in the config folder on the delivery system and verify that the PageCacheUpdater section has the code lines shown below.

   Note:

   Do not change any of the values in the PageCacheUpdater section except for numThreadsPerServer that is used to specify the number of simultaneous threads for crawling.

   <bean id="PageCacheUpdater" 
   class="com.fatwire.realtime.regen.ParallelRegeneratorEh" singleton="false">
      <property name="id" value="CacheFlusher" />
      <property name="numThreadsPerServer" value="3" />
      <property name="regenServers">
        <list>
           <value>http://address:port of server where pages are regenerated/
   servlet/ContentServer</value>
        </list>
      </property>
   </bean>
   

   Use the Property Management tool to update regen.servers to point to the WebCenter Sites nodes by <address> and <port of server where pages are regenerated>. You can add complete pagename with arguments to preview the page.

2. Restart the delivery system.

3. RealTime publish to the delivery to create the FW_RegenCriteria table on that system.

4. Open the FW_RegenCriteria table, using Explorer. Specify the pages to be regenerated and the depth of links to be followed. The ft_ss parameter can be included in the URLs to specify whether page requests are handled by directly or by remote Satellite Server.

   Note:

   If a URL assembler is used, specify the internal URLs of the pages to crawl. The regenerator does not recognize URL-assembler URLs.

   Example:

   pagename=SiteName/HomePage&ft_ss=true
   Level=1
   

   will regenerate HomePage and the pages that are linked from HomePage. Given that ft_ss=true, the requests are treated as if they are generated from Satellite Server.

5. RealTime publish to the delivery .

   During the publishing session, the delivery system crawls all of the pages specified in the FW_RegenCriteria table, but regenerates only pages for which component assets were invalidated (it also generates the uncached pages).

   For example:

   1. Updated assets are published to the delivery system.

   2. The delivery system invalidates the existing dependency information for the re-published assets by marking their asset identifiers as invalid in the dependencyRepository cache and incrementing the dependency generation counter. Because the invalidated assets are no longer available to pages that reference the assets, the pages are invalidated.

   3. The page regenerator crawls pages with the URLs that are specified in the FW_RegenCriteria table and regenerates the invalidated pages. It also generates the uncached pages.

30.7.3 Setting Up Page Propagation

Page propagation enables all nodes in a WebCenter Sites cluster (including the Satellite Server nodes) to host the same pages without each node having to regenerate the pages.

When configured to use inCache, each WebCenter Sites has a separate JVM and thus maintains a separate, local cache. If one WebCenter Sites generates and caches a new page, no other WebCenter Sites have the newly cached page, nor are they informed of that page. Upon receiving a request for the same page, each node must generate the page by referring to the database and shared file system, thus putting extra load on both components. Page propagation prevents different nodes from regenerating the same page by propagating the page across the cluster.

Page propagation is triggered when pages are loaded into a node's local cache. It works as illustrated in the following scenario, starting with basic inCache functionality:

1. inCache Page Caching for Newly Generated Pages:

   1. Node A, a WebCenter Sites node, receives a request for a new page.

   2. Node A generates the requested page.

   3. Node A caches the new page with complete dependency information (identifiers of component assets) into its local page and dependency caches.

   4. When page propagation is enabled, step 3 follows.

2. inCache Page Caching for Regenerated Pages:

   1. Node B, also a WebCenter Sites node, receives a request for a page that has been invalidated (a component asset was modified. The asset is marked as invalid in the node's local dependency cache and in the dependency caches of all other nodes containing the asset.)

   2. Node B regenerates the requested page.

   3. Node B caches the regenerated page and updates its dependency (in step 2a) by incrementing the generation counter.

   4. When page propagation is enabled, step 3 follows.

3. inCache Page Caching with Page Propagation:

   When the node caches the (re)generated page, it also propagates the page to all other nodes. Propagated information consists of:

   • The page's complete dependency information. For example, if the page has x dependencies (asset identifiers), all x dependencies are propagated from the local dependency cache to the dependency caches of other WebCenter Sites nodes.

   • The page itself. The page is propagated from the local page cache to the page caches of other WebCenter Sites nodes.

   If the page exists on a receiving node, the node ignores the propagation.

The following list summarizes page propagation events and conditions:

• When a page is cached on a WebCenter Sites node, its complete page information (described in step 3, above) is propagated to all other WebCenter Sites nodes.

• When a page is cached on a remote Satellite Server node, its complete page information (described in step 3, above) is propagated to other remote Satellite Servers over Java Remote Method Invocation (RMI).

• When a page is propagated:

  • The page's last updated time stamp is preserved on all WebCenter Sites and Satellite Server nodes.

  • The generation count on a given node remains independent of generation count on all other nodes. For example, Node A has a generation count of 10, but other nodes use a generation count of 10 for a different type of dependency. Even though the same object is propagated across WebCenter Sites or Satellite Servers, it may be assigned different generation counts by each WebCenter Sites or Satellite Server node. The object and its last updated/modified time remain the same across nodes.

  • The propagation is ignored by nodes on which the page exists.

• If any of a cached page's dependencies fail to propagate to a node where the page does not exist, the page is not cached on that node until it is requested and generated on that node.

• Because blobs are still stored in the Satellite Server caches, they are replicated across Satellite Servers.

This section covers the following topics:

• Enabling Page Propagation

• Setting Up Page Propagation on Restart

30.7.3.1 Enabling Page Propagation

Start with a system that is configured to use inCache.

To enable page propagation:

1. On all WebCenter Sites nodes:

   1. In the Property Management Tool, set propagatecache=true. Ensure to check Global to set this property for all nodes.

   2. In cs-cache.xml, verify that multicastGroupPort is the same for all WebCenter Sites nodes in the cluster to ensure they can communicate with each other. (The file is located in WEB-INF\classes.)

2. On all remote Satellite Servers:

   1. Set propagatecache=true in the wcs_properties.json file for remote satellite servers. This file is located in the config folder.

      Note:

      The config folder for Satellite Server is placed in a user-defined location during installation. For clustered environments, the recommended location is under the sites shared directory (<WCSITES_SHARED DIR>). For non-clustered environments, he recommended location is outside of the home directory (<WCSITES_PRODUCT HOME>). If you cannot locate the config folder, contact your installation engineers.

   2. In ss-cache.xml, ensure multicastGroupPort is identical for all Satellite Servers intended for cache propagation, but different from multicastGroupPort for the WebCenter Sites nodes.

3. On all nodes, initialize page propagation by rendering any page and verify that the system responds as follows:

   • On WebCenter Sites nodes, caching of the page triggers its propagation from the local cache to the caches of other WebCenter Sites nodes (as described in step 3 in Setting Up Page Propagation) while preserving the page's last update/modified time stamp across all WebCenter Sites. Propagation is ignored by WebCenter Sites nodes on which the page exists.

   • The response on Satellite Servers proceeds as on WebCenter Sites nodes, but over Java RMI.

30.7.3.2 Setting Up Page Propagation on Restart

If a node enabled for page propagation is restarted, its local caches must be re-initialized for the node to recognize page propagations.

To reinitialize a local cache:

1. Render a cacheable page on the node.

   Caching triggers the node to propagate the page to other nodes and recognize pages that are propagated by other nodes.

2. Restart a node. The propagations it missed during its period of inactivity are not reproduced on the node, even though its local caches are reinitialized.

30.7.4 Configuring for Pagelet Regeneration in the Background

Remote Satellite Server can be configured to serve invalidated pagelets while they are being regenerated by a background process.

To enable the serving of invalidated pagelets:

• Add serveStale=true to the remote Satellite Server's wcs_properties.json file (located under WCSites_Shared_Dir for clustered environments and under WCSites_Product_Home for nonclustered environments).

  If a pagelet is then invalidated, it is regenerated in these ways:

  • If a browser requests the pagelet within the next 30 minutes, remote Satellite Server starts a background process that sends a request to WebCenter Sites to regenerate the page. While the background process is running, the browser is served the invalidated pagelet from remote Satellite Server's cache. All subsequent requests are served the invalidated pagelet until it is regenerated by the background process.

  • If a browser requests the pagelet after 30 minutes, remote Satellite Server uses its normal process for regenerating pagelets; that is, it sends a request to WebCenter Sites to regenerate the pagelet. The requesting browser must wait until the page is regenerated.

• To obtain information about the background process, set the com.fatwire.logging.cs.cache.ehcache logger to DEBUG in the logging-config.properties file.

  DEBUG produces the following message at the start of the background process:

  "Data for <cache key> is found to have been invalidated. 
  A new request has started processing new data in the background."
  

  After the process, the message reads:

  "Background process for request <cache key> has completed successfully, 
  data in cache is updated."
  

30.8 Working with the 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. See Types of Asset Caching and 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 using-incache-framework.html#GUID-4A2E2C00-03D0-4B73-A018-5CF1FE806863__BABIAIDB. 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 through Oracle WebCenter 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.

The following table shows how asset caching works independently of page caching, but still shares various cache containers.

Table 30-2 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

30.9 Working with Asset Caching Operations

This section covers the following topics:

• Working with Asset Loading

• Comparing Asset Caching with inCache Page Caching

• Flushing AssetCache

30.9.1 Working with 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 using-incache-framework.html#GUID-86E05E15-90D2-4D2A-9ACA-E0C1304D584E__BABHEEIG. 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 readonly_complete.

The following modes determine whether an asset is cached and how its key is named in the AssetCache and dependencyRepository.

Figure 30-3 Asset Caching Scenarios

Description of "Figure 30-3 Asset Caching Scenarios"

30.9.2 Comparing Asset Caching with inCache Page Caching

Keys are named differently for cached assets and pages, and for their dependencies, as shown in the following figure. Understanding the differences helps to interpret caching information shown in the Cache Management tool (available under the System Tools node, in the Admin node of the General Admin tree).

Figure 30-4 Dependence Naming Conventions in Asset Caching and Page Caching

Description of "Figure 30-4 Dependence Naming Conventions in Asset Caching and Page Caching"

For example, this preceding figure 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.

The key of a cached page begins with pagename. Mode does not apply to pages. If a page is cached, it is cached only one time.

See Working with Asset Loading and About Using the Cache Management Tool.

30.9.3 Flushing AssetCache

Assets can be flushed from the AssetCache if they are saved through 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

30.10 Types of Asset Caching

When asset caching is enabled on a WebCenter Sites node, the cs-cache.xml file on that node contains one or more 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 node of the General Admin tree) shows dialogs showing the contents of AssetCache containers, corresponding entries in the dependency Repository, and other types of information. Searches are also supported.

See Customizing Asset Caching and About Using the Cache Management Tool.

30.11 Customizing Asset Caching

These steps show how to configure type-specific asset caches.

To configure asset caching:

1. When default asset caching is enabled on a node, you will see the following entry in the cs-cache.xml file on nodes, which specifies that assets of all types are cached in a generic container named AssetCache (parameters, other than name, are defined in using-incache-framework.html#GUID-4A2E2C00-03D0-4B73-A018-5CF1FE806863__BABIAIDB):

   <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 are cached. Assets having their own type-specific container are cached exclusively in their own container, which can be individually tuned by use of the parameters shown in using-incache-framework.html#GUID-4A2E2C00-03D0-4B73-A018-5CF1FE806863__BABIAIDB.

   • You can replace the generic AssetCache container with one or more type-specific containers. Only assets of the named types are 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.

2. 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 using-incache-framework.html#GUID-4A2E2C00-03D0-4B73-A018-5CF1FE806863__BABIAIDB.

   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 does not cache assets of type Content_C.

30.12 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. See Types of Asset Caching.

30.13 Using the Cache Management Tool

When asset caching is configured, the Cache Management tool shows dialogs showing the contents of AssetCache containers and corresponding entries in the dependencyRepository, among other types of information. Searches are also supported. See About Using the Cache Management Tool.

30.14 Using inCache Features for Remote Satellite Server

Remote Satellite Server is used only in page caching. It can be configured to support advanced functionality such as page propagation and page regeneration in background.

Page propagation

The page propagation option enables all WebCenter Sites nodes and Satellite Server nodes to host the same pages without each node regenerating pages. Nodes receive generated and regenerated pages into local caches from the nodes the pages were (re)generated and cached from. Page caching triggers the propagation. For more information about page propagation, see Setting Up Page Propagation.

Background page regeneration

Remote Satellite Server can be configured to serve invalidated pagelets while they are being regenerated by a background process. See Configuring for Pagelet Regeneration in the Background.