Adobe ColdFusion Docs team, there's a better way...

I'm not a fan of the approach the Adobe ColdFusion (ACF) documentation team has moved to with documentation for the recent versions of their product.

A bit of background

With the recent (late May 2014) release of ACFv11, there are now three versions of ACF in which I have varying degrees of interest: 

• v9: we are in the final stages of moving our last app from a shared v9 server to one of our dedicated v10 servers,
• v10: our entire dev environment is based on v10, and all of our apps with the noted exception above run on v10 in production, and
• v11: the recent release we've watched from a distance as we weigh whether to continue with ACF in the future or shift to Railo as our CFML engine.

As a team, we've been on ACF since its Allaire v4 days, and have historically had multiple versions in play across our development and production environments, so the above situation covering three versions is very typical for us. In fact, having all of our dev and production environments based on a single version of ACF as we (almost) do now represents the first time in close to 10 years we've been able to achieve this. I don't believe we are unique in this: any developer moving between versions of the product (or even considering such a migration) will be working with at least two versions of the language and/or the documentation before and during their migration effort.

In addition, I built and continue to maintain a CFML language mode for ActiveState's Komodo IDE and Edit editors, providing syntax highlighting and tag/tag attribute completion. The tag/tag attribute completion is specific to each CFML version, allowing the user to designate which version of the language is to be used as the basis for which tags and which attributes are to be provided as options to the user. I rely heavily on version-specific documentation to build each of these version-specific implementations.

The problem with the current wiki approach

In versions of ACF up through v9, each version had comprehensive documentation sets available both online and as downloadable PDFs. Each of these documentation sets were separate and distinct, and the online versions made it very straightforward to shift between versions. With v10, however, there is a downloadable PDF version of the documents (thanks to Adam Cameron for pointing me toward those) but the only references to it I can find are not easy to find (search the wiki for "archive" -- how obvious is that if you are looking for CF10 documentation?). The online version of the documentation is maintained as part of a wiki that does not contain discrete sections for different versions of the product or language and for the most part appears to be focused on v11.

The old version of the online docs has the tremendous benefit to the user of being crystal clear as to what capabilities are available in that version of the language (e.g., which attributes are available for a given tag, what functions/function arguments are available). If I am working on an app currently running on version "x" of ACF, I typically want to see only the version "x" documentation for that tag.

The current wiki-based documentation set, however, does not have that clear distinction between versions of the product or language. This makes differentiating between versions for tags, attributes, supported attribute values, functions, etc., in terms of what is valid and supported between versions far more challenging and error-prone than in previous versions. If I care about the v10 implementation of the cfzip tag, for instance, I have to either use the off-line version of the docs or make sure I look at the "history" portion of the relevant tag page and then mentally remove the new attributes added for v11 ("password" and "encryptionalgorithm", in this particular case) as I scan down through the attribute documentation -- particularly given that there is nothing within the description of the attributes indicating their recent addition in v11).

A better approach?

It seems to me that a better approach would be for separate, discrete version-specific sections within the wiki. The language reference -- along with the supporting documents identifying additions, removals, and deprecations -- is one example of where this would make the documentation much easier to use. The v10 portion of the reference would always be specific to v10 and would not (should not?) need to contain any v11 content. The v11 portion of the reference would presumably start as a clone of the v10 portion of the documentation, and could evolve along with the language as v11 was developed. As work on v12 is started, the v11 portion would be cloned as a draft and evolve independently from the sections covering previous versions.

The current wiki approach is likely to get more and more unwieldy as additional versions of the product and the language are covered within the current wiki structure. Take the page listing deprecations and removals as an example. Besides being in drastic need of updates as of this writing for completeness and currency with v11, this page -- based on its current structure -- will get more and more unwieldy as additional versions have to be covered: more rows to cover features being deprecated or removed, and more columns for subsequent versions? The current approach just does not seem to scale for pages such as this.

Note that this is not a problem with the use of a CMS or wiki for the documentation itself as much as it is a poor decision, in my opinion, on how to structure the documentation within the tool they selected.

Finding documentation for earlier, but still-supported, versions of a product should not be difficult but in this case it is getting harder. I'd like to believe the ColdFusion documentation team will see the light and restructure the documentation set before it collapses under its own weight and degenerates even further in terms of being usable and useful.

And the off-line docs?

The current wiki structure -- where it seems to be focused mostly on the current language version -- also raises the question for me as to whether a similar set of downloadable v11 references will be made available now that the product is available or as the wiki gets refocused on v12. That's a separate but important and relevant question. I hope they do, as those downloadable PDFs have repeatedly proven invaluable for me and my team.

A Gotcha with Enabling J2EE session in Adobe ColdFusion on Apache Tomcat

I've spent a bit of time over the past month or so playing with setting up a couple of my development systems to run Railo and Adobe ColdFusion 10 on a stock install of Apache Tomcat 7. In the case of ACF10, my interest in running on stock Tomcat is based on a desire get away from the custom-built and now outdated version of Tomcat Adobe (unwisely, in my opinion) bundles with ACF10. This past week I bumped into a bit of a gotcha that took me quite a bit of time to track down and solve. In the hopes of helping others avoid this same problem and so that I don't forget it, I'll share what I ran into and how to solve it.

