Writing a Java CFX

To create a Java CFX, you simply create a class which implements the CustomTag interface. This interface contains one method, processRequest, which is passed Request and Response objects that are then used to do the work of the tag.

Note To create a Java CFX:
  1. Create a new source file in your editor.
  2. Enter the code, for example, the code below illustrates the creation of a very simple Java CFX named SimpleJavaCFX that writes a text string back to the calling page:
    import com.allaire.cfx.* ;
    
    public class HelloColdFusion implements CustomTag
    {
       public void processRequest( Request request, Response response )
            throws Exception
       {
            String strName = request.getAttribute( "NAME" ) ;
            response.write( "Hello, " + strName ) ;
       }
    }
    
  3. Save the file as HelloColdFusion.java in the classes subdirectory
  4. Compile the java source file into a class file using the java compiler. If you are using the command line tools bundled with the JDK, you do this using the following command line, which you execute from within the classes directory:
    javac -classpath cfx.jar HelloColdFusion.java
    
    Note The above command will only work if the java compiler (javac.exe) is in your path. If it is not in your path, specify the fully qualified path, for example:

    c:\jdk12\bin\javac on Windows NT, or /usr/java/bin/javac on Solaris

If you receive errors during compilation, check the source code to make sure you have entered it correctly. If no errors occur, you have just successfully written your first Java CFX!

As you can see, implementing the basic CustomTag interface is very straightforward. This is all a Java class has to do to be callable from a CFML page.

Processing Requests

Implementing a Java CFX requires interaction with the Request and Response objects passed to the processRequest method. In addition, CFXs that need to work with ColdFusion queries will also interface with the Query object. The com.allaire.cfx package, located in the classes/cfx.jar archive contains the Request, Response, and Query objects.

A basic overview of each of these object types is provided below. To see a complete example Java CFX that uses Request, Response, and Query objects, see the "ZipBrowser Example".

Request Object

Passed to the processRequest method of the CustomTag interface. Provides methods for retrieving attributes passed to the tag, including queries, and reading global tag settings.

Methods Used by Request Object
Method Description
attributeExists Checks if the attribute was passed to this tag
getAttribute Retrieves the value of the passed attribute
getIntAttribute Retrieves the value of the passed attribute as an integer
getAttributeList Retrieves a list of all attributes passed to the tag
getQuery Retrieves the query that was passed to this tag, if any
getSetting Retrieves the value of a global custom tag setting
debug Checks if the tag contains the DEBUG attribute

Response Object

Passed to the processRequest method of the CustomTag interface. Provides methods for writing output, generating queries, and setting variables within the calling page.

Methods Used by Response Object
Method Description
write
Outputs text into the calling page
setVariable
Sets a variable in the calling page
addQuery
Adds a query to the calling page
writeDebug
Outputs text into the debug stream

Query Object

Provides an interface for working with ColdFusion queries, including methods for retrieving name, row count, and column names as well as methods for getting and setting data elements..

Methods Used by Query Object
Method Description
getName
Retrieves the name of the query
getRowCount
Retrieves the number of rows in the query
getColumns
Retrieves the names of the query columns
getData
Retrieves a data element from the query
addRows
Adds a new row to the query
setData
Sets a data element within the query

For detailed reference information on each of these interfaces see the "Java CFX Reference".

Java CFX Class Loading

Each Java CFX class has its own associated ClassLoader which loads it and any dependent classes also located in the classes directory. When Java CFXs are reloaded after a change, a new ClassLoader is associated with the freshly loaded class. This special behavior is similar to the way Java servlets are handled by the Java Web Server and other servlet engines, and is required in order to implement automatic class reloading.

However, this behavior can cause subtle problems when attempting to perform casts on instances of classes loaded from a different ClassLoader. The cast will fail even though the objects are apparently of the same type. This is because the object was created from a different ClassLoader and is therefore technically not of the same type.

To solve this problem, only perform casts to class or interface types that are loaded via the standard Java class path, that is, classes not located in the classes directory. This works because classes loaded from outside of the classes directory are always loaded using the system ClassLoader and will therefore have a consistent runtime type.

Automatic Class Reloading

You can determine how the server treats changed Java CFX class files by using the RELOAD (?) . The allowable values for the RELOAD attribute are as follows:.

Allowable Values of RELOAD Attribute 
Value Description
Auto Automatically reload Java CFX and dependent classes within the classes directory whenever the CFX class file changes. Does not reload if a dependent class file changes without the CFX class file changing as well.
Always Always reload Java CFX and dependent classes within the classes directory. Ensures a reload even if a dependent class changes, but the CFX class file itself does not change.
Never Never reload Java CFX classes. Load them once per server lifetime.

The default value is RELOAD=Auto. This is appropriate for most applications. Use RELOAD="Always" during the development process when you want to ensure that you always have the latest class files, even when only a dependent class has changed. Use RELOAD="Never" to increase performance by skipping the check for changed classes.

Note The RELOAD attribute applies only to class files located in the classes directory. Classes located on the Java class path are loaded once per server lifetime and can only be reloaded by stopping and restarting ColdFusion Server.

Disabling Automatic Reloading for Deployment

Automatic class reloading is an essential feature for iterative development and testing. However, because it must continually check to see whether Java CFX class files have changed, performance may decrease slightly. Therefore, when you move from development into deployment, Allaire ecommends that you globally disable automatic class reloading. You can do this by modifying the coldfusion.cfx.class.reload setting of the config/jvm.init file as follows:

coldfusion.cfx.class.reload=no

For additional details on modifying JVM configuration file settings, see "Java Customization and Configuration".

Life cycle of Java CFXs

A new instance of the Java CFX object is created for each invocation of the Java CFX tag. This means that it is safe to store per-request instance data within the members of your CustomTag object. If you wish to store data and/or objects that are accessible to all instances of your CustomTag you should use static data members.

Calling the CFX from a ColdFusion Template

You call Java CFXs from within ColdFusion templates by using the name of the CFX. The following CFML template calls the HelloColdFusion custom tag:

<HTML>
<BODY>
<CFX_HelloColdFusion NAME="Les">
</BODY>
</HTML>
Note To test the CFX:
  1. Create a new source file in your editor and enter the code displayed above.
  2. Save the file in a directory configured to serve ColdFusion templates. For example, you might save the file as c:\inetpub\wwwroot\cfdocs\testjavacfx.cfm on Windows NT or /home/docroot/cfdocs/testjavacfx.cfm on UNIX.
  3. Request the template from your web browser using the appropriate URL, for example
    http://localhost/cfdocs/testjavacfx.cfm
    

ColdFusion processes the template and returns a page that displays the text "Hello, Robert." If an error is returned instead, check the source code to make sure you have entered it correctly.