How to install POI on ColdFusion 8 using JavaLoader.cfc

Update (02/07/2009):

The new POI 3.5 beta also supports ooxml files (xlsx,docx,...). For updated instructions see: How to install the POI 3.5 beta on ColdFusion 8 using JavaLoader.cfc

Update (01/15/2010): Changed server scoped lock to named lock in Application.cfc example

I decided to write up a quick set of instructions for using POI with ColdFusion 8 as a reference. If you are not familiar with the JavaLoader.cfc it is a great tool, written by Mark Mandel, that allows you to dynamically load jar files.


Instructions:
1. Download the latest version of POI from http://poi.apache.org/. Extract the jars into the desired directory.

Example:
I created a directory under the webroot named "poi" and placed the jar files there. You can use a different location. So long as ColdFusion has permission to access whatever directory you select. Please note the jar file names tend to be based on version and date. So your file names may differ.

Jar Locations:
c:\coldfusion8\wwwroot\poi\poi-3.1-FINAL-20080629.jar
c:\coldfusion8\wwwroot\poi\poi-contrib-3.1-FINAL-20080629.jar
c:\coldfusion8\wwwroot\poi\poi-scratchpad-3.1-FINAL-20080629.jar

2. Download and install the JavaLoader.cfc, available at javaloader.riaforge.org

Example:
I installed the JavaLoader under the webroot

JavaLoader Location:
C:\coldfusion8\wwwroot\javaloader\JavaLoader.cfc
C:\coldfusion8\wwwroot\javaloader\JavaProxy.cfc
C:\coldfusion8\wwwroot\javaloader\lib\*.*

3. Instantiate the JavaLoader

Example:
Due to a java bug that causes a memory leak, I store my JavaLoader in the server scope. This is done inside my Application.cfc file. To read more about the java issue see: Using a Java URLClassLoader in CFMX Can Cause a Memory Leak.

Usage

// get a reference to the javaLoader
<cfset javaLoader = server[application.myJavaLoaderKey]>

Application.cfc

<cfcomponent>

<cfset this.name = "POIExamples">
<cfset this.sessionManagement = true>
<cfset this.loginStorage = "session">

<cffunction name="onApplicationStart">
<!--- use a unique hard coded key to store the javaLoader in the server structure ---->
<!--- the xxxx is actually a hardcoded UUID value ---->
<cfset var myJavaLoaderKey = "xxxxxx-xxxxxxxx-xxxxxxxxxx-xxxxxxxxxxx_javaloader">
<cfset var jarPaths = arrayNew(1)>

<!--- if the javaLoader was not created yet --->
<cfif NOT structKeyExists(server, myJavaLoaderKey)>

<!--- these are absolute paths to the POI jar files --->
<cfset arrayAppend( jarPaths, expandPath("./poi-3.1-FINAL-20080629.jar")) >
<cfset arrayAppend( jarPaths, expandPath("./poi-contrib-3.1-FINAL-20080629.jar")) >
<cfset arrayAppend( jarPaths, expandPath("./poi-scratchpad-3.1-FINAL-20080629.jar")) >

<!---  re-verify it was not created yet --->
<cfif NOT structKeyExists(server, myJavaLoaderKey)>
   <cflock name="#Hash(myJavaLoaderKey)#" type="exclusive" timeout="10">
       <!---  create an instance of the JavaLoader and store it in the server scope --->
       <cfset server[myJavaLoaderKey] = createObject("component", "javaloader.JavaLoader").init( jarPaths )>
   </cflock>
</cfif>
</cfif>

<!--- store the key in the appliation scope for easy access by other pages --->
<cfset application.myJavaLoaderKey = myJavaLoaderKey>
</cffunction>

</cfcomponent>