Page Comparison

In memory structure of object broker

Basic process flow

1. on fourq.getData() calls
   • check typename.objectpool for UUID
     • if present
       • return struct
     • if not,
       • make dbgateway call
       • check if room in objectpool
       • purge/update aobjects FIFO list as required
       • update objectpool with object struct
       • return struct
     • update cache stats
2. return object struct to content type call exactly as per original

Essentially update dbgateway calls for CRUD methods in fourq.cfc with calls to object broker. dbgateway would then be responsible for making calls on the Object broker. Update delete and setdata calls to purge objectpool as required.

Reality Check

Currently fourq goes through dbgateway for create, set and delete method calls but not getdata(). Object broker should be an inherent part of the dbgateway componentry. In any event should be easy to get a getdata cache going that ignores underlying data changes through setdata(). Need to update getdata() to go through the dbgateway.

Quick and nasty prototype seems to work well

	<cffunction name="getData" access="public" output="false" returntype="struct" hint="Get data for a specific objectid and return as a structure, including array properties and typename.">
		<cfargument name="objectid" type="uuid" required="true">
		<cfargument name="dsn" type="string" required="false" default="#application.dsn#">
		<cfargument name="dbowner" type="string" required="false" default="#ucase(application.dbowner)#">
		<cfargument name="bShallow" type="boolean" required="false" default="false" hint="Setting to true filters all longchar property types from record.">
		<cfargument name="bFullArrayProps" type="boolean" required="false" default="false" hint="Setting to true returns array properties as an array of structs instead of an array of strings.">
		<cfargument name="bUseInstanceCache" type="boolean" required="false" default="true" hint="setting to use instance cache if one exists">
		
		<cfset var stobj=structnew()>
		<cfset var tablename=getTablename()>
		<cfset var aprops="">
		<cfset var sqlSelect="">
		<cfset var i=0>
		<cfset var qgetData="">
		<cfset var key="">
		<cfset var qArrayData="">
		<cfset var aTmp=arraynew(1)>
		<cfset var stArrayProp=structnew()>
		<cfset var col=0>
		<cfset var j=0>
		
		<cfparam name="instance.stobj.typename" default="#tablename#">

		<cfif isdefined("instance.bgetdata") AND instance.bgetdata EQ arguments.objectid AND arguments.bUseInstanceCache>
			<!--- get local instance cache --->
			<cfset stObj = instance.stobj>
			<cftrace type="information" category="coapi" var="stobj.typename" text="getData() used instance cache.">
			
		<!--- todo: prototype object manager --->
		<cfelseif structkeyexists(application.objectbroker, instance.stobj.typename) AND structkeyexists(application.objectbroker[instance.stobj.typename], arguments.objectid)>
			<cfset stObj = application.objectbroker[instance.stobj.typename][arguments.objectid]>
			<cfset instance.bgetData = arguments.objectid>
			<cftrace type="information" category="coapi" var="stobj.typename" text="getData() used objectpool cache.">
			
		<cfelse>
			<!--- build a local instance cache --->
			<cfinclude template="_fourq/getData.cfm">
			<cfset instance.stobj = stobj>
			<cfset instance.bgetData = arguments.objectid>
			<cftrace type="information" category="coapi" var="stobj.typename" text="getData() used database.">
			
			<!--- todo: prototype object manager (populate pool) --->
			<cfif structkeyexists(application.objectbroker, instance.stobj.typename)>
				<cfset application.objectbroker[instance.stobj.typename][stobj.objectid]=duplicate(stobj)>
			</cfif>
		</cfif>
		
		<cfreturn stObj>
	</cffunction>

...

...

Broker Overview

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.

Objectbroker 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, object broker can also manage caching of all views. A view is like a fragment of output, such as HTML. Generally a page request is made up of one or more views. Objectbrokers 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.

How to activate the ObjectBroker

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

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.

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"

Dealing Pagination & other URL changes

In some cases you need the view to respond to changes on the URL. 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.

You can have webskin caches dynamically keyed by a hash of the pages URL by including the @@hashURL template level metadata, for example:

<!--- @@displayname: Article Pagination Rule --->
<!--- @@description: A bit of blurbage about what this rule can do. --->
<!--- @@author: Mat Bryant (mat@daemon.com.au)--->
<!--- @@hashURL: true --->

Note: you only have to include this directive inside the webskin that responds to the URL parameter. If this webskin is embedded inside another webskin the system will automatically determine what additional caches would need to be flushed in the event of a change in URL parameter.

Object Broker Webtop Report

You can check which content types have been activated for the object broker by running the Objectbroker Report in the webtop Admin section. This should indicate those content types using the objectbroker, their maximum threshold and the current number of objects in the broker.

Image Added

Basic process flow

1. on fourq.getData() calls
   • check typename.objectpool for UUID
     • if present
       • return struct
     • if not,
       • make dbgateway call
       • check if room in objectpool
       • purge/update aobjects FIFO list as required
       • update objectpool with object struct
       • return struct
     • update cache stats (no cache stats implemented at this time 20070505)
2. return object struct to content type call exactly as per original

In memory structure of object broker