Using Third-Party JARs and Native Libraries

This topic describes issues that can arise when using different combinations of third-party JARs and native libraries, and indicates where to locate them.

Custom adapters and Java operators are built against the StreamBase Client API libraries, as documented elsewhere in this guide. When you use third-party JAR files, especially ones that call native libraries, additional considerations may apply when those libraries load. The potential issues and their workarounds are described below. To keep things simple, we assume that you create the base code using one of the StreamBase wizards for creating adapters or Java operators.

There are four scenarios to consider. The first two are not problematic:

Scenario 1: No third-party dependencies

In the simplest case, your adapter or operator uses no third-party JARs and no native libraries:

The adapter or operator source is generated into the src/main/java folder of your Studio project by default.

Scenario 2: Adapters or operators and third-party JARs

If your adapter or operator uses third-party JARs but no native libraries:

  • Adapter and operator resources can be in the same locations as in Scenario 1. In addition:

  • Put your third-party JARs on the project build path.

The third and fourth scenarios may require workarounds to handle properly.

Scenario 3: Adapters or operators and native libraries

Your adapter or operator uses native libraries but no third-party JARs.

Scenario 4: Adapters or operators and third-party JARs and native libraries

Your adapter or operator uses both native libraries and third-party JARs.

Java JVM architectural constraints can require that native libraries be loaded only once per JVM on certain platforms. As you edit and configure operators and adapters, StreamBase Studio typechecks them by instantiating classes as needed. Therefore, you must take care to ensure it makes no attempts to load native libraries more than once.

Caution

To the greatest extent possible, place any code that loads native libraries into the #init method of your operator, and avoid any static or non-static initializers that would trigger the native library to load during typecheck in StreamBase Studio.

However, you may not have access to the source code of some third-party libraries, and thus cannot control how and when they load. Symptoms of such issues include error messages such as: 

Native Library xyz already loaded in another classloader
NoClassDefFoundError
UnsatisfiedLinkError

Should you be unable to constrain the native library load or must have it available for typechecking, then do the following to ensure that Studio will load the library only once:

  • Put third party jar files in STREAMBASE_HOME/lib/bootext/, which StreamBase Studio searches to satisfy such dependencies.

  • Put native libraries somewhere in your %PATH% (Windows), LD_LIBRARY_PATH (Unix), or DYLD_LIBRARY_PATH (Mac).

  • Restart StreamBase Studio for your changes to take effect.