Resolving Library Conflicts with Class Whitelisting

Photo of Lenny Primak by Lenny Primak

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 package, as shown:


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

  • 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
  • org.hibernate.validator
  • org.jboss.weld
  • com.ctc.wstx