ColdFusion 9 Property Annotations

09/22/2009 | ColdFusion | 15 Comments

I actually came across this feature while listening to the cfhour podcast. A lot of this came from the basis of the new quicksilver framework . I knew that you could use annotations in comments for properties and components. This is an example of component written in script that describes attributes of the component and properties using annotations. These are all attributes that are all documented and can be used in tag versions. /** * @output false * @extends AbstractEntity */ component { /** * @ sqltype integer */ property userId; }

This is great but its really just another way to describe the component or property using another method. What if you wanted to provide your own custom attributes to the property or component? You can do so by simply adding them to the comments right above your property or component. It's important to note that /** is different than /*. With this in mind I thought this would be a great place to be able to sprinkle validation in to my Entities. In this example I have a user entity that I have defined some custom attributes. /** * @output false * @extends AbstractEntity * @myCustomProperty true */ component { /** * @sqltype integer * @generator increment */ property numeric userId; /** * @NotNull */ property string firstname; /** * @NotNull */ property string lastname; /** * @NotNull * @Length min=30,max=100 */ property string username; /** * @NotNull * @Length min=30,max=100 */ property string password; /** * @NotNull * @Email */ property string email; }

That is great but as it is right now it really is not much help to us because we have no way to get that data. Well thanks to ColdFusion 9 we actually do. The getMetaData will actually give us back the annotations. <cfset user = new model.User()> <cfdump var="#getMetaData(user)#"> If you look at the dump of the meta data you will notice that we have an array of properties with a key/pair value for each annotation we defined. This gives the ability to add some really cool functionality to our applications.

This to me is just awesome because it allows us to sprinkle some extra functionality into our components very easily. With this new found knowledge we could also create some handy methods in our Abstract Entity. /** * @displayname Abstract Entity * @hint I am base component for all domain models to extend * @output false * */ component { public array function getProperties(){ var props = getMetaData(this).properties; return props; } public string function getPropertyList(){ var props = getProperties(); var propList = ""; for(i=1; i <= arrayLen(props); i++){ propList = listAppend(propList,props[i].name); } return propList; } }

I had no idea any of this was possible until I really started looking the new QuickSilver framework and listening to some podcasts. If you want to learn more about the framework I would listen to the 1st episode This Week In ColdFusion.

*** UPDATE ***
It is important to note that this can be done using tags as well.

*** UPDATE ***
Apparently this can be done in older version of CF, that is news to me. You could not do this in script in older version so to me its a new feature!

This entry was posted on September 22, 2009 at 10:32 AM and has received 4657 views. Comments 15 | Print this entry.

TweetBacks

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)

[Add Comment] [Subscribe to Comments]

#1 by Steve 'Cutter' Blades on 9/22/09 - 10:03 AM

@Dan -

Your first block of custom properties somehow didn't get the <code> formatting.
#2 by Dan Vega on 9/22/09 - 10:04 AM

I saw, should be fixed now!
#3 by Steve 'Cutter' Blades on 9/22/09 - 10:04 AM

Wow! Quick catch! Got it before my comment submitted
#4 by Tony Garcia on 9/22/09 - 10:11 AM

This isn't only limited to CF9. I've been using annotations and the getMetaData() function in CF8 (and Railo) for a while now. Although in CF8 the annotations have to be in the <cfcomponent> or <cffunction> tags as custom attributes. i.e. <cfproperty name="mproperty" myAnnotation="myValue" />
#5 by Dan Vega on 9/22/09 - 10:24 AM

@Tony - I just found out that this can be done in earlier versions. You learn something every day!
#6 by Mike Chandler on 9/22/09 - 11:42 AM

Annotations aren't new to CF9, you're correct. It's the ability to use annotations in cfscript that's new.

The Quicksilver guys are all about brevity in their source code when it's possible and when it makes sense, hence their enthusiastic response to annotations in script.

And thanks for the link to the podcast!
#7 by Dan Vega on 9/22/09 - 12:01 PM

Thanks Mike - Keep up the great work, loved the 1st episode!
#8 by Tony Garcia on 9/22/09 - 12:47 PM

