ColdFusion Compiler

The ColdFusion Compiler compiles ColdFusion templates (CFM, CFC, and CFR) into Java bytecode. Macromedia provides a command-line interface to the compiler (cfcompile.bat on Windows; cfcompile.sh on Unix). The script is located in the cf_root/bin (server configuration) or cf_webapp_root/WEB-INF/cfusion/bin (J2EE configurations) directory.

You can use this utility for:

• Converting ColdFusion source code into Java bytecode for sourceless deployment of ColdFusion templates

• Precompiling ColdFusion templates into Java class files

The basic syntax for calling the cfcompile script is as follows:

 cfcompile [-deploy] webroot [directory-to-compile] [output-directory] 

It is preconfigured with the options necessary to compile source code into Java bytecode for sourceless deployment, and for compiling ColdFusion templates into Java class files.

Compiling Sourceless Templates

The capability to deploy sourceless ColdFusion templates is one of the most anticipated Cold Fusion MX 7 features. Sourceless means you can deploy your ColdFusion templates (CFM, CFC, and CFR files) as Java bytecode and distribute them without changing the template names or paths. The templates will contain unreadable Java bytecode but will run as if they contained CFML. This makes source code distribution more secure and protects the intellectual property contained in the files. For more information on the security of sourceless deployment, see the "Encrypt ColdFusion Templates" section of Chapter 10.

Use the cfcompile utility with the deploy option to convert the source code of your ColdFusion templates to Java bytecode. The utility will make a copy of your original template and compile the CFML to Java bytecode. The template containing the Java bytecode will be written to a specified destination directory, leaving unchanged your original templates containing CFML. The cfcompile executable is located in the cf_root\bin directory. Use the following command to compile your templates to Java bytecode:

 cfcompile -deploy webroot directory-to-compile output-directory 

Table 6.4 describes the cfcompile parameters for creating sourceless templates.

Table 6.4. cfcompile Script Options for Sourceless Deployment

OPTION	DESCRIPTION	REQUIRED
webroot	Specify the fully qualified path to the web server root directory (for instance, C:\CFusionMX7\wwwroot or C:\Inetpub\wwwroot).	Yes
directory-to-compile	Specify the fully qualified path to the directory containing the templates to be compiled. This directory must be under the specified webroot directory. If omitted, ColdFusion will compile all ColdFusion templates in the specified webroot directory.	Yes
output-directory	Specify the fully qualified path to the destination directory that will contain the compiled deployable files. This cannot be the same directory as the source directory.	Yes

Precompiling ColdFusion Templates

As you may know, the ColdFusion server compiles each ColdFusion template into Java bytecode when the template is initially requestedthat is, the first time after a server restart. When the "Save class files" option in ColdFusion Administrator is enabled, the compiler writes the bytecode into Java .class files on the disk and then copies the bytecode into memory (the Template Cache); otherwise, the bytecode is written directly to the Template Cache. This compilation process increases the initial page request. ColdFusion will continue serving the template from the Template Cache, so that only the initial request takes the compilation hit. Combining this technique with the Trusted Cache option can dramatically improve site performance. Macromedia recommends saving the class files only for production servers.

Use the following command to compile ColdFusion templates (CFM, CFC, and CFR files) into Java class files:

 cfcompile webroot directory-to-compile 

TIP

Notice that the directory-to-compile must be within the specified webroot. If you want to compile templates outside of the actual webroot to class filessuch as templates in a Web server virtual directory called Testingthen specify that directory as the webroot and omit the srcdir parameter: cfcompile C:\Testing.

The compiled class files are stored in the cf_root/wwroot/WEB-INF/cfclasses (server configuration) or cf_webapp_root/WEB-INF/cfclasses (J2EE configurations) directory. The files are renamed using a unique syntax:

 cf + filename + hash code + .class 

ColdFusion uses the following to derive this filename:

• The filename is extracted from a Java File object created from the canonical filename (for example, C:\Testing\hasher.cfm) with the following substitutions:

  Included slashes (/) in the filename are replaced with a double underscore (__).

  Any characters that are illegal in a Java identifier are replaced with their equivalent two-digit hexadecimal number; for example, a period (.) becomes 2e.

• The hash code represents the hash code value created by the Java File object (java.io.File). The hash code is generated by calling the hashCode method; refer to the Java documen tation at http://java.sun.com/j2se/1.4.2/docs/api/java/io/File.html#hashCode().

  If the value returned by hashCode() is negative, it is exclusive-or'd with 0xFFFFFFFF to get the value ColdFusion uses.

TIP

You will also see .class files with a dollar sign ($) in the name followed by a function name, as in cfApplication2ecfc639310892$funcONREQUESTSTART.class. The $ represents the compiled ColdFusion user-defined function (UDF) calls within the file. This is more common for ColdFusion Components (CFC) files, but they will occur for any ColdFusion template containing UDF calls.

ColdFusion Template Deployment Considerations

