The Definitive Guide to the ColdFusion Classpath

Before you can load and use third-party Java classes from ColdFusion, you have to add them to the ColdFusion class path. Unfortunately, class paths are not much fun (learning to get your class path right is probably just as hard as learning to write Java in the first place), and on top of that, adding classes to ColdFusion’s class path is confusing because there are so many different ways of doing it. I finally decided to sit down and create the definitive guide to how it’s done to try to clarify the process.

First of all, there are different ways of doing it depending on how ColdFusion is deployed. The techniques below are broken down by deployment preference. Also note that there is a difference between adding class files to your class path, and adding jar files. I would recommend jarring up your class files to simplify the installation process, but you can deploy either jar files or class files. If you deploy the class files outside of a jar file, make sure you grab the entire directory structure representing your packages. In other words, if you have a class file called VeryCoolUtil.class in the package “com.macromedia.util”, make sure you deploy the entire directory structure (ie com/macromedia/util/VeryCoolUtil.class). If you decide to jar you class files up instead, you also need to make sure you jar up the entire directory structure representing your packages as opposed to just the class files.

ColdFuison Standalone

  1. The easiest way to add class or jar files to your class path is to simply drop them in the lib directory where they are automatically picked up. The directory is located at {cf_installation}/lib.
  2. You can also drop them in any of the Java extension directories. To find a list of the Java extension directories, open the ColdFusion administrator and click on “System Information”. Toward the bottom, you will see a system property called “Java Ext Dirs”. You can put jar and class files in any of those directories to have them picked up by the ColdFusion server.
  3. If you want more control over the order in which class files are loaded, you can add them to the ColdFusion server’s class path manually. In the ColdFusion administrator, click on “Java and JVM”, then add the absolute paths to your jar or class files in the “Class Path” field.
  4. Finally, you can manually add class and jar files to the server’s class path located in the jvm.config file. I’m not going to go into much detail about that since I recommend you use the admin interface rather than tweaking config files by hand.

J2EE Deployment

  1. The easiest way to add class or jar files to your class path is to simply drop them in the lib directory where they are automatically picked up. The directory is located at {cf_installation}/servers/lib. These class files will be available to all servers.
  2. You can also make your class files available only to the ColdFusion server by dropping them in “{cf_installation}/servers/default/cfmx/WEB-INF/lib”. (Note that putting them in {cf_installation}/servers/default/cfmx/WEB-INF/cfusion/lib will NOT work.)
  3. You can drop them in any of the Java extension directories. To find a list of the Java extension directories, open the ColdFusion administrator and click on “System Information”. Toward the bottom, you will see a system property called “Java Ext Dirs”. You can put jar and class files in any of those directories to have them picked up by the ColdFusion server.
  4. Another way to do it is to add classes through the JRun Management Console. Open up the console, and under the default server, click on settings, then add your classes to the class path list. (Note you can also click on “ColdFusion MX application” under the default server, then click on settings to make the same changes.)
  5. And finally, once again, you can edit the jvm.config file yourself, however again, I recommend you stick to using one of the methods above.

There are also ways to load your class files programatically in ColdFusion, or even to load them remotely, which you can find instructions on here. And finally, keep in mind that changes to you class path always require you to restart ColdFusion and/or JRun for them to be picked up.