Loading the POI java libraries

(Applies to v1.0.0+)

This library is essentially a wrapper for the spreadsheet functionality available in the Apache POI Java API and needs the POI java libraries ("jars") to be "loaded" so that they can be invoked. How this is done, however, will depend on the CFML engine and version you are using and whether or not you have customised it.

Lucee 4.5

Lucee 4.5 includes old versions of the POI jars in its "core" set of libraries. If the more up-to-date POI jars included with this library are loaded directly they will clash with these legacy versions preventing the library from working properly.

To avoid this, JavaLoader will be used by default to load POI and ensure the correct version is used.

Lucee 5+

If you are using the latest version of Lucee, POI will be loaded directly without the need for JavaLoader. POI jars no longer ship as part of the core, which is loaded separately via OSGi, meaning conflicts are avoided.

Be aware though that once loaded via this direct method the POI objects cannot be updated without restarting the engine. Normally this shouldn't be a problem since the POI jars are rarely updated. However, if you wish you can override the default behaviour and revert to using Javaloader by adding the following parameter to the init() method:

spreadsheet = New spreadsheetLibrary.spreadsheet( requiresJavaLoader=true );

Adobe ColdFusion (any version)

ACF also includes older versions of POI and is not OSGi based. JavaLoader will therefore be used by default to load the correct version.

Avoiding JavaLoader by customising the contents of your Java Class Path

If you are using Lucee 4.5 or ColdFusion and would prefer not to use JavaLoader (perhaps for security reasons) you have the option of doing this as long as you are happy to customise your engine's installation to avoid POI version clashes. You will need to:

1. Remove the existing POI jars from your engine's core java class path.
2. Ensure the jars in the /lib folder of the Spreadsheet Library are added to your engine's java class path.
3. Pass the following parameter to the Spreadsheet Library's init() method:

spreadsheet = New spreadsheetLibrary.spreadsheet( requiresJavaLoader=false );

Using an existing copy of JavaLoader

If JavaLoader is required for your environment and 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 as the javaLoaderDotPath init argument. For example:

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