Clearing the #ColdFusion template cache programmatically

While it's basically just a single line of code, my regular readers won't be surprised to hear that I feel there's a lot more you ought to know or consider about using that code! So while the code below may be all that some readers need, I hope folks will take time to consider the other related matters I raise. At least scan the headlines to decide. :-) (Indeed, I'm even leaving a more detailed discussion of the Admin API and the template cache in general to another day.)

The code

So here's just one variant of some code one could use to clear the template cache. It can of course be done using tags (CFOBJECT vs createObject) and could be done even more compactly in script. Those preferring other styles can take this ball and run with it.

About the code

The first couple of lines are to "log in". Just as one can't use the CF Admin without a password (unless the Admin has removed that requirement), one can't use the Admin API without knowing the Admin login.

The next couple of lines obtain a reference to the runtime CFC, which has the method to clear the template cache. Sadly, the engineers called it "cleartrustedcache". It should have been called clear cleartemplatecache, but they've never seen fit to change it.

(The method does NOT clear any "trusted cache". There's no such thing. There is a template cache, and the "trusted cache" setting, also available on the CF Admin "Caching" page, simply changes how CF processes files found in the template cache--whether it should check the source to see if it has changed. Again, this entry is not the place to elaborate on that.)

Why would one want to clear the template cache?

Again, I don't want to elaborate on the details of template caching, but I'll just say briefly that at least one reason one might want to clear the template cache is because they're using the "trusted cached" feature (also set on the CF Admin "Caching" page), which causes CF to no longer look at the source code on disk to see if it's changed, once a template is loaded in the template cache. If a developer changes a template and wants CF to pick it up (while "trusted cache" is enabled), they can clear the template cache to cause CF to pick up the change. (I'll have more to say on options to limit clearing the *entire* template cache, later in this entry.)

Note that you don't need to clear the "trusted cache" setting. Just clear the cache. (Also, turning off the "trusted cache" setting does not itself clear the template cache.)

Let's now move on to some nuances of clearing the template cache.

Clearing all vs some of the cache

Note that this cleartrustedcache function will by default clear the entire template cache, across all templates and applications on the CF instance. You might reasonably wonder "isn't that throwing the baby out with the bathwater? Why can't we just clear the template cache only for a given template or folder?"

And the good news is that Adobe has indeed addressed that, a couple of ways.

As of CF8, clearing template cache entries for given file(s)

First, as of CF 8, there's a new option for this cleartrustedcache method of the Admin API. Note the commented out final line above, showing use of the optional new argument to clear the template cache for only one or more named templates, which indicated as a comma-separated list of full path\filename values.

Do you find it a hassle to have to do that by code? Wish there was a way to do it via a web page (or in the CF admin)? Well, Ray Camden comes to the rescue with both an Admin extension that adds an admin page to do this, which he calls CacheClearer, or check out his simpler web page/form that he created to do this as well, discussed in this blog entry.

(And if you need to know how to add extensions to the CF Admin, which are new links in a new page that gets created when added, see Ray's nifty guide to using those.)

As of CF10, clearing all template cache entries for given folder(s)

While it's nice that CF 8 added the ability to clear the entries for a given file or list of the, sadly you can't specify just a folder and hope it will clear all the template cache entries for files in that folder and subfolders, at least, not until CF 10, which adds a couple ways to do just that.

First, in the CF 10 Admin "Caching" page, there's not only the long-existing button (since CF7) to clear the entire template cache, but there's now a new field and button (under the label, "Clear folder specific template cache") with which you *can* now in fact point to a directory, and tell it to clear the template cache entries only for files whose source came from the given folder, recursively.

Second, CF10 also adds a new method in the API to do this action also. It's not a new argument but a new method: clearTemplateFolderFromCache, and it takes as an argument a directory, and it again will clear the template cache of entries for files whose source came from the given folder, recursively.

What about clearing it automatically

A natural follow-on question to all this would be, "can't we just set things up so that CF just watches a directory, and whenever a file is changed, it automatically clears the template cache for that file(s). Well, there's nothing built-in to do that, but you can make it happen yourself, using the DirectoryWatcher gateway (another feature introduced in CF7). Again, this entry is not the place to elaborate on that.

But it could be set to watch a given diretory(ies) and then if a file changes, it would call a CFC that you could write, which could then call this AdminAPI method. If anyone's already written that, please do share a comment here.

The template cache is about compiled CFML code stored in memory, not on disk

Just a couple more points of clarification before we conclude.

I really don't want to delve into general matters of CF's template caching here, but it seems worth heading off a couple of questions "at the pass".

First, note that this matter of clearing the template cache is all about the template cache in memory, which holds the compiled CFML code for templates that are executed during the life of the instance (or until the cache fills, whose size is also controlled on the CF Admin "Caching" page).

On that same page there's another option called "saved class files", which causes CF to saved those results of the compiled templates (.class files) to disk as well, in a cfclasses directory buried deep within the CF directory.

My point in raising this here is that this cleartrustedcache method does ONLY clear the templates from memory. It does NOT clear them from that cfclasses directory. (And generally, you should not have any reason to clear those, which is why there is no function or method to do that. Again, this is not the place to get into an extended discussion of the "save class files" option, when and why to use it, how to resolve problems with it, etc.)

This template cache is not THAT template cache

Second, there's some real potential for confusion when it comes to talking about "template caching" in CF, because CF9 introduced the integrated ehCache functionality, which adds all kinds of power for caching objects, whether strings, CFCs, queries, or even page output (whether a full or partial page). And the engineers chose to refer to the latter (caching page output) as "template caching".

Well, this CF Admin template cache (holding compiled code) is not THAT template cache (holding objects or page content that you have stored via code). They are entirely unrelated to each other, and the CF admin settings (and admin API method above) all apply only to the former, not the latter.

How can I find more about methods in the Admin API

Again, I don't want to get too far into general discussions of the Admin API, but it seems worth pointing out that while you won't find much documentation on the Admin API, you can find details about all the methods in the Admin API, by simply browsing each CFC in the API (they're in the /CFIDE/adminapi/ folder). So for instance, the following request would browse the runtime.cfc in which the cleartrustedcache (and many other methods) would be found:

When you run that, you should be shown the built-in (and oft-missed) CF component browser tool, which will ask you for your CF Admin password. Some day I should do an entry about that tool! :-)

You'll see there are also methods related to other separate but related buttons on the CF Admin "Caching" page, such as one to clear the component cache added in CF9), clearcomponentcache, and to clear the query cache: clearquerycache. See the help there for more on those and all the other CFCs in the Admin API.

So there you have it: go forth and clear your template cache when you need to, programmatically. And hopefully you'll appreciate now why I really couldn't just leave it at showing just the one line of code!