CDI Scanning in Payara Server

The capability to disable implicit CDI scanning was already added to the previous Payara Server releases but the default admin console setting was to enable it at deploy time. We have now made a change so that the value added to the deployment descriptor is the overriding setting and the admin console setting will be ignored.

For even more control, we have added the ability to explicitly include or exclude JARs within an Application Deployment from CDI scanning. You can now, for example, include all JARs by default and exclude some named ones, or do the opposite and exclude all by default and only include some named ones.

CDI Scanning in Java EE 7

One of the improvements that came with CDI 1.1 in Java EE 7 was related to CDI scanning. Previously, a beans.xml file was necessary for CDI scanning to happen and, therefore, for any CDI beans to be processed, but CDI 1.1 removed that stipulation and mandated that CDI scanning would happen by default. CDI is an increasingly popular and forward-looking API, used in a large proportion of new Java EE projects, so this was a logical change to make.

 
The way this now works in Java EE 7 is that CDI scanning, by default, looks at all classes for so-called "bean-defining annotations" and processes those that it finds. With this implicit scanning comes more control over the way scanning happens with a new attribute for the beans.xml called bean-discovery-mode. This can be set to all, annotated or none. If there is no beans.xml the mode is assumed to be annotated, meaning that only class-level annotations are processed.

So the beans.xml file has not been deprecated in Java EE 7, it is now an optional file that can be used to control CDI scanning of an archive in a more fine-grained way. Turning off scanning completely (by setting the bean-discovery-mode to none) can be really useful if you use other dependency injection frameworks, like the popular Google Guice. Sometimes, however, this method of disabling implicit CDI scanning isn't possible; manually adding a beans.xml to a signed third-party JAR is not an option.

Disabling Implicit CDI

The way to completely stop CDI scanning, inherited from GlassFish, is to explicitly disable it at deploy time. In the admin console, this takes the form of a checkbox labelled Implicit CDI, as shown. To be spec compliant, this must be enabled by default so you would need to untick this box each time you deploy your application.

Under the covers, this admin console screen calls the asadmin deploy command with the option --property implicitCdiEnabled=false. Again, this property would have to be supplied with each deployment to disable implicit CDI and we can't alter this behaviour while staying spec-compliant. In a scripted deployment, this is less of a problem, but this is an extra dependency for the application which is outside of its control.

To address this, we added a new feature for the 162 release of Payara Server to enable or disable CDI scanning within the deployment descriptor for EAR files (glassfish-application.xml) as follows:

<glassfish-application>
  <enable-implicit-cdi>false</enable-implicit-cdi>
</glassfish-application>

Unfortunately, though this was intended to increase the portability of applications, it was still limited by the admin console's checkbox; the value from the deployment descriptor would be respected when deploying via asadmin, but would be overridden by the value of the checkbox in the admin console. Since it can be reasonably assumed that disabling CDI for the EAR is not a setting that you would want to change at deploy-time, we made a change in the 164 release so that the admin console value is ignored if the deployment descriptor explicitly disables CDI.

Explicitly Scanning 3rd party JARs

While these features now give greater control over CDI scanning for entire deployments (both EAR and WAR), modern WAR and EAR files very often include a number of 3rd party JARs. In situations where some JARs require CDI scanning and others may cause problems if scanned, these can now be explicitly included or excluded from scanning.

Both the glassfish-application.xml and the glassfish-web.xml files now support the elements scanning-exclude and scanning-include, as shown below:

<scanning-exclude>*</scanning-exclude>
<scanning-include>ejba*</scanning-include>
<scanning-include>conflicting-web-library</scanning-include>

In the above example, a wildcard (*) is used to specify that the default behaviour is to exclude all JARs. Then, all JARs beginning with ejba are specifically included in scanning, as well as the JAR named conflicting-web-library.

Availability

All of these enhancements are available from the 164 release and that applies to both Payara Server and Payara Micro. That's one less thing to depend on outside of your application!