Building Custom CFXAPI Tags - amir@clickamir.com - www.clickamir.com


Writing a Java CFX tag

To create a Java CFX tag, 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.

The example in the following procedure creates a very simple Java CFX tag named cfx_MyHelloColdFusion that writes a text string back to the calling page.

To create a Java CFX tag:

  1. Create a new source file in your editor with the following code:
    import com.allaire.cfx.* ;

public class MyHelloColdFusion implements CustomTag
{
   public void processRequest( Request request, Response response )
    throws Exception
   {
    String strName = request.getAttribute( "NAME" ) ;
    response.write( "Hello, " + strName ) ;
   }
}
  2. Save the file as MyHelloColdFusion.java in the web_root/WEB_INF/classes directory.
  3. 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 cf_root\lib\cfx.jar MyHelloColdFusion.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:\jdk1.3.1_01\bin\javac on Windows 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 successfully wrote your first Java CFX tag. For information on using your new tag in a ColdFusion page, .

Calling the CFX tag from a ColdFusion page

You call Java CFX tags from within ColdFusion pages by using the name of the CFX tag 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).

To register a Java CFX tag in the ColdFusion Administrator:

  1. On the ColdFusion Administrator Server tab, select Extensions > CFX Tags to open the CFX Tags page.
  2. Click Register Java CFX.
  3. Enter the tag name (for example, cfx_MyHelloColdFusion).
  4. Enter the class name without the .class extension (for example, MyHelloColdFusion).
  5. (Optional) Enter a description.
  6. Click Submit.

You can now call the tag from a ColdFusion page.

To call a CFX tag from a ColdFusion page:

  1. Create a ColdFusion page (.cfm) in your editor with the following content to call the HelloColdFusion custom tag:
    <html>
<body>
  <cfx_MyHelloColdFusion NAME="Les">
</body>
</html>
  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 or /home/docroot/cfdocs/testjavacfx.cfm on UNIX.
  3. If you have not already done so, register the CFX tag in the ColdFusion Administrator.
  4. Request the page from your 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, Les." If an error is returned instead, check the source code to make sure you have entered it correctly.

To delete a CFX tag in the ColdFusion Administrator:

  1. On the ColdFusion Administrator Server tab, select Extensions > CFX Tags to open the CFX Tags page.
  2. For the tag you want to delete, click the Delete icon in the Controls column of the Registered CFX Tags list.

Processing requests

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

This section provides an overview of these object types. For a complete description of these object types, see CFML Reference.

For a complete example Java CFX tag that uses Request, Response, and Query objects, .

Request object

The Request object is passed to the processRequest method of the CustomTag interface. The following table lists the methods of the Request object 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.

For detailed reference information on each of these interfaces, see CFML Reference.

Response object

The Response object is passed to the processRequest method of the CustomTag interface. The following table lists the methods of the Response object for writing output, generating queries, and setting variables within the calling page:
Method
Description
 
write
Outputs text to the calling page.
 
setVariable
Sets a variable in the calling page.
 
addQuery
Adds a query to the calling page.
 
writeDebug
Outputs text to the debug stream.

For detailed reference information on each of these interfaces, see CFML Reference.

Query object

The Query object provides an interface for working with ColdFusion queries. The following table lists the methods of the Query object 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 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 web_root/WEB-INF/classes directory. When Java CFX classes 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 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 therefore is not technically the same type.

To solve this problem, only perform casts to class or interface types that are loaded using the standard Java classpath, 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 ColdFusion 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 class 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.

Note:   The reload attribute applies only to class files located in the classes directory. The ColdFusion server loads classes located on the Java classpath once per server lifetime. You must stop and restart ColdFusion Server to reload these classes.

Life cycle of Java CFX tags

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.

main page