Unknown macro: floating-toc

How to integrate external libraries into jBEAM start

Some special jBEAM components need external libraries to work. Most of these libraries are simple Java jar files, which need to be included in the Java classpath to be loaded at runtime. Some special libraries additionally need native libraries (on Windows called DLL files) to work. These native libraries must be included in the Java native libary path.

Use jBEAM as a jar file

To make these things as easy as possible in jBEAM, it isn´t necessary to define a difficult start script therefore. The only thing you have to do, is to put the library jar files into a folder called “lib” which must be located in the same folder as the jBEAM jar file. It is also possible to only create a link to the folder containing all the required libraries. This also works on Windows, even if links in Windows are simple shortcut files, named “lib.lnk”.

Your jBEAM installation folder should look like this to work:


If the lib folder exists, jBEAM will scan the whole folder on startup including all subfolders. So you can organize your external libraries in subfolders as you like. Even native libraries will be loaded if they fit to some naming conventions. These conventions are the following:
If you run jBEAM on a Windows system you need to create a folder named “windows_32” (for 32 bit native libraries) and “windows_64” (for 64 bit native libraries) and put all relevant DLLs in there next to their respective jar file. On Linux systems you will have to name the folder like “unix_32” and “unix_64”, on MacOS X systems “macos_32” and “macos_64”.

For example the DSJ library which is used to show video files inside jBEAM should look like this:


Beginning with the jBEAM version 6.9.X.X we will deliver All-In-One jar files (e.g. windows_32 folder inside the jar file) which contain native libraries in a standardized way. These jar files can be loaded by the default AMS "ExtendableClassLoader" without any issue.
In most cases you will get all required libraries from us in the correct form. So please always remember to keep the lib folder.

Use jBEAM in your application

If you use jBEAM as a library itself inside your own application you need to integrate native libraries by yourself. There are several ways to do that:

  1. Write your own ClassLoader and load the libraries including native libraries yourself
  2. Put all AMS provided external library jar files onto the Java classpath on startup (maybe using -cp switch in java.exe command)
  3. Use the AMS "ExtendableClassLoader" on Java startup using the command line switch -Djava.system.class.loader=com.AMS.jbeam_utils.classes.ExtendableClassLoader 
  4. Use the AMS "ExtendableClassLoader" in your code like shown below:
// load jBEAM class using the ExtendableClassLoader
Class<?> instanceclass = ExtendableClassLoader.getOrCreateExtendableClassLoader().loadClass("com.AMS.jBEAM.jBEAM");
// create new jBEAM instance !Please remember to access all methods only via reflection!
Object instance = instanceclass.newInstance();
// init jBEAM -> starts up into jBEAM desktop
instanceclass.getMethod("init", Object.class, Map.class).invoke(instance, null, new HashMap<String, Object>());

If you use Apache Tomcat please take a look here. Please be adviced to always use reflection if you choose the 4th way because your application code is loaded by the default Java Application classloader and all jBEAM classes need to be loaded by the AMS "ExtendableClassLoader". Not doing so will cause LinkageErrors and weird application errors.

Details about class loading in Java and jBEAM

Normally Java forces you to define all jar files which should be available in the application on startup (mainly using -cp switch to set the classpath). So it would not be possible to load any other third party library jar files while running the application. Additionally the pre-defined jar files are locked in Windows file system so that they cannot be modified (e.g. updated or deleted).

To solve this Java-owned issue we created the AMS "ExtendableClassLoader" which replaces the Java Classloading structure and gives us the possibility to:

  1. Add jar files while running the application
  2. Modify jar files at runtime (e.g. for web updates)
  3. Remove unused jar files at runtime
  4. Load system libraries (native dlls or so files) dynamically

The AMS "ExtendableClassLoader" needs to be injected into the default Java Classloader structure:

                    Ext ClassLoader (loads Java classes, "rt.jar")


                    App ClassLoader (loads the application jar files, per default the classpath elements defines via "-cp")


                    AMS ExtendableClassLoader (loads all other jar files dynamically)

So any jBEAM class needs to be loaded using the AMS "ExtendableClassLoader". If you use the jBEAM jar files (e.g. starting via double click or using the dedicated start script) you are fine because the jBEAM main class creates a new instance of the ExtendableClassLoader and starts jBEAM using Java reflection API. This way you don´t have to manually change the Java Classloader structure.

If you use jBEAM itself as a library you need to integrate the AMS "ExtendableClassLoader" yourself like described in the previous chapter.

How to get an overview over all used libraries in jBEAM

If you also want to know, which libraries can be included by jBEAM, just have a look at your jBEAM. All you have to do, is to open the Help menu entry and select the menu item “Resources/Library Usage”. There you find a list of all possible libraries, with some details about them.


In newer versions of jBEAM you can always download required jBEAM libraries if you click on help -> libraries/resources and if you are connected to the internet. jBEAM will try to download all libraries on click at the “download” button. This feature is included in jBEAM versions from 6.8 and newer.

The table below shows some details to the libraries:

Apache BatikJava library, which is able to render, generate, and manipulate SVG graphics.
Apache Common IOLibrary of utilities to assist with developing IO functionality.
Apache Common LoggingWrapper around a variety of logging API implementations.
Apache log4jJava-based Logging-Framework
Apache XML Graphics CommonsLibrary that consists of several reusable components used by Apache Batik and Apache FOP.
ASAM ModbusModbus-TCP (ADAM)
BeanShellBeanShell is a lightweight Java scripting language.
Beckhoff SPSSPS library
Delphin DataServiceAPI for device drivers
DSJVideo-Player Library
FreeHEPLIbrary for graphical functions
GroovyGroovy OOP-language, which can be used as a scripting language for the Java Platform.
HBM QuantumX APILibrary for access to HBM QuantumX Hardware
iTextLibrary, which allows to create and manipulate PDF documents.
Java HelpHelpService library
Java MailPlatform-independent and protocol-independent framework to build mail and messaging applications.
Java Media FrameworkLibrary that enables audio, video and other time-based media to be added to Java applications and applets.
Java Modbus LibraryObject oriented implementation of the Modbus protocol.
jBEAM HelpHelp library of jBEAM
JDOMOpen source Java-based document object model for XML.
JEuclidIs a complete MathML rendering solution.
JOGLIs a wrapper library that allows OpenGL to be used in Java.
JOPC-BridgeJava access to OPC servers
JScienceImplementation of Units of Measurement services.
NetCDFSet of software libraries and self-describing, machine-independent data formats that support the creation, access, and sharing of array-oriented scientific data.
NI DAQmx WrapperWrapper to enable a flexible data acquisition system using jBEAM
QuicktimeQuicktime library
RXTX Java Communication APISerial Port library
SerialIO CommSerial Port library
Sun SerialPortSerial Port library
TalkingJavaAudio output library
VectorXL WrapperUSB modul library

See also

How To » How To collection for jBEAM » How to integrate external libraries into jBEAM start

Copyright by Kistler Chemnitz GmbH 2021
XWiki Enterprise 4.4 - Documentation