At first glance, the difference in the command syntax for compiling your ColdFusion templates to .class files as compared with compiling to sourceless code is the deploy option. However, the real difference is the process by which the code is compiled. When precompiling (or not using the deploy option), the compiler translates the CFML into Java bytecode and writes the bytecode to a .class file. When creating sourceless templates, the compiler implements the ColdFusion run-time service, translates the CFML into Java bytecode, and then creates a new template (with the same name as the original) and writes the bytecode into that template. Implementing the run-time service allows the compiler to check the code for syntax errorsas if the code were called from the browser. The compiler will fail and return if there are any errors in your code. The error and stack trace are recorded to the ColdFusion exception log (cfroot\logs\exception.log).

TIP

The deploy option will catch compilation errors, but some run-time errors will not occur until after deployment. For example, "Template not found" errors for cfinclude will not occur until the deployed file is run on the deployed system.

Macromedia provided the cfcompile script with ColdFusion for precompiling .class files. Some developers have tried deploying these files on other systems. Macromedia does not recommend deploying compiled .class files, however, because they are largely dependent on the underlying directory structure of the source server. Some of the class files might actually work on the deployment server. Macromedia created the deploy option to enable the secure deployment of ColdFusion templates.

Customizing the cfcompile Script

You can customize the cfcompile script file that ships with ColdFusion MX 7, or build your own. Table 6.5 provides a complete list of ColdFusion Compiler options. The cfcompile script preconfigures some of these options for you. Examine the preconfigured values to ensure that the script will run on your system.

Table 6.5. cfcompile Script Options for Precompiling .class Files

OPTION	DESCRIPTION	REQUIRED
webroot	Specify the fully qualified path to the Web server root directory (for instance, C:\CFusionMX7\wwwroot or C:\Inetpub\wwwroot).	Yes
directory-to-compile	Specify the fully qualified path to the directory containing the templates to be compiled. This directory must be under the specified webroot directory. If omitted, ColdFusion will compile all ColdFusion templates in the specified webroot directory.	Yes

TIP

You can compile individual files by specifying the fully qualified path to the file instead of just the directory path. For example: cfcompile C:\InetPub\wwwroot C:\InetPub\wwwroot\index.cfm.

With the options in Table 6.5, you can create your own compiler script using syntax similar to the following:

[View full width]
 java -cp "c:\cfusionmx7\runtime\lib\jrun.jar;C:\CFusionMX7\wwwroot\WEB-INF\lib \cfmx_bootstrap.jar;C:\CFusionMX7\wwwroot\WEB-INF\lib\cfx.jar" -Dcoldfusion.classPath=C: /CFusionMX7/lib/updates,C:/CFusionMX7/lib -Dcoldfusion.libPath=C:/CFusionMX7/lib coldfusion .tools.CommandLineInvoker Compiler -webinf C:/CFusionMX7/wwwroot/WEB-INF -webroot C: /InetPub/wwwroot -cfroot C:/CFusionMX7 -d -srcdir C:/Testing/deploy -deploydir C:/Testing /source v 

Table 6.5. ColdFusion Compiler Command Options

OPTION	DESCRIPTION	REQUIRED
cfroot	The fully qualified path to the ColdFusion root directory (such as C:\CFusionMX7 or /opt/coldfusionmx7).	Yes
d or deploy	Compile templates for sourceless deployment.	Yes for Sourceless Deployment
deploydir	The fully qualified path to the directory that will contain the compiled deployable files. This cannot be the same directory as the source directory.	Yes for Sourceless Deployment
f or force	Force compilation.	No
g or debug	Enable debug symbols.	No
help	Displays usage information and available options.	No
srcdir	The fully qualified path to the directory containing the templates to be compiled. This directory must be under the specified webroot directory. If omitted, ColdFusion will compile all ColdFusion templates in the specified webroot directory.	Yes
webinf	The fully qualified path to the ColdFusion WEB-INF directory.	Yes
webroot	The fully qualified path to the Web server root directory (such as C:\CFusionMX7\wwwroot or C:\Inetpub\wwwroot).	Yes
v or verbose	Display compiler performance statistics.	No

This command will compile all the ColdFusion templates (CFM, CFC, and CFR files) in the C:\Testing\deploy directory and save the Java bytecode versions in the C:\Testing\source directory. The original files in C:\Testing\deploy will retain the original CFML in a human-readable format.

NOTE

The ColdFusion Compiler is hard coded to accept only the default ColdFusion file extensions (.cfm, .cfc, and .cfr) for deployment. The capability to compile additional filename extensions is not fully exposed via the command-line interface. If you configure your ColdFusion server to process other extensions (such as *.cfx), you will have to specify the fully qualified path to the individual files instead of just the directory path. For example, to create a sourceless version of index.cfx, you will need to call

 cfcompile deploy C:\InetPub\wwwroot C:\InetPub\wwwroot\index.cfm C:\Testing\source 

If you try using a wildcard (as in C:\InetPub\wwwroot\*.cfx), only the first file is compiled. See the "Filename Extension" section in Chapter 10 for details on adding additional ColdFusion filename extensions.