Class loader configuration

In containerized environments, typically only one application runs on an Open Liberty server. However, some non-containerized configurations might run multiple applications on a single server. In such cases, Java libraries can be shared across multiple applications. All the applications can use the same classes at run time or each application can use a separate copy of those classes that is loaded from the same location. Common libraries, which are used by multiple applications on the server, are specified by the commonLibraryRef element. Private libraries, which copy the library classes from the server for use by a single application, are specified by the privateLibraryRef element. Private library class paths are appended to the application class loader class path, while a common library has its own class loader that the application delegates to.

In the following example, a library that is called Alexandria is on a server that is called Academy, in the wlp/usr/servers/Academy/mylib/Alexandria directory. An application that is called Scholar and an application that is called Student are running on the Academy server. Both applications need access to this common library. A third application on the same server, which is called Spy, needs its own private copy of the library classes. In the server.xml file, the library element specifies an ID and location that the three applications can reference to access the library classes:

The commonLibraryRef element specifies that the Scholar and Student applications can share a single copy of the library. The privateLibraryRef element specifies that the Spy application creates its own copy of the classes from the same physical files on disk.

The library, privateLibraryRef, and commonLibraryRef elements can also specify a filesetRef attribute, which designates a comma-separated list of fileset element IDs.

Global libraries are available to all Jakarta EE applications on a server, including applications in the dropins directory that are not explicitly configured in the server.xml file.

Global libraries are kept in a global library directory and can be referenced from the class loader configuration for each Jakarta EE application. However, other kinds of applications, such as OSGi applications, cannot use global libraries.

You can put global libraries in the following locations under the user directory that is specified by the WLP_USER_DIR environment variable:

If libraries are present in these locations when an application starts, and that application does not specify a classloader element, the application uses these libraries. If a class loader is specified in the application, these libraries are not used unless the global library is explicitly referenced.

If you use global libraries, you are also advised to configure a classloader element for every application on the server. The servlet specification requires applications to share the global library class loader in their class loader parent chain. Sharing a global library class loader breaks the separation of class loaders for each application. In such cases, applications are more likely to have long-lasting effects on classes that are loaded in Open Liberty and on each other. Class-space consistency issues are more likely to arise among applications, especially as features are added and removed from a running server. None of these considerations apply for applications that specify a classloader element in their configuration because they maintain the separation of class loaders.

In the following example, an application that is called Scholar is configured in the server.xml file to use the global library and a common library that is called Alexandria:

You can also configure the settings for the global library explicitly by specifying the library element with the special ID global, as shown in the following example:

By default, applications do not have access to the third-party APIs that are available in Open Liberty. To enable this access, you can configure class loading for an application in your server.xml file.

The apiTypeVisibility attribute of the classloader element specifies the types of API packages that a class loader supports. The default value for the apiTypeVisibility attribute includes the following API types:

If you want to enable access to non-default third-party APIs that are available for Open Liberty, you can specify the third-party API type for the apiTypeVisibility attribute. When you enable third-party API access, the APIs that are available to your application are still controlled by the Open Liberty features that are enabled in your server.xml file.

To learn which third-party APIs are available for an Open Liberty feature, see the feature page documentation for that feature. For example, the MicroProfile Telemetry feature page lists a collection of third-party OpenTelemetry APIs in the Third-party API packages provided by this feature section.

You can add or remove access to API types by specifying the API type with either a plus (+) or minus (-) prefix. The default API types are always enabled unless you explicitly remove them.

In the following code, an application that is called Scholar needs access to non-default third-party APIs that are available in Open Liberty. The application also needs to use a common library that is called Alexandria, which is located in the ${server.config.dir}/mylib/Alexandria directory. If an application uses any common libraries, you must configure those libraries to use the same API type visibility setting as the application. In the following example, third-party API type visibility is configured in the server.xml file for both the application and the common library:

In some cases, you can’t bundle a Java library with your application, for example, when the application is already packaged and does not include the library.

In the following example, an application that is called Scholar needs access to a Java library that is called Alexandria, which is located in the ${server.config.dir}/mylib/Alexandria directory: