There are times during the development of a ColdFusion application when CFML is not the best tool for the job. While this might seem to be a contradiction, it's true nonetheless. Allaire recognized this and while CFML has gotten to be a pretty pumped up scripting language, sometimes it's necessary to get a little help.

That help can come in a big way from Java in the form of regular classes, applets, servlets, EJB, and CFX tags. Building these components in Java gives you access to a powerful array of language extensions that are simply not available or are impractical to implement in CFML.

In this series of articles we'll look at how Java integrates with CFML and the ColdFusion Server (specifically 4.5.1 SP2).

To utilize the information contained in this series, you'll need to have a few software packages in-stalled:

• ColdFusion Server 4.5.1 Service Pack 2 (Professional or Enterprise editions)
• Java 2 SDK
  - Sun's Production release 1.2.2,
  or
  - Blackdown 1.2.2 RC 4 (or bet- ter) for the Linux platform
• A Java servlet engine
  - JRun 3.0 (any edition),
  or
  - Apache 1.3.x Tomcat
• An Enterprise JavaBean server
  - JRun 3.0 (Enterprise or Developer Editions),
  or
  - BEA WebLogic

Verifying Your ColdFusion Server Version
From within the ColdFusion Administrator navigate to the Version Info screen. The hyperlink for this screen is the last under the Server menu. The second entry under the Server Information section is Version and reflects the version of the server. It's important to be using at least version 4.5.1 SP2. While many of the samples in this series will work with 4.5, there are some quirks that can cause failure.

Obtaining a JDK
The documentation Administering ColdFusion Server, Chapter 3, "Configuring ColdFusion Server," specifies that the Java 2 virtual machine must be installed. A Java 2 platform can be obtained from either Sun's Java Web site (www.javasoft.com/j2ee/j2sdkee) or from Linux, the Blackdown site, where a listing of mirrored locations is given (www.blackdown.org/java-linux/mirrors.html).

Obtaining a Servlet Engine
Suitable Java servlet engines for this series are Allaire's JRun 3.0 and the Tomcat extension to the Apache Web server ( http://jakarta.apache.org/tomcat/index.html). The more obvious choice is the JRun product. While the Apache Tomcat extension is a fine product, JRun's integration is tighter, allowing use of the <CFSERVLET> tag, and the Developer and Enterprise editions have EJB capability.

Obtaining an EJB Server
Suitable EJB servers for this series are Allaire's JRun 3.0 and BEA System's WebLogic (www.beasys.com/). Again, while the alternatives to the Allaire product line are worthy of consideration in their own right, the better integration will come with JRun.

Series Environment
I'll be using both Windows and Linux for all the examples in this series. The Windows machine will be Windows 2000 Professional, Service Pack 1, with ColdFusion Server (Enterprise Edition) 4.5.1 SP2, IIS 5.0, Sun's J2EE JDK (1.2.2), and JRun 3.0 SP1. The Linux machine will be RedHat 6.2, with ColdFusion Server (Enterprise Edition) 4.5.1 SP2, Apache 1.3.12, Blackdown's Java 2 JDK (1.2.2 RC 4), and JRun 3.0 SP1. All deviations from this platform will be clearly noted.

My Windows installation has ColdFusion and JRun installed to their default locations: C:\CFUSION and C:\JRUN, respectively. The JDK is installed at C:\Program Files\Javasoft\JDK\1.2.2.

My Linux installation has ColdFusion and JRun installed to their default locations: /opt/coldfusion and /opt/jrun, respectively. The JDK is installed at /usr/local/jdk1.2.2.

Configuring the Administrator Java Settings Panel
Before we can do any integration with Java we need to configure the ColdFusion Server. So let's get down to business. Allaire provides us with what appears to be a fairly straightforward Settings panel for configuring Java. There are, however, some tricks to getting everything to run just right. We'll discuss some of them and how to avoid obstacles.

There are eight different settings in the Java Settings panel:

1. Load JVM when starting Cold-Fusion checkbox
2. JVM Path setting
3. Class Path setting
4. JVM Initial Heap Size setting
5. JVM Max Heap Size setting
6. System Options setting
7. Implementation Options setting
8. CFX JAR Path setting