The symptoms I was seeing were that as soon as I enabled J2EE sessions in the CF administrator and then subsequently stopped Tomcat for any reason, Tomcat would no longer start cleanly,it was no longer bringing up the context running ACF, and because it was not starting cleanly it would also not shutdown cleanly. As weird as this seemed (and sounds, I realize), this was very repeatable. I had it down to something I could reproduce in under 5 minutes: set up a clean new Tomcat install, deploy ACF10 on it via a WAR file, sign into the CF admin, enable J2EE sessions, stop Tomcat... and it would no longer start. There was nothing in the ${CATALINA_BASE}/logs/catalina.out log file indicating what was wrong; it just looked like as Tomcat began starting, it would hang.

It seemed like something about turning on J2EE sessions in ACF10 was breaking Tomcat. Based on a suggestion from a co-worker, I removed write permissions for the user under which Tomcat was running from all folders under ${CATALINA_BASE} except the ./logs/ and ./webapps/ folders, in an attempt to see if I could determine where the breakage was occurring. On starting Tomcat, I noticed a complaint in the ${CATALINA_BASE}/logs/catalina.out log file about not being able to write to folder ${CATALINA_BASE}/work/Catalina/localhost/_. Looking in that folder, I found a file named SESSIONS.ser and doing a bit of Googling, I came across a short blog post dealing with session persistence across Tomcat-restarts.

I'm not going to pretend that I know why Tomcat would have session persistence enabled across restarts, or why I might want to persist sessions across restarts (I really can't come up with a scenario where I would want that), or why enabling J2EE sessions in ACF10 would seem to break this persistence... but clearly it does. To disable this persistence, the context(s) within Tomcat on which ACF10 is enabled need to include a session manager component specifically configured to disable this persistence:

<Manager pathname="" />

This is touched upon in the Apache Tomcat docs here.

Wrestling with expired chart images in Adobe ColdFusion

TL;DR

Change the timeouts specified in webcharts3d.xml

Long Version

We are in the midst of migrating several existing Web applications to Adobe ColdFusion 10 (ACF10) as part of a server consolidation effort at work. One of these apps has a page that takes a Web-eternity to generate (over 30 seconds, in some situations based on load and other what the user has opted to include) based on the sheer volume of data that has to be digested, and includes several charts created by invoking cfchart. For years, we've struggled with situations where the chart images in this particular report don't show up and instead are replaced with placeholder images indicating the image has "expired". In spite of playing with the limited configuration options related to chart caching in the ACF administrator UI, we've never really found a way to ensure the chart images don't expire. (And, yes, we've invested a significant amount of time to improving the efficiency of the logic behind the report and improving performance of the underlying queries used to retrieve the data.) I think we finally made a bit of a breakthrough on this front yesterday.

I was wrestling with this problem on my development server, which although reasonably fast, is significantly slower than our staging server where we are testing this particular app. Because my dev server is slower, the problem with these expired chart images was exacerbated and I was consistently getting this particular report back with all of the images expired: good for testing and troubleshooting, but useless in terms of the report itself. The ACF admin UI provides only two configuration options that seemed relevant to solving the problem: the size of the cache (how many chart images will be cached) and whether the chart images are cached to disk or to memory. The cache size on my dev server was configured at 200 charts, but given that I am the only one who can connect to my dev server, it made no sense that the half-dozen charts on this report could be expiring based on the cache being filled quickly enough to cause them to be expired. They had to be expiring based on something else... age, perhaps?

I verified this by switching the cache to be on disk and watching the content of the folder being used for the cache. In spite of the specified cache size in the ACF admin UI, there were never more than a handful of image files present in the folder. Something other than the number of chart images was at play here.

A quick search of the ACF bug list yielded nothing relevant in terms of a known problem. Searching the ACF forums brought up a couple other topics related to expired images but nothing that on the surface seemed really relevant to what I was seeing. The entry that seemed most relevant was in a clustered environment and seemed to be related to how requests got moved among the various servers in the cluster and how that seemed to be leading to expired chart images. But... in that post there was a reference to an XML configuration file for the underlying charting engine... and a timeout parameter in that file.

The ACF forum post referred to minTimeout and maxTimeout parameters in a configuration file named webcharts3d.xml. At least on my system, that file resides at {cf_home}/cfusion/lib/webcharts3d.xml. Locate the <server ...> element near the top of the file, and adjust the minTimeout and maxTimeout attributes. On my system, they were set to 5000 and 30000, respectively, which I believe to be 5 and 30 seconds. When I saw those values, I was convinced I had found my solution, as it seemed like when the report in question took more than 30 seconds to generate, I was consistently getting the expired images. Recognizing that this long-running report can take as long as a couple minutes to generate under load, I changed the minTimeout attribute to 120000 (120 seconds) and the maxTimeout attribute to 300000 (5 minutes). I saved the file and bounced ACF on my dev server, and... no more expired images. Watching the cache folder, I started seeing images pile up (as I would have expected). Problem solved.

Having said that, I still have a couple questions:

1. What exactly do those configuration parameters in the ACF admin UI for cache size and number of threads actually control (if anything)?
2. Is there documentation somewhere for the webcharts3d.xml file, explaining what the cache, minTimeout, maxTimeout, cacheSize, and maxThreads attributes do? Several of those have similarly-named settings in the CF admin UI but updating the CF admin UI values does not touch this file. So far, I've not been able to find any documentation on-line.

As is often the case, now that I have some idea of how to solve the problem, I can find at least half a dozen posts or articles via Google describing the solution. With this post, there is now one more.

And for the record, this just might be the first time I've found something of value in the ACF forums, but that's a topic for another post and another day.