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.
![]() |
To create a Java CFX: |
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 ) ; } }
HelloColdFusion.java
in the classes
subdirectory
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/java
c 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.
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".
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 |
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 |
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".
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.
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.
|
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".
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.
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>
![]() |
To test the CFX:
|
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.