As you can see in Figure 1, Allaire has made three default settings from which we can work. The Initial Heap Size of 1024K, the Max Heap Size of 16384K, and CFX JAR Path, which on my Windows machine is C:\CFUSION\Java\classes.

Load JVM When Starting ColdFusion
This setting indicates whether the ColdFusion Server should load the JVM when it starts. When it's un-checked, the ColdFusion server will load the JVM when the first Java object (class or EJB) or Java CFX is called. Clearly this is an issue of system performance and user perception.

If the JVM path is set incorrectly and the ColdFusion Server is flagged to load the JVM at start-up, the server will fail to start. An error message will get set in the server.log file; for example, on Windows,

"Error attempting to start the service,"

and on Linux (complete with sentence error),

"Unknown exception occurred while trying initialize the services."

This can create a tricky situation since the error doesn't inform us that the JVM failed to load. If you've adjusted a number of different settings, you don't know for certain which one is the culprit. It becomes even dicier once you decide to turn off the setting, since the ColdFusion Administrator can no longer be accessed! This setting can be adjusted through the registry at HKEY_ LOCAL_MACHINE\ SOFTWARE\Allaire\ColdFusion\ Current Version\ JVM through a string setting, JVMLoad. A value of 1 means to load on start, and a value of 0 means not to load on start (Knowledge Base Article 15018, www.allaire.com/Handlers/index.cfm?ID=15018&Method=Full). This can be done through the registry editor (Regedit. exe) on Windows or using a favored text editor on the cf.registry file in the registry subdirectory of the ColdFusion installation on UNIX. This problem is more commonly found on Windows machines, where setting the JVM Path setting is not as straightforward as it is on the UNIX platforms.

JVM Path
This setting can be tricky on Windows machines. For whatever reason, Allaire chose not to be very flexible about their path requirements. The use of forward slashes is re-quired, even on Windows (Knowledge Base Article 13863, www. allaire. com/Handlers/index.cfm?ID= 13863&Method =Full). While this isn't a problem on the UNIX platforms, failure to do so on Windows will cause the server to fail to start or hang when a Java call is made; for example, on my Windows machine,

C:/Program Files/Javasoft/JDK/1.2.2/jre/ bin/classic/ jvm.dll

or on my Linux machine,

/usr/local/jdk1.2.2/jre/lib/i386/classic/libjvm.so

There's an additional setting that must be made on the UNIX platforms. An alteration to the LD_ LIBRARY_PATH variable in the start script must be made to include locations to various subdirectories of the JDK installation (Knowledge Base Article 15452, www.allaire.com/Handlers/index.cfm?ID=15452&Method=Full). This will make certain that the needed shared objects get loaded with the server. The ColdFusion Server will have to be restarted for this to take effect.

JAVAPATH=/usr/local/jdk1.2.2

LD_LIBRARY_PATH=$CFHOME/lib:$JAVAPATH/jre/lib/i386/classic:$JAVAPATH/jre/
lib:$JAVAPATH/jre/lib/i386/native_threads:$JAVAPATH/jre/lib/i386

Class Path
This setting defines the Java CLASSPATH used for locating CFX class files, regular class files, and EJB components. I like to set it to the CFX subdirectory of the ColdFusion Server installation. Whether it's a CFX written in Java, C++, or Delphi is immaterial to me; my logic follows that any CFX belongs in the CFX subdirectory. In addition, the path to any auxiliary classes needed should be included as well. For example, on my Windows machine it's at

C:\CFusion\CFX;C:\Test

On my Linux machine,

/opt/coldfusion/cfx:/usr/local/test

A number of bugs are documented as being corrected in Release Notes for ColdFusion Server SP1 (Knowledge Base Article 17751, www.allaire.com/Handlers/index.cfm?ID=17751&Method=Full) and SP2 (Knowledge Base Article 18364, www.allaire.com/Handlers/index.cfm?ID=18364&Method=Full). However, verifying this at the time this article was written is difficult, as two other Knowledge Base Articles (17329 and 17334) referenced in the SP1 Release Notes are inaccessible. It's hard to tell if this is a technical glitch at the site, if the articles have been removed, or if those articles were never meant for public consumption.

