Default

Normally in patch releases we do not introduce new functionality. Except if they don't affect the runtime behaviour of Railo Server. With the latest release of Railo Server (3.3.1.007) we have introduced two new features I would like to present in more detail.

Support for Query coverage

Now when you pull a query from the database, you can check your debugging output for a percentage of how much the columns of your queries has been actually used in the code. First of all you need to activate the query coverage display in the admin under debugging:

Once activated, if you for instance execute something like this:

<cfquery name="get" datasource="ds">
Select * from countries
</cfquery>
<cfoutput>
<cfloop query="get">
#get.countryShort#: #get.countryLong#<br>
</cfloop>
</cfoutput>

And your countries table has 5 columns. The coverage of that query lies at 40%. This is then displayed in the debugging information like follows (in this example I use the debugging console):

Support for Comment Metadata

General syntax and notes

Another new feature we have introduced is the idea of Comment Metadata (also known as annotations). In Railo we would rather call them "doc comments" since Railo will only check for added metadata if a doc type comment is found in the code. So the comment must look like the following:

/**
*
...
*
*/
function ... { }

So what you now can do in Railo Server is:

/**
* my Hint
* @prop1 Property 1
* the rest of the hint
*/ function test(arg1){ }

Now if you call getMetaData(test) you will get a struct that contains additional keys (in this case prop1). Other implementations allow you to define each possible argument of a function in annotation style, just like this:

/**
*
@returntype string
*/
function test(arg1) { }

This notation and thus the functionality behind it means that comments are affecting the code's behaviour, which we will intentionally NOT support.
Take the following example that throws a compiler error:

/**
* @returntype string
*/
public int function test(arg1) {
}

In our opinion you should never receive a compiler error because of a comment you have made in your code. So even the following would throw an error, which is wrong since it IS just a comment:

/**
* please never ever use the comment
@returntype since this might crash
something in the compiler.
*/
public int function test(arg1) {
}

So Railo always ignores definitions which contain doc comments that might interfere with allowed arguments of a function definition (like output, returntype etc.).
Another case is that Railo Server will never ever throw an exception if something is wrong in the doc comment or meta data for a param which is defined inside the comment and also within the statement.
In short, the doc comments will only provide data for the return of the function getMetadata() and nothing else.
So how does one use it?
/**
* test
* @susi sorglos
* update
*/
Generated metadata:
/**
* test
* @
* update
*/
Generated metadata:
/**
* test
* @arg1. susi
* update
*/
function test(arg1){}
Generated metadata:
in ACF: {"":"susi"}
ignored in Railo, thus producing: {}

/**
* test
* @susi "Sorglos"
* update
*/
Generated metadata:
/**
* test
* @susi "Sorglos
dried her hair"
* update */
Generated metadata:
In this case Adobe ColdFusion only removes the starting quote ("), but not the ending quote("). Railo only removes quotes (") if there is a quote (") at start AND at the end of the line. We are thinking of changing this to allow multiple line definitions for metadata, so that the above code would result in metadata for susi that would contain the value "Sorglos dried her hair" (including the quotes of course).

/**
* test
* @hint "Susi Sorglos"
* update
*/
Generated metadata:

Defining argument hints in cfscript

What you can also do is to define your hints for certain arguments within cfscript.
Let's have a look at the code below for details (both function definitions define the same function):

/**
* @arg3.urs hallo
* @arg3.peter halli
*/
function testFunctionScript(argument1='something' myannotation='something', string arg2="" susi="sorglos", numeric arg3 urs="ursula") {
return 'something';
}

<cffunction name="testFunctionTag">
<cfargument name="argument1" myannotation="something">
<cfargument name="arg2" susi="sorglos">
<cfargument name="arg3" type="numeric" urs="ursula" peter="halli">
</cffunction>

Generated metadata:

As usual, comments are warmly welcome

It has been two years today that I have been working at Railo Technologies and it gives me great pleasure to announce that Denny Valliant (@denstar) has just joined the team!