# 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.

| 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/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.

## 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>

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