Reading into the Release Notes, one article seems to indicate that on UNIX the Class Path setting is lost when the server is restarted. The other seems to indicate two different problems, one on UNIX and the other on an unspecified platform, presumably both Windows and UNIX. The former refers to changing the path separator from a semicolon to a colon, and the latter to a 500-character limit in the Class Path field in the Administrator. The first two of these three bugs appear to be fixed in SP1. The 500-character limit in the Class Path is a bug for which there's an easy test. Upon closer inspection of the source of the Java Settings panel, the Class Path input field on the Windows platform is indeed set to a maximum length of 500. However, on Linux and Solaris for SP1, the maximum length is set to 250. This is corrected in SP2.

JVM Heap Size
This is a great setting for controlling the memory allocation on your server. The Initial and Maximum Heap Memory Size values allow you to adjust for your specific utilization needs. By default, the server uses 1024KB for the Initial Heap Size and 16384KB for the Maximum Heap Size. In many cases this is enough; however, Allaire recommends on Linux (Knowledge Base Article 15452, www.allaire.com/Handlers/index.cfm?ID=15452&Method=Full) 4096KB for the Initial Heap Size and 65536KB for the Maximum Heap Size. This is a good recommendation on all platforms for the kinds of things we'll be examining later in this series.

System and Implementation Options
These options show as separate entries on the Java Settings panel but I'll address them together, as they reflect the same kinds of information. Through these two settings it's possible to make configurations to the JVM. System Options are a nice keyhole into the JVM environment, allowing for global settings to be made that will affect the way the JVM runs, such as what Just-in-Time compiler to use or an alternate security manager. Entries for these settings are done in key/value pair assignment format (i.e., property=value) and separated by semicolons. For example, Java.security. manager=java.rmi.RMISecurity Manager.

Implementation Options are an-other keyhole into the JVM. Acting like command line switches, they set options for the way the JVM executes. Implementation Options are specific to a JVM implementation (for example, Microsoft's JVM might have special options for interfacing with COM services). Entries look like command line options, leading with a dash and a letter switch. You can usually get a listing of supported switches by executing your Java command with the help switch (java -h). For example, -Djava.compiler=NONE.

A problem on UNIX platforms causes these settings to clear whenever there's more than one option specified. Allaire's workaround to this is to restrict your usage of both settings to just one value each (Knowledge Base Article 15955, www.allaire.com/Handlers/index.cfm?ID=15955&Method=Full). Further complicating this is Allaire's recommendation for Linux (Knowledge Base Article 15452, www.allaire.com/Handlers/index.cfm?ID=15452&Method=Full) for the System Option setting, java. compiler =NONE.

CFX JAR Path
Here the location of the Java archive containing Allaire's Java CFX library is identified. The ColdFusion Administrator provides one by de-fault. For example, on my Windows machine it's:

C:\CFUSION\Java\classes

On my Linux machine,

/opt/coldfusion/Java/classes

Restarting the Server
Perhaps it's obvious, but I would be remiss if I left out this tidbit of information. It's necessary to restart the ColdFusion Server whenever you make a change in the settings panel if the JVM has been loaded. This can mean any time you make a change if the JVM is set to load at server start-up. At best, failing to do this can cause some confusion when templates don't act as you intend. In the case of adding to the Class Path, the ColdFusion Server will report back that it's unable to locate the referenced class or cause other classes to raise exceptions and fail. This can make for a very messy looking application.

It's possible to catch these errors programmatically with the structured exception handling in CFML (<CFTRY> and <CFCATCH>). It's a good recommendation to use try/ catch blocks liberally when working with any object. It gives you, the developer, a great deal of flexibility to enable your application to de-grade gracefully under dire situations.

Wrapping It Up
As you can see, with the exception of a few twists and turns, there really isn't much to Java enabling your ColdFusion Server installation. All that remains is to actually test the configuration. You can do this by creating a regular Java class and calling it with <CFOBJECT>. A class with a simple "hello world" functionality would do. The code for this simple test can be found in Listings 1 and 2. Compile the Java source from Listing 1, place the resulting bytecode file somewhere in your class path, and execute the template from Listing 2. I'll cover using Java classes with <CFOBJECT> in later articles, so I won't explain the listings here. To paraphrase Fermat, the explanation is too large to fit in the sidebar.