Calling Java from Lucee

Because Lucee is a Java application, any Java library can be used within Lucee. This article describes using Java libraries from within Lucee code. Java libraries you'll use in Lucee are typically of the following types:

Instantiating a Java standard library class

The entire Java standard library that ships with the JVM is available to Lucee code without any additional configuration.

To utilize a Java standard library class, it first must brought into Lucee, which is kind of like a class import. In Lucee, this is done with the createObject() function.

The above merely readies the Java class but has not called any constructors. To call a constructor use the init() method:

This example above initialized the Java class matching a constructor whose arguments match what was passed into the init function. Now the class is fully instantiated and methods can be called on it like in the example below:

The above example does not have to be so verbose, it is possible to accomplish the same all in one line:

Instantiating third party Java libraries

In order to use third party java libraries, Lucee must be able to find them. Like any Java application, Lucee will load any java libraries on the classpath, but Lucee also supports dynamically loading libraries at runtime.

Defining Java libraries in the Application.cfc

The Application.cfc can have a setting to tell Lucee where to find additional java libraries

this.javaSettings = {LoadPaths = [".\java_lib\",".\java\myjar.jar"], loadCFMLClassPath = true, reloadOnChange= true, watchInterval = 100, watchExtensions = "jar,class,xml"}

Parameter Required? Default Value Description
LoadPaths yes An array of directories containing jar files or an array of paths to jar files. It will also accept a single directory or path to a Jar file
loadCFMLClassPath yes false Whether to load the underlying Lucee classes. This is only for advanced use cases and should be rare as functionality may change
reloadOnChange no false Instructs Lucee to reload the java libraries when they have changed without needing to restart the Lucee server
watchInterval no 60 How many seconds to wait between checking for changes to the java libraries. This only applies if reloadOnChange is true
watchExtensions no false Specifies which file extensions to watch for changes. By default only .class and .jar files are monitored

Support for this.javasettings was added in Lucee version 4

Note, there appears to be an issue with watchinterval and detecting changed classes https://luceeserver.atlassian.net/browse/LDEV-800 as a workaround, use the admin tag to restart the Lucee instance and pick up Java library changes:

<cfscript>
//Set the password to the password of your server administrator
admin action="restart" type="server" password="";
</cfscript>

Defining Java libraries during instantiation

For one off instantiations, its possible to define the jar files to load with the createObject function.

createObject('java',String className,String paths, String delimiter )

Parameter Required Default Description
Type yes Must be 'java' to tell Lucee it is instantiating a Java object
Classname yes The Java class being instantiated, must be the full package and class name
Path yes An array or list of jar files or directories containing jar files
Delimiter , The delimiter for the list of jar files, defaults to a comma

This example below shows loading the Handlebars.java library to use the Handlebars templating language inside Lucee.

Further Resources:

Custom Java Code

Any Java code that you write can be utilized just like a third party library above. Make sure that your .java classes are compiled to .class or .jar files and visible to be loaded using one of the methods listed for third party libraries. For just a new custom java classes, its possible to have Lucee compile java classes.

Other Tips

Generics

In Java, generic types are compiled down to the object type. Since Lucee is dynamic, it is not necessary to specify Java generic types when instantiating a generic class.

results matching ""

    No results matching ""