2009 UPDATE: ColdFusion MX 9 has been released since this article was originally published, and it now has Hibernate baked right in.

Why do I want to use JBoss instead of sticking with Macromedia’s own JRun J2EE Application Server? Well, it’s a little bit of a long story. Most of the application development I’ve done in the past year has been with CFMX, but I often find myself extending the functionality of CFMX with existing Java APIs, for example using JAI to create photo thumbnails or edtftp for FTP operations that require wildcards. A database architect I know through work recently suggested I look into Hibernate, an open source object/relational persistence and query service for Java.

Not only is it free, but several Eclipse plug-ins exist which can help automate the process of creating data objects and the Hibernate XML mappings which link those objects to tables in your database. As a test I put together a simple Java application using Hibernate for persistence and was impressed with how easy it was to implement and use. I then found a Yahoo user’s group dedicated to getting Hibernate to work in CFMX.

I downloaded the sample application and was able to get it running on my PowerMac at home, but when I tried to get it to run with IIS on my Windows server I ran into logging errors with the log4j archive. According to one member in the cfhibernate group, there is a bug with JRun/CF for Windows that prevents any Java application using the log4j logging classes from running within CFMX. Unfortunately, Hibernate uses these classes extensively. My only option at this point was to use the CFMX built-in Web server or deploy CFMX on another application server. I deployed CFMX on Tomcat and it seemed to work pretty well, although I didn’t do any extensive testing. I finally decided to try JBoss with Tomcat as the Web server and servlet container, however, so that I can also use JMS for asynchronous method calls. (If you own or can afford the Enterprise version of CFMX, you can use the CFML event gateway for asynchronous CFCs. I’ve tested it with the developer edition and it seems to work pretty well.)

The first step is to download and install the latest version of JBoss. Make sure you have a Java JRE on your machine first, though, or the installation will not work. JBoss used to require the full JDK install, but as of version 4.0.2 all it needs is the JRE. I used Java 1.5 and installed it into the “C:\Java\jre1.5.0_04” directory instead of the default “C:\Program Files\Java\jre1.5.0_04” to avoid problems that the space in the path name can cause. Next, unzip the JBoss zip file to the folder where you want JBoss to live, in my case “C:\jboss-4.0.2”. If you have the full JDK installed, set the JAVA_HOME environment variable to point to that directory. Now all you have to do to start JBoss is launch the “run.bat” file in the “C:\jboss-4.0.2\bin” directory. You’ll see several lines scroll by in the console window until it says something like “Started in 15s:837ms”. You can test to see if it’s running by going to the welcome page at http://localhost:8080. To shutdown the JBoss server, type Ctrl-C at the console command prompt. Since I prefer to have JBoss automatically load when the server is rebooted, I set it up as a Windows Service. Once JBoss is running, use the Coldfusion installer to create a EAR or WAR file for deployment. 

At this point you could simply drop the EAR file you created into the “C:\jboss-4.0.2\server\default\deploy” folder and JBoss would automatically deploy it, but this would also cause it to redeploy every time you restarted JBoss and you would lose your CF admin settings. Instead you can “explode” the EAR using the Java jar command or a ZIP utility like Winzip (Java archive files use the standard ZIP file format). If you’re using Winzip, you’ll need to rename the extension to “.zip”. Create a folder in the “C:\jboss-4.0.2\server\default\deploy” directory called “cfusion.ear” where the “.ear” is part of the folder name, then create a subfolder called “cfusion-war”. Extract the “cfusion.zip” file you created to the “cfusion.ear” directory, then rename the resulting “cfusion.war” file “cfusion.zip”. Now extract cfusion.zip” to the “cfusion-war” directory and delete both “.zip” files. The final step is to edit the “application.xml” file in the “cfusion.ear\META-INF” folder. Change the content of the “web-uri” node to “cfusion-war”. The context root should already be set to the value you selected during the CFMX install process. You can now restart JBoss and CFMX will be automatically deployed. CFMX will not be redeployed again on restart as long as the “cfusion.ear” folder remains in the “deploy” folder.

The first time you visit the CF Administrator to complete the CF configuration, you may want to use IE as I’ve noticed it will sometimes hang in Firefox. Once the initial configuration is complete and you’re in the administrator, Firefox seems to work fine.