Updated June 26th, 2019: The approach described below is out of date, since the Eclipse plugin has been discontinued in the meantime. In the Web UI, adding a Java library is exceedingly easy: Simply upload it directly on your integration flow’s Resources tab, and you’re done. Also, Cloud Integration now supports Java 1.8. I’m leaving the blog post in place as a historical record 🙂

Groovy scripts in your CPI integration flows have the combined class libraries of Groovy and Java available to them. Sometimes, though, you also need to access classes from external Java libraries. Luckily, you can do that. However, this useful feature is only mentioned in passing in the Developer’s Guide, and particularly if you are new to Eclipse, it is not obvious how it works. In this blog post I will walk you through the required steps.

Before we get started, let me point out that adding external libraries is currently only possible in the Eclipse add-on. I expect the feature to be added to the Web UI sooner or later, though.

Step 1: Create the src.main.resources.lib package

The JAR files containing your external Java libraries must be imported into the src.main.resources.lib package of your integration project. Since this package is not created automatically in a new project, we need to add it manually. To do so, right-click your project, click New and choose Package. In the New Java Package window, enter src.main.resources.lib in the Name field and click Finish.

A freshly created integration project with the package added looks like this:

Step 2: Import your JAR file

Having created the package, the next step is to import the JAR file containing the external Java library. Right-click the src.main.resources.lib package and choose Import… from the context menu. In the Import window, choose File System in the General category and click Next. Now click Browse and navigate to the directory containing your JAR file and click OK. From the list of files in the chosen directory, check the JAR file to be imported and click Finish:

The library has now been imported into the proper package. If you need more than one library, you can go ahead and import multiple JAR files.

One restriction to keep in mind: The Java Virtual Machine executing your Groovy code runs Java version 1.7, so for now you cannot use Java 1.8 libraries. As always with cloud software, this can and probably will change in the future.

Step 3: Utilise the external classes in your code

The classes of the external library are now available in your Groovy code. At this point, you would usually import them at the top of the script, and then reference them by class name in the code. And that is all there is to it 🙂

Bonus: How to determine the Java version

How did I determine that CPI’s underlying JVM is version 1.7? The getProperty method of class java.lang.System lets you look at various system properties, including the Java version. At the time of writing, System.getProperty("java.version") returned 1.7.0_121. For a full list of supported properties, check out the method’s documentation.