Adam Tuttle

Introducing Moment.cfc

Today I'm releasing a new open source project, moment.cfc.

If you've ever used moment.js calm down, because I promise you this isn't quite as awesome as that. If you haven't used moment.js —first of all, get on that!— it's a great little library for dealing with and manipulating dates and times in JavaScript. They also have a newer companion library for dealing with time zones in JavaScript.

While moment.cfc isn't as awesome as moment.js, it's still pretty rad.

The original motivation was having to deal with time zones in ColdFusion. CF has some limited functionality for converting between local time zones and UTC, but it assumes your server is running in the desired local time and there are no functions for converting between arbitrary time zones. We're working on a big app to be used by nation- and globe-spanning organizations, so time zones are a pretty big deal.

Let me share with you what was on my mind just hours before this project was undertaken:

Assume your DB server and App server are configured to run in UTC. (So dateConvert() with utc2local and local2utc are non-starters right away...). Now imagine this scenario: Your organization's headquarters is on the east coast of the us (America/New_York time zone). You're creating an "event" for people to register to attend, which will be held on the west coast (America/Pacific). And although while you're creating this event it is currently Standard Time, between now and when the event starts, Daylight Saving Time will begin. Pop quiz, hot shot! What do you do? What. Do. You. Do?

If you guessed, "consider quitting your job and opening a lemonade stand" then I was right there with you (with 2nd place going to, "seek out and destroy every computer in the world"). Fortunately I had my friends in the ColdFusion IRC channel to talk me down from that ledge.

