Try Free

Resolving Library Conflicts with Class Whitelisting

Uncategorized
Lenny Primak
Published: 12 Jul 2017
Updated: 03 Aug 2025

Many applications, especially complex legacy ones that are packaged with a large number of libraries, may contain libraries that are also shipped with Payara Server (like Google Guava or Jackson for example). These types of conflicts can be very hard to track down and solve. Starting from the  171 release of Payara Server, there is now another solution in the toolbox which can help with resolving these dependency conflicts.

 

Applications can now include a whitelist, which will list the only classes that are allowed to be looked up from the Payara Server packaged applications, with certain exceptions.

 

This feature can be turned on with the <whitelist-package> directive in the following deployment descriptor files:

  • glassfish-web.xml
  • glassfish-application.xml

If this directive is included, the whitelist feature is considered turned on. When this happens, only Java packages that are explicitly mentioned in the whitelist are loaded from Payara Server packaged libraries; otherwise, Payara Server will look at the libraries included on the deployed application and throw a ClassNotFoundException if they are not present.

 

For example:

To use the version of Google Guava that is shipped with Payara Server, you can whitelist the com.google package, as shown:

     <whitelist-package>com.google</whitelist-package>

This has an effect of whitelisting all packages that start with com.google, for example:

  • com.google.guava
  • com.google
  • com.google.collections.concurrent
  • etc.

All other classes are only allowed to load from the Application itself.

Certain classes are whitelisted automatically, meaning they will always be loaded from Payara Server’s libraries, even if this feature is turned on.  This is because these packages are required by Payara Server and therefore cannot be loaded from a deployed application:

  • java
  • javax
  • com.sun
  • org.glassfish
  • org.apache.jasper
  • fish.payara
  • com.ibm.jbatch
  • org.hibernate.validator
  • org.jboss.weld
  • com.ctc.wstx
 

Share:

Download Payara Platform Community

Comments (5)

Post a comment

Your email address will not be published. Required fields are marked *

Payara needs the contact information you provide to us to contact you about our products and services. You may unsubscribe from these communications at any time. For information on how to unsubscribe, as well as our privacy practices and commitment to protecting your privacy, please review our Legal & Privacy Policy.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

  1. Ariel Alberto Grassano

    Hello, I have problems with the version of xmlsec.jar using wss4j, I have a new version in the “lib” folder of the domain, but still indicating “whitelist-package” still running the version that exists in modules. The error is “java.lang.NoSuchMethodError: org.apache.xml.security.utils.I18n.init (Ljava / util / ResourceBundle;) V”

    Reply
    1. Lenny Primak

      Hi,

      I think you are misunderstanding how Whitelist works.
      It’s not meant to de-conflicts domain’s lib directory JARs vs. Payara modules/ directory JARs.

      It is only meant to isolate JARs packaged within your application, i.e. WAR’s WEB-INF/lib and EAR’s lib/ directories.

      Domain’s lib/ directory is covered by the first part this blog: https://payara.gitbooks.io/payara-server/documentation/extended-documentation/classloading.html

      Also, keep in mind that not all modules are upgradeable, because of it’s transitive dependencies, so it may not be possible to do what you are trying without major surgery.

      If you have any follow up questions you can use the Payara google groups

      Reply
  2. Ariel Alberto Grassano

    My problem is because within webservices-osgi.jar is defined the class “org.apache.xml.security.utils.I18n” and the method “public static synchronized void init (ResourceBundle resourceBundle)” is not defined.

    Reply
  3. jm

    Thanks. One question , what is the default behavior for EJB module? I think that it is look up into /modules/lib at first and then /lib contained on EJB module , is this right ?

    Reply
  4. Lenny Primak

    By “EJB Module” do you mean EJB-jar inside EAR files correct?
    If you deploy “plain” ejb-jar it does not contain lib/ directory
    In any case, this behavior is controlled by Enhanced Class Loading features in EAR’s glassfish-application.xml file as well as fish.payara.classloading.delegate system property.
    See https://docs.payara.fish/documentation/extended-documentation/classloading.html for details

    Reply

Related Posts

Application Modernization 7 minutes
Thought Leadership
Valentina Kovacic
18 Dec 2025

8 Key Benefits of Application Modernization for Business Growth

Modernizing enterprise applications is a strategic imperative for organizations that want to remain competitive and resilient. According to our […]

Read More
Patrik Dudits presenting at Devoxx Belgium 2025 5 minutes
Cloud & Microservices
Patrik Duditš
14 Nov 2025

Devoxx BE 2025: It Only Starts with a Container & How Abstraction Becomes Reality 

At Devoxx Belgium 2025, I was able to talk about what happens after you build your container. In theory, […]

Read More
How to Kickstart Your Jakarta EE 11 Projects with Payara Starter 4 minutes
Cloud & Microservices
Gaurav Gupta
22 Aug 2025

How to Kickstart Your Jakarta EE 11 Projects with Payara Starter

With Jakarta EE 11 now officially released, you are likely eager to explore its new capabilities but setting up your first application […]

Read More