WebSphere Traditional scans application library jars. WebSphere Liberty does not scan application library jars.

[tbitonti]

Problem Statement

There is an inconsistency in the scanning of enterprise application library jars between WebSphere Traditional and WebSphere Liberty:

• In WebSphere Traditional, annotations and classes located in JAR files in the enterprise application library folder are scanned. In particular, servlet container initializers are located.
• In WebSphere Liberty, the EAR library folder is not scanned. Initializers in EAR library JAR files are not located.

(Detection of other annotations, in particular, component defining annotations, is also impacted.)

Changing the Liberty scan behavior is possible, however, this is a change of behavior to existing Liberty application installations. That leads to two questions:

1. Should the Liberty scan behavior be changed?
   1. Con: Impactful changes are to be avoided for existing Liberty application installations.
   2. Pro: The lack of consistency makes for an adverse migration experience when migrating from WebSphere Traditional to WebSphere London.
2. If the scan behavior is changed, should it be conditional?
   1. Should a new configuration element be provided?
   2. Should the behavior be custom property enabled (or disabled)?
   3. If either a new configuration element or a custom property is provided, should the default be the current Liberty behavior (do not scan application archives), or the new compatible behavior (do scan application archives).
   4. If a new configuration element is provided, where should the element be specified? The top candidate locations are either (or both) of the application manager element or the application element.

For example:

As-Is:

<applicationManager autoExpand="true"/>

To-Be:

<applicationManager autoExpand="true" enableLibraryScans="true"/>

As-Is:

<application location="helloworld.ear"/>

To-Be:

<application location="helloworld.ear" enableLibraryScans="true"/>

---

Proposed Resolution

The proposal is to add code which performs scans of application library archives, to add configuration options to the application manager and application which are used to enable the new scanning code, and to have the new scans be disabled by default.

• A capability to perform scans on application library JARS should be added.

  • A small amount of new code is needed to enable the new scans.
  • The capability is correct according to the specification.
  • The capability is important for migration and modernization scenarios.

• The capability should be enabled via a new element of the application manager and application configuration elements.

  • The element is consistent with other application elements.

• The default should be current behavior, which is to not perform application library scans. Changing behavior is preferred, but not possible due to impacts to existing Liberty application installations.

  • Con: Defaulting to not perform scans makes for different default behavior between WebSphere Traditional and WebSphere Liberty.
  • Con: Placement of component defining annotations in application library JAR files, while allowed, is strongly recommended against.
  • Pro: Defaulting to not performing scans provides maximum consistency for existing Liberty application installations.
  • Pro: Performing scans on application library JARs increases application start times, in proportion to the number of JARs and their sizes in application libraries.

---

Background

Sample

For example, test jar "SpringAnnoTest.jar", with "JarInit.java", which is a web application initializer with an "onStartup" method, is not located when "SpringAnnoTest.jar" is an EAR library jar. This initializer is located in TWAS and is not located in Liberty:

SpringAnnoTest.jar/src/spring/test/init/jar/JarInit.java

package spring.test.init.jar;

import jakarta.servlet.ServletContext;
import jakarta.servlet.ServletException;

import org.springframework.web.WebApplicationInitializer;

public class JarInit implements WebApplicationInitializer {
    @Override
    public void onStartup(ServletContext servletContext) throws ServletException {      
        System.out.println("AnnotationScanInJarTest test output: onStartup method found via jar file");
    }
}

The problem is specific to applications packaged as enterprise applications. That is to say, which are packaged using an Enterprise Application Archive (EAR file), which may contain java archives (JAR files) under an application library folder. This problem does not occur for applications which are packaged as Web Module Archives (WAR files). The "WEB-INF/lib" folder of WAR files is not the same as the "lib" folder of EAR files.

Customer Impact

This behavior difference has been noted by a customer migrating / modernizing applications from WebSphere Traditional to WebSphere Liberty. (A case is active.)