The answer, of course, is that DST "doesn't matter" (in that it's an entirely human concept) and if you schedule an event for 5pm Pacific time on Thursday, it should display as 5pm Pacific time on Thursday, regardless of DST coming and going. If you store all date/times in UTC and use smart conversion functions, they'll take care of the rest themselves.

If only there were a way to make that time zone math easier in ColdFusion. There isn't. Yet. But all is not lost. As much as I like to bemoan Java for its complexity and verboseness, it saved my bacon this time. java.util.TimeZone to the rescue.

After a few hours spent reading the documentation, and some blog posts, and fiddling with trying to find the right syntax to get it to instantiate and run from within CF, I had a super basic proof of concept that I could specify a time in an arbitrary time zone and convert it to UTC or any other time zone of my choosing.

I was pretty thrilled with this, but then I had a light bulb moment...

Light Bulb!

I could turn this into a moment.js-like tool for CFML. And thus was born moment.cfc. It's not a port of moment.js (there are many features I've skipped for now, or because I think they just aren't necessary), but it is heavily inspired by its namesake.

Allow me to give you a taste of some of the syntactic goodness:

Adobe CF moment.cfc
x = now(); x = new moment();
y = createDateTime( 2008, 11, 27, 13, 47, 0 ); y = new moment( '2008-11-27 13:47:00' );
x = dateAdd( 'ww', 1, x ); x.add( 1, 'week' );
y = dateAdd( 'n', -30, y ); y.subtract( 30, 'minutes' );
diff = dateDiff( 's', x, y ); diff = x.diff( y, 'seconds' );
before = dateCompare( now(), x, 'h' ) == -1; before = x.isBefore( y, 'hours' );

And as promised, it makes time zone conversion, including UTC, a breeze:

  • event = new moment( '2015-03-26 17:00', 'America/Pacific' );
  • utc = event.utc();

There are around a dozen methods available, with more coming soon, so if you really want the nitty gritty, you should read its documentation. And there is (almost) 300% more code lines in the tests (829) than in the component itself (305): it's pretty well tested.

As for me, when I signed off on Friday with these time zone thoughts swirling around my head I was dreading coming to work on Monday morning. Now I'm excited to get in there and kick some butt!

ColdFusion and ORMReload()

If you use ColdFusion's ORM (layer on top of Hibernate), then chances are pretty good you've needed to run an ormReload() now and then to pick up changes to your entity definitions. In our application, I've been having a minor nuisance getting this to work as intended, and I think I've finally figured out why.

Let's consider my ORM settings:

this.ormenabled = true;
this.ormsettings = {
    dbcreate="none"
    , logsql=false
    , cfclocation= ["/orm"]
    , flushAtRequestEnd=false
    , useDBForMapping=false
    , dialect="MySQL"
};
if (getEnvironment() eq "dev"){
    this.ormsettings.dbcreate = "update";
}

The intention is, on all environments other than my local machine, to block ormReload() from doing its job. In those scenarios, we're willing to jump through a few extra hoops to deploy our changes for the sake of safety; but during DEV you just want to be able to make changes and have them quickly picked up.

The only problem was that getting ORM to detect changes and actually do the ormReload() seemed to always require a CF service restart. It happens so infrequently that it was hard to remember if it requires a service restart every time, or just seemingly every time — but just often enough to be annoying.

As it turns out (I think), this bit of cleverness seems to have been too clever for Adobe ColdFusion. (I've not tested on Lucee.) It appears as though the very first time the value for this.ormsettings.dbcreate is set is the only value that is ever used. So, in the above case, where we default it to "none" but then overwrite it to "update" on development machines, ACF never noticed — or never cared that it changed. It would also seem that it wasn't the service restart + ormReload() that caused my changes to be picked up, but just the service restart itself.

It took explaining this frustration to our new developer, with the code in front of my face, to have my lightbulb moment.

I've since changed the code to the following:

this.ormenabled = true;
this.ormsettings = {
    dbcreate=(getEnvironment() eq "dev" ? "update" : "none")
    , logsql=false
    , cfclocation= ["/orm"]
    , flushAtRequestEnd=false
    , useDBForMapping=false
    , dialect="MySQL"
};

And now everything is peachy. Does this account mirror your own experiences, or am I losing my marbles?

ORM and Transactions in ColdFusion

This has been written about a few times already by others in the community, but it still seems to be something that many people don't understand, so I thought I would put my oar in too. Truth be told, I thought I understood it but recently I learned that I still had a few details wrong.

ColdFusion's ORM (Hibernate) does not commit your changes to the database until the end of the request, by default.

That's an important thing to know, because there are other control-flow directives, like locking, that might lull you into a false sense of security if you're using the default behavior, and it could end up causing you grief.

Here's the ORM settings right out of an application I've been working on lately:

this.ormsettings = {
    dbcreate="update"
    , logsql=false
    , cfclocation= ["/orm"]
    , flushAtRequestEnd=false
    , useDBForMapping=false
    , dialect="MySQL"
};

Please note the line flushAtRequestEnd=false. This is explicitly disabling the default behavior I described above. When you do this, you have to tell Hibernate when to commit ("flush") the changes ("session") to the database. There are two ways to accomplish this: Either follow every call to entitySave() with a call to ormFlush(), or wrap your changes in a transaction.

The former approach bugs me, because I feel like I'm required to call two functions to do one thing. I know that the transaction approach does exactly the same thing, but I still feel better looking at transactions in my code.

Let's consider some code:

list = entityLoadByPK("List", 11);
list.setName("my new name");
transaction {
    entitySave( list );
}

On which line is the list name change committed to the database? If you said line 4, I have some bad news for you. It's line 3. To further illustrate this point, consider this slight modification to the same code:

list = entityLoadByPK("List", 11);
list.setName("my new name");
transaction {}

If you run this code, you'll see that your list's new name has been updated in the database after line 3 — and we never called entitySave() on it.

ORM is flushed at every transaction boundary. That means as you enter a new transaction, or exit a transaction, all unsaved ORM changes will be flushed to the database. This is in stark contrast to the way that transactions work with standard database queries using the <cfquery> tag or the queryExecute() method.

The only way you'll be able to roll-back ORM-based changes using transactions is to make the changes and issue the rollback all within the same transaction:

x = entityLoadByPK("List", 11);
transaction {
    x.setName("this change will be rolled back");
    transaction action="rollback";
}

As a rule of thumb, partially just to keep things tidy, we always load the entity within the transaction, too:

transaction {
    x = entityLoadByPK("List", 11);
    x.setName("this change will be rolled back");
    transaction action="rollback";
}

As ever, the best resource for ORM information in ColdFusion is John Whish's book ColdFusion ORM.

Elvis Is (Back) in Production

Remember how I gave Adobe a really hard time about their fumbling of the Elvis operator (among other things) in ColdFusion 11 Update 3?

Today they released Update 4 in the stable update channel. Of course, there were two pre-releases of this patch, so if you were willing to run beta software in production, then you could already be ahead of the game on this one. As a policy, we don't run pre-release platform patches in production.

I wish it would have been released in the stable update channel sooner. The last pre-release refresh was on January 27th. That's 3 weeks and 2 days ago. I think 2 weeks is a pretty good testing period. But, it's been released, and it works —I tested it pretty thoroughly, at least as far as the Elvis operator is concerned. I've already installed it on our production server. So I won't give them too much grief over the timing.

If you're wondering why I cared so much about the Elvis operator, I present to you a sample, in the form of a diff of the awesome terseness that is ?:. These are just a few of the changes that I had sitting in a branch waiting for this day.

What I do think they still could have done better is the updating process, though. It's very evident that Adobe haven't figured out how to use the updater in situations like this.

When I refreshed from the first pre-release to the second, I had to uninstall and re-download the patch. Granted, it was point-and-click through the updater, but... isn't the whole point of having the updater to prevent the tedium of steps like "uninstall, re-download"? I would seriously consider the folks at Adobe read up on semver. The updater should be able to handle all of these situations flawlessly, without the need for manual deletion and re-downloading.

v11.0.4-beta1 is, by semver definition, less than v11.0.4-beta2. And v11.0.4 is by semver definition, greater than both of them. The updater should see all of these version numbers, regardless of which channel was used to install whatever updates are currently installed, and know how to get from point A to point B, with a single "upgrade" button.

Instead, you must:

Re-download

  • Go to the Installed Updates tab, and click the Uninstall button
  • Wait for the service to restart
  • Go to the Settings tab, and click the Restore Default URL button (thank god we got them to add that)
  • Restart the service manually. This isn't listed as a required step, but I always do it because I don't trust them to get it right without a server restart.
  • Log back in, go back to the Server Updates section, Available Updates tab, and click the Re-download button, because apparently the new update looks like the old one to the updater and it thinks you already have the stable release. You don't.
  • After it downloads, click the Install button, and wait for the service to restart

Is this better than the old process? Sure. Is it "good" yet? Nope.