Using Java libraries

You can extend the capabilities of Gallium Data by installing additional Java libraries.

As a Docker container, Gallium Data already includes the following libraries, which are therefore available in your JavaScript code out of the box:

Adding a library in a Docker image

You can add additional libraries by creating your own Docker image. This is the most efficient way to go, since it avoids having to download libraries on first startup, but it does take more work, so you may consider doing this only as an optimization, once you have figured out all the libraries you need.


Adding a library in a repository

You can also add a library as part of the repository, either using the GUI, or by editing the repository.json file and restarting Gallium Data.

This is slightly less efficient than putting that library in a Docker image because it requires the library to be downloaded during the first startup of Gallium Data, but it is much easier.

To use the GUI, open the Libraries page (left nav), select the Find tab, and enter a value for Organization (e.g. org.apache.commons). You can then click FIND LIBRARIES to see all the libraries available from that organization, or you can enter a value in the Artifact field (e.g. commons-email) if you know it.

Click Add to this repository to add a version of the library to the repository.

When you click Publish (which could take a moment as Gallium Data downloads the library and its dependencies), this library will be available to your filter code.

For example, let's assume that you want to add the Apache Commons Email library to your repository.

If you look it up on Maven Central, you'll see that its two-part full name is org.apache.commons and commons-email.

Once you have found it, added to the repository, and published, you can have a filter with the following code:

const SimpleEmail = Java.type("org.apache.commons.mail.SimpleEmail");
let email = new SimpleEmail();
email.setHostName("smtp.acme.com");
email.setSmtpPort(587);
const DefaultAuthenticator = Java.type("org.apache.commons.mail.DefaultAuthenticator");
email.setAuthenticator(new DefaultAuthenticator("jdoe", "secret"));
email.setSSLOnConnect(true);
email.setFrom("jdoe@acme.com");
email.setSubject("Test email");
email.setMsg("Hello world!");
email.addTo("pope@vatican.com");
email.send();


If something is not working as expected, it's a good idea to look at the logs for Gallium Data (using docker logs).

Note that some larger libraries, such as Apache POI, have a lot of dependencies and therefore take a moment to download, and to load every time you start an instance of Gallium Data for the first time . If you plan to use these very large libraries, you may want to consider creating your own Docker image to reduce startup time.

Underlying mechanism

The Java libraries you specify in your repository are analyzed and retrieved with the Apache Ivy library. By default, new libraries and their dependencies will be found and downloaded from Maven Central at https://repo1.maven.org/maven2, but you can change that and many other things by providing your own Ivy configuration file, which you can specify by specifying a command-line option for Gallium Data:

--ivy-settings=/home/jdoe/ivysettings.xml

This can be done with a -e parameter to Docker, e.g.:

docker run -e ivy-settings=/home/jdoe/ivysettings.xml ...

or by creating your own Docker image of Gallium Data and replacing the startup script with your own.

Keep in mind that the file you specify must be from the perspective of the Docker container.