Developing ColdFusion Applications
Building Custom CFXAPI Tags

Writing a Java CFX

To create a Java CFX, you create a class that 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.

To create a Java CFX:

1. Create a new source file in your editor.
2. Enter your code. The following code shows how t o create 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, use the following command line, which you execute from within the classes directory:

   javac -classpath cfx.jar HelloColdFusion.java
   
   

   
   

   Note The previous command works only 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 UNIX.

   
   

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

As you can see, implementing the basic CustomTag interface is straightforward. This is all a Java class must 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 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.

This section provides an overview of these object types. For a complete example Java CFX that uses Request, Response, and Query objects, see the "ZipBrowser Example".

Request object

The Request object is passed to the processRequest method of the CustomTag interface. It provides methods for retrieving attributes, including queries, passed to the tag and for reading global tag settings.

Method	Description
attributeExists	Checks whether 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 whether the tag contains the debug attribute.

Response object

The Response object is passed to the processRequest method of the CustomTag interface. It provides methods for writing output, generating queries, and setting variables within the calling page.

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

The Query object provides an interface for working with ColdFusion queries. It includes methods for retrieving name, row count, and column names and methods for getting and setting data elements.

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 CFML Reference.

Loading Java CFX classes

Each Java CFX class has its own associated ClassLoader that 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 you are attempting to perform casts on instances of classes loaded from a different ClassLoader. The cast fails 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 the same type.

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

Automatic class reloading

You can determine how the server treats changed Java CFX class files by specifying the reload attribute when you use a CFX tag in your CFML page. The following table describes the allowable values for the 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 but the CFX class file does not change.
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 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 must ensure that you always have the latest class files, even when only a dependent class changed. Use reload="Never" to increase performance by omitting the check for changed classes.

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. To store data and/or objects that are accessible to all instances of your CustomTag, use static data members. If you do so, you must ensure that all accesses to the data are thread-safe.

Calling the CFX from a ColdFusion page

You call Java CFXs from within ColdFusion pages by using the name of the CFX that is registered on the ColdFusion Administrator CFX tags page. This name should be the prefix cfx_ followed by the class name (without the .class extension). The following CFML page calls the HelloColdFusion custom tag:

<html>

<body>

  <cfx_HelloColdFusion NAME="Les">

</body>

</html>

To test the CFX:

1. Create a new source file in your editor and enter the preceding CFML code.
2. Save the file in a directory configured to serve ColdFusion pages. For example, you can save the file as C:\inetpub\wwwroot\cfdocs\testjavacfx.cfm on Windows NT or /home/docroot/cfdocs/testjavacfx.cfm on UNIX.
3. If you have not already done so, register the CFS in the ColdFusion Administrator, as described in "Registering CFXs".
4. Request the page from your Web browser using the appropriate URL; for example:

   http://localhost/cfdocs/testjavacfx.cfm
   
   

ColdFusion processes the page 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.

Copyright © 2001, Macromedia Inc. All rights reserved.

---