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.

5 Responses to The Definitive Guide to the ColdFusion Classpath

  1. Tony says:

    In my oppinion, all this this is relatively unneccessary. I’ve used the solution found here :http://www.spike.org.uk/blog/index.cfm?data=20040603&viewcomment=1It works a treat, and no problems when deploying the application. You can have the class anywhere you want!

  2. Andy Allan says:

    Christian, in regards modifying JVM settings within the JMC, does the bug still exist in that when you make a change and restart the service it fails because the -server flag is no longer the first one listed? Or has this been fixed in JRun Updater 3?Because of this bug, it has always been recommended that you modify any JVM settings directly in the jvm.config file rather than the JMC.Andy

  3. Paul Kenney says:

    Is there any reference on how to load class files programatically (without having to place them in the classpath)?

  4. Andy Allan says:

    Paul,the link is in Christian’s post above.Andy

  5. jim collins says:

    I’ve written a cfc called JavaClassLoader for loading java jar and class files at runtime without dealing with classpath and restarting issues. Its available on cfczone here: http://www.cfczone.org/cfcs/downloads/javaclassloader.zip