Loading the POI java libraries - cfsimplicity/spreadsheet-cfml GitHub Wiki

This library is essentially a wrapper for the spreadsheet functionality available in the Apache POI Java API and needs the POI and other supporting java libraries ("jars") to be "loaded" so that they can be invoked.

However if your CFML engine already uses older versions of any of these libraries, conflicts may arise.

Lucee

To ensure this doesn't happen Lucee (from version 2.14.0 of the library) loads the jars using OSGi from a specially provided "bundle" (lib-osgi.jar) which is included in the root.

The OSGi bundle is automatically installed to Lucee the first time it runs and will appear in your server administrator's "Info -Bundle (jar)" list as:

Spreadsheet CFML (spreadsheet-cfml)

The bundle can be uninstalled by calling the following method on the library:

spreadsheet = New spreadsheetLibrary.Spreadsheet();
spreadsheet.flushOsgiBundle();

Use of lib-osgi.jar in Lucee means that you do not need the lib or javaLoader folders that come with the library.

Adobe ColdFusion

If you are using Adobe ColdFusion the jars are loaded using JavaLoader to ensure the correct versions are used. (In this case lib-osgi.jar and osgiLoader.cfc are not required.)

Using an existing copy of JavaLoader

If you already have a copy available on your server, you can configure the library to use that instead of the bundled version. Simply specify the dot path of the JavaLoader.cfc component:

spreadsheet = New spreadsheetLibrary.spreadsheet( javaLoaderDotPath="myLibrary.javaloader.JavaLoader" );

or

spreadsheet = New spreadsheetLibrary.spreadsheet().setJavaLoaderDotPath( "myLibrary.javaloader.JavaLoader" );

Loading using javaSettings

Usually the default loading methods described above will work best. However if you want more control and are sure you won't run into "class clashes" you can bypass both Javaloader and OSGi and load the library jars directly from the /lib folder using javaSettings in your Application.cfc, for example:

this.javaSettings = {
  loadPaths = [ ".\spreadsheetCFML\lib\" ]
}

Then instantiate the library as follows:

spreadsheet = New spreadsheetCFML.Spreadsheet( loadJavaClassesUsing="javaSettings" );

or alternatively:

spreadsheet = New spreadsheetCFML.Spreadsheet().setLoadJavaClassesUsing( "javaSettings" );

Dynamic path loading

Lucee also supports specifying jar paths in CreateObject() without the need for javaSettings. To enable this use:

spreadsheet = New spreadsheetCFML.Spreadsheet( loadJavaClassesUsing="dynamicPath" );

or

spreadsheet = New spreadsheetCFML.Spreadsheet().setLoadJavaClassesUsing( "dynamicPath" );

Notes

  1. Dynamic path loading is only supported in Adobe ColdFusion version 2025 and above.
  2. This is the default loading method for Boxlang (experimental support only)