Changing the Liberty behavior will have two impacts to existing Liberty application deployments:

• Adding scans of application library archives has the potential to add annotations and classes to scan results. This would be a major change of behavior to existing application installations.
• Adding scans of application library archives makes the scan space larger, adding to the time needed for annotation scanning in proportion to the size and count of JAR files which are added.

To date, no Liberty application installation has noted the difference in scan behavior.

The problem scenario will be seen with an increased likelihood as a consequence of ongoing WebSphere development projects which directly enable the deployment of applications from WebSphere Traditional to WebSphere Liberty.

Reproducibility

The problem is easily reproduceable in Liberty. See open-liberty pull request 30592 (https://github.com/OpenLiberty/open-liberty/pull/30592/files), and run the new fat test without the other code changes.

Noted on the case, the sample application deploys on WebLogic and Apache TomEE.

Specification

The JavaEE v7 specification has:

Java™ Platform, Enterprise Edition (Java EE) Specification, v7 
Final Release - 4/5/13

EE.8.5.2 Deploying a Java EE Application

4. If the module deployment descriptor is absent, or is present and is
a Java EE 5 or later version descriptor and the metadata-complete
attribute is not set to true, the deployment tool must examine all the
class files in the application package that can be used by the module
(that is, all class files that are included in the .ear file and can
be referenced by the module, such as the class files in- cluded in the
module itself, class files referenced from the module by use of a
Class-Path reference, class files included in the library directory,
etc.). Any annotations that specify deployment information must be
logically merged with the information in the deployment descriptor (if
present). Note that the presence of component-declaring annotations in
shared artifacts, such as libraries in the library directory and
libraries referenced by more than one module through Class-Path
references, can have unintended and undesirable consequences and is
not recommended. The correspondence of annotation information with
deployment descriptor information, as well as the overriding rules,
are described in this and other Java EE specifications. The result of
this logical merge process provides the deployment information used in
subsequent deployment steps. Note that there is no requirement for the
merge process to produce a new deployment descriptor, although that
might be a common implementation technique.

Code Updates

The problem has a relatively small fix. This is also provided in the open-liberty pull request 30592 (https://github.com/OpenLiberty/open-liberty/pull/30592/files). Application library information is readily available and may be used to add library jars for scanning. See, in particular, the update to "com.ibm.ws.container.service.annocache.internal.WebAnnotationsImpl.java" in the pull request (https://github.com/OpenLiberty/open-liberty/pull/30592/files#diff-7ea24aacd210af7cd669109121db148f1cb75872fd5a4ae3f00bc34d701b747c).

Notes

The JavaEE specification notwithstanding, no cases have been opened against WebSphere Liberty in regards to scans of application library jars.

WebSphere Liberty does scan referenced classes in application library jars.

---

Design Call Notes

Need to review behavior changes with respect to CDI. Followup w/Ben and Emily and the CDI team.

Does this same problem exist for shared libraries? If so, the setting for shared libraries should be unified with the setting for application libraries. (Not mentioned on the call: Does this problem exist for manifest class path jars?)

Given the lack of reported problems, having the current behavior as the default seems preferred. The preference is to add an attribute to the application element.

Adding an attribute to the application manager element would be necessary to enable the behavior for dropins applications. However, the preference was to not add an application manager element.

See the recently added setting for configuring application classloading behavior for consistency with TWAS. See issue #28110.

A UFO is recommended, since this is a design change.

Having a UFO will mean a POC call will not be needed. An UFO will provide a place to remark that for migration scenarios the setting might be set to true.

[benjamin-confino]

Need to review behavior changes with respect to CDI. Followup w/Ben and Emily and the CDI team.

The review is now complete. I verified that the CDI visiblity fat bucket still passes with these changes, and I also used a debugger to watch the output of CDIArchiveImpl line 634 where CDI and annotation scanning communicate with a custom designed application to ensure the behavior does not change.

I discussed my findings with Emily and we're both satisfied that this will not cause issues for CDI