Objectives

By the end of this unit you will be able to apply caching to various aspects of your applications to dramatically increase performance.

Object Broker

The Object Broker is a super piece of caching technology for the integrated ORM of FarCry Core. In simple terms it speeds up the access to data in the database by only retrieving the data once, then using in-memory storage to provide fast access for subsequent requests. You really want to turn this on. The goodness provided is only limited by the the memory available to your ColdFusion instance.

The Object Broker manages the population and refreshing of its cache. You don't really need to do anything more than activate the service for the specific content types you desire.

In addition to specific database calls, the Object Broker can also manage caching of all views. Remember a view or webskin is like a fragment of output, such as HTML. Generally a page request is made up of one or more views. The Object Broker's webskin cache will even keep track of embedded views, flushing all the relevant views whenever a relevant content item is changed. This ensures that your changes are directly reflected in the view without having to be involved in any complex cache management.

Activating Object Broker

The Object Broker is activated by adding component level metadata to your content type.

<cfcomponent extends="farcry.core.packages.types.versions" displayname="Article"
  hint="Standard article used in the site."
  bObjectBroker="true"
  objectBrokerMaxObjects="10000"
  lObjectBrokerWebskins="display*">

bObjectBroker

Setting this to true activates object-level caching for the specific content type. The default if you do not specify this attribute is false.

objectBrokerMaxObjects

The maximum number of objects to be held in the Broker for this content type. The default if you do not specify this attribute is 100. Typically you want to set this to a number that is high enough to hold all the records for this content type. The only reason not to is if you lack enough physical memory on the ColdFusion instance to accommodate them.

Object Broker Report

You can check which content types have been activated for the Object Broker by running the Object Broker Report under the webtop Admin tab, Cache Management menu. This should indicate those content types using the Object Broker, their maximum threshold and the current number of objects in the Broker.

Walkthrough: Activating the Object Broker for Content Types

Let's activate the Broker for the three content types we created earlier; superHero, superGroup and superPower.

Open your Super Group type (./packages/types/superGroup.cfc) and update the component metadata

<cfcomponent
	name="superGroup" extends="farcry.core.packages.types.types" output="false" displayname="Super Group"
	bObjectBroker="true" objectBrokerMaxObjects="1000">

Open your Super Hero type (./packages/types/superHero.cfc) and update the component metadata

<cfcomponent
	name="superHero" extends="farcry.core.packages.types.types" output="false" displayname="Super Hero"
	bObjectBroker="true" objectBrokerMaxObjects="1000">

Open your Super Power type (./packages/types/superPower.cfc) and update the component metadata

<cfcomponent
	name="superPower" extends="farcry.core.packages.types.types" output="false" displayname="Super Power"
	bObjectBroker="true" objectBrokerMaxObjects="1000">

Re-initialize the application to get your component changes registered in the application (ie. Update App!)
Wander about the website clicking on a few pages; this will activate the Object Broker and start caching objects behind the scenes
Open up the webtop Admin tab and review the Object Broker Report

View Caching

You can also cache the view layer very easily, either through metadata on the component or directly in the webskin templates themselves.

lObjectBrokerWebskins

A list of webskins that should be cached. The default timeout for any webskin cache is 1400 minutes (or 24 hours). This seems like a long time, but remember they get automatically flushed if content within the view is updated.

You can list the webskin templates by name, for example:

lObjectBrokerWebskins="displayTeaserFeature,displayPageStandard"

You can list the webskin templates using a wildcard, for example:

lObjectBrokerWebskins="display*"

You can nominate a specific timeout in minutes for each template, for example:

lObjectBrokerWebskins="displayTeaserFeature:30,displayPageStandard:60"

Using Wildcards

Although using wildcards are great for caching whole sets of webskins, be careful. Best to be specific about your caching strategy; simplistic caching models can very quickly get you into trouble

Caching From the View

5.1 introduced the ability to nominate metadata within a specific webskin or view to control webskin caching.

@@cacheStatus: 1 caching, 0 default, -1 nothing can cache
@@cacheTimeout: (in minutes)

A @@cacheStatus is always required if you want to nominate a @@cacheTimeout value.

Setting a @@cacheStatus of "-1" will ensure that the template is never cached. Be aware that this may have a significant impact on your caching strategy as all views that enclose a webskin with a negative @@cacheStatus will in turn not be cached.

Example of Caching for 15 minutes

<cfsetting enablecfoutputonly="true" />
<!--- @@displayname: Mugshot Teaser for Super Hero --->
<!--- @@cacheStatus: 1 --->
<!--- @@cacheTimeout: 15 --->

<!--- tag libraries --->
<cfimport taglib="/farcry/core/tags/webskin/" prefix="skin">

<skin:buildLink objectID="#stobj.objectid#">
	<cfoutput><img src="#application.url.webroot##stobj.imgHero#" class="thumbnailLeft" /></cfoutput>
</skin:buildLink>

<cfsetting enablecfoutputonly="false" />

Example of Enforcing No Caching

<cfsetting enablecfoutputonly="true" />
<!--- @@displayname: Mugshot Teaser for Super Hero --->
<!--- @@cacheStatus: -1 --->

<!--- tag libraries --->
<cfimport taglib="/farcry/core/tags/webskin/" prefix="skin">

<skin:buildLink objectID="#stobj.objectid#">
	<cfoutput><img src="#application.url.webroot##stobj.imgHero#" class="thumbnailLeft" /></cfoutput>
</skin:buildLink>

<cfsetting enablecfoutputonly="false" />

Environment Changes

In some cases you need the view to respond to changes on the URL, form post, client session, security role or other environmental factor. For example, in the case of a paginated result set you may be changing the displayed list of teasers based on a URL parameter such as "&pg=2". This is often awkward for caching regimes as you really need to use a hash of the query string in order to be sure you are looking at the right cache.

There are two specific options for managing environmental cues for caching:

@@cacheByVars: used for any arbitrary variable you may wish to key the cache to
@@cacheByRoles: used to key webskin caches by security roles (to allow for different views dependent on different privileged access levels to be cached in the presentation tier)
Deprecated Options

The following inline template metadata options have been deprecated as of 5.1: @@cacheByURL, @@cacheByForm, @@hashURL. These are all replaced by the @@cacheByVars metadata option. @@cacheByRoles is simply a boolean, so set it to 0 or 1.

Using cacheByVars

To correctly set the cache, you need to specify the full variable name. So, if you want to cache according to a url parameter (such as 'page') you need to set

@@cacheByVars: url.page

Walkthrough: Add Caching to Super Hero

Open the ColdFusion Administrator and turn on debugging times for the server
Run some pages in the sample Mollio site and review the debugging output with your instructor
Open the ./packages/types/superHero.cfc for editing
Modify the opening <cfcomponent> tag to include references to the Object Broker caching engine
```
<cfcomponent bObjectBroker="true" lObjectBrokerWebskins="display*">
```
Restart the application to activate the changes to the component metadata you have made
Re-run the pages in your web site and review your findings with your instructor

Lab: Add Object Broker Caching To Super Group and Super Power

Open up superGroup and superPower content types for editing
Activate caching for all display templates

Walkthrough: Nested Webskin Cache Flushing

1. View a Super Hero page and notice the caching
2. Edit a Super Group and change the title
3. Refresh the Super Hero page and notice that the Super Hero was flushed because a nested webskin needed flushing