So basically the features were already there but now with CF9 you can implement them (as well as just about everything else) in cfscript. I guess since I was already using annotations and I'm partial to tags, I didn't see anything new about this. But I do think it's cool that more people are starting to use annotations and metadata in their development. For me, I rather use this for configuration than XML. The ColdBox framework leverages annotations and metadata for dependency injection, where you can use custom attributes and cfproperty tags to tell the framework how to autowire your components.
I have made a decision to start using cfscript, more, though, just to "broaden my horizons." The thing I don't like about the examples above are the JavaDoc style comments to describe components and properties. Something just doesn't feel right to me about comments having an impact on the code. I'm not the only one who feels this way (see the comments in this blog post: http://www.bennadel.com/blog/1662-Learning-ColdFus...).
I'm probably more likely to use the other style of syntax where you put your custom attributes alongside your propery declaration (or just below the component declaration before the opening curly brace):

property name="myProperty setter="false" myCustomAttribute="value";

or

component
output="false"
myAnnotation = "something"
{...
#9 by Mike Chandler on 9/22/09 - 1:45 PM

Hi Tony, those are fair comments. Regarding the remark "Something just doesn't feel right to me about comments having an impact on the code." I'd have to let the Quicksilver guys comment on this, but my take on it is this... The annotations in the comments allow you to define application parameters, such as dependency injection for example, without having to depend on XML configuration files. And since they are comments as you pointed out, you can detach from the framework without having to "gut" the application.

Preferences are preferences, of course, so I certainly understand that some will lean one way versus another!
#10 by Dan Vega on 9/22/09 - 1:49 PM

I understand people are going to go both ways on this but for some reason this just does not look right to me

property name="myProperty setter="false" myCustomAttribute="value";

I like the idea of writing

property string myProperty;

Also I keep hearing about these huge impacts on code. I will try and write a component with a huge number of annotations and one with none and see if there is a significant difference. My guess is no because in both cases its looking for them one, to collect can't be a huge hit at all.
#11 by Brian Carr on 9/22/09 - 2:31 PM

@Mike @Tony I agree. Preferences are preferences and developers of course should work with that which they feel most comfortable. In the case of cfscript, once a comment is prefixed with the '@' symbol AND directly precedes a programmatic construct that supports meta-information, it is no longer just a comment - it becomes an Annotation and that difference is very important.

The wonderful thing about this latest release of CF is that there are several different ways to leverage the benefits of annotations and chances are there's a way that best suits the individual developer.

@Tony - are you talking about performance impacts?

@Dan excellent blog entry - keep up the great work!
#12 by Tony Garcia on 9/22/09 - 4:37 PM

@Brian,
No, I didn't mean performance impacts. I guess I just feel that comments should be comments and their absence or presence shouldn't have an impact on the _execution_ of the code.
But I do see your point (and Dan's) about how annotations are different. I'm just starting out writing in cfscript I'm still figuring out what my preferences will be and I want to keep an open mind. I guess since annotations are customized "attributes" of your components, properties, or methods it wouldn't be a big deal to keep them in the JavaDoc comments, but I wouldn't use that style for the standard stuff. So I'd do:

component
output = "false"
extends = "baseService"
{

and not:

/**
*@output false
*@extends baseService
*/
component {

(btw -- Brian and Mike, I really enjoyed the first TWiCF podcast and am looking forward to the next one)
#13 by Brian Carr on 9/22/09 - 7:32 PM

@Tony
Glad you liked the podcast!
#14 by Mohamad on 6/25/11 - 1:22 PM

@Dan, is there a meaningful way to leverage annotations in such a way that they provide meaningful feedback to the user? As I understand, CF just throws a regular error, which is not something we want to expose the user to. So I'm curious how/if people have a method to return these errors to the user for feedback!
#15 by Dan Vega on 6/29/11 - 10:20 AM

Mohamad,
Property annotations have nothing to do with error handling. I am sure you could probably leverage them to throw specific errors but again that has nothing to do with this. If you want to provide more information to your users when something happens you can do so by using error handling techniques like try / catch / throw.