Class loaders in Payara Server follow a delegation hierarchy by default. This page documents how classes are usually loaded and from which locations.
With the default classloader configuration, Payara Server will attempt to search for classes in the following locations in this order:
Classes provided by the JDK
Extension libraries in a Payara Server domain (installed as a library of the
Classes provided by Payara Server
Common libraries in a Payara Server domain (installed as a library of the
Application-specific libraries in Payara Server (installed as a library of the
Classes and libraries provided by the deployed application archive (e.g.
Classloaders that are lower in the hierarchy will first delegate searching for a class to a classloader higher in the hierarchy.
|If none of the classloaders higher in the hierarchy finds the class, the classloader will attempt to find the class itself.
Here, you can see that:
Classes provided by Payara Server have higher priority than classes provided by an application
Classes provided by Payara Server have higher priority than installed libraries of type
Classes in installed libraries have higher priority than classes provided by an application
To install a library with a higher priority than classes provided by Payara Server, it should be installed with type
The delegation hierarchy can be tweaked using the Enhanced Classloading features. For example, it’s possible to give the classes provided by an application the highest priority (by disabling classloading delegation), or completely hide (isolate) classes provided by Payara Server from a deployed application.
If a deployed application requires additional classes not provided by the application, you can install a library with those classes into the Payara Server domain. This is useful if you’d like to build an application for flexible deployments and configure it with classes dropped on the classpath, or if you’d like multiple deployed applications to share the same library.
If an internal Payara Server resource, such as a JDBC connection pool, requires an additional library, you can install it into the Payara Server domain too.
To install a library into a Payara Server domain, use the asadmin add-library command. This command accepts the
--type argument, which accepts the following options:
The library is installed as a common library into the
libdirectory in the Payara Server domain
The library is installed as an extension library into the
lib/extdirectory in the Payara Server domain
the library is installed as an application library into the
lib/applibsdirectory in the Payara Server domain
Common libraries are available to all applications or modules deployed on servers with the same configuration. There are several levels of common libraries:
Shared by all applications deployed on the same Payara Server installation - located in the
glassfish/libdirectory in the Payara Server installation
Shared by all applications deployed in the same Payara Server domain - located in the
libdirectory in that Payara Server domain directory
Shared by all applications deployed on instances that share the same configuration - located in the
config/<config-name>/libdirectory in the particular Payara Server domain directory
Only libraries shared by applications in the same domain can be installed by the
add-library asadmin command. All other types have to be installed manually by copying the libraries into the particular locations.
Application developers can use libraries installed as extension libraries to extend the functionality of the core Payara Server platform. For example, an Oracle Database JDBC driver should be installed as an extension library if it’s going to be used via JPA to use Oracle-specific JPA features. Or a Java agent library should be installed as an extension library if the Java agent instruments classes in Payara Server to use classes from the agent library itself.
Classes in extension libraries will be available to all deployed applications. If you need that classes from an extension library are available also to Payara Server’s internal classes (and OSGi bundles in general) as is often the case with Java agents, you also need to add the packages exported by the library into OSGi boot delegation. This is done by modifying the
glassfish/config/osgi.properties configuration file in the Payara Server installation and adding the packages to the list in the
org.osgi.framework.bootdelegation property. Packages exported by Oracle JDBC drivers are already added by default.
When Payara Server runs on JDK 8, extension libraries are added to the JVM using the standard Java extension mechanism, by adding the
lib/ext directory in the current domain as an extension directory using the
java.ext.dirs JVM option.
When Payara Server runs on JDK 11 and newer releases, extension libraries are added to the system classpath at the beginning of the classpath, so that they have higher priority than all other classes and libraries on the classpath. This is because the Java extension mechanism isn’t supported in Java 11 and newer and the official recommend way to replace it is to add the libraries to the classpath directly.
This behavior is triggered automatically if the
java.ext.dirs property isn’t defined as a JVM option, regardless of the JDK version used. Since defining the
java.ext.dirs on Java 11+ leads to an error, this JVM option cannot be used with Java 11+ and extension libraries are automatically added as classpath elements.
It’s also possible to trigger this behavior when using Java 8 by removing the
java.ext.dirs JVM option from the Payara Server default configuration settings.