Reducing annotation searches during application deployment

Enterprise applications containing many classes and are enabled for annotations processing (are not marked as "metadata-complete") take extra time to deploy. Extra time is necessary to scan application binaries for annotations that were introduced by Java EE 5. If there are no additional options to limit which classes are scanned, when scanning is enabled for a module all classes in the module must be scanned. A scan of all classes is necessary even when only a small subset of classes within a given module has annotations.

Fast bytecode scanning technology is used to improve deployment performance. However, better deployment performance is achieved by limiting which classes are scanned for annotations.

When a module is marked as metadata-complete, it applies to an entire module. Marking the module as metadata-complete cannot be done when annotation processing is necessary. Additionally, marking the module as metadata-complete prevents the scanning of a module, which causes problems for web modules that use EJB or web service annotations.

JAR files of web module archives (WAR files) might be moved to the application library folder. However, moving the WAR files might not be possible since doing so can break web module encapsulation, or because multiple modules that require different JAR files are present.

To overcome these limitations, and to reduce deployment time, IBM WebSphere Application Server provides options for limiting which classes are scanned for annotations.

Install an application that supports Java EE 5 or later on a product server. If deployment is unreasonably slow and you plan to deploy the application again in the future, and if the application contains modules that are enabled for annotation processing, complete a procedure in this topic to reduce the number of classes that are scanned for annotations.

The product provides a configurable filtering function to reduce the number of classes that are searched for annotations. We can identify which modules or Java packages to ignore for annotations processing through four properties: (or manifest attributes):

• Ignore-Scanning-Archives

• Ignore-Scanning-Packages

• Include-Scanning-Archives

• Include-Scanning-Packages

The properties can be specified either in amm.filter.properties in app_server_root/properties, or can be specified as manifest attributes.

We can also identify which modules or Java packages to ignore using these system properties:

• com.ibm.ws.amm.scan.context.filter.archives

• com.ibm.ws.amm.scan.context.filter.packages

• com.ibm.ws.amm.scan.context.include.archives

• com.ibm.ws.amm.scan.context.include.packages

Use these options to limit which classes are scanned for annotations. Performance is improved proportionally to the number of classes that are removed. Remove from processing any classes containing no annotations data.

Usually, filtering is done on whole archives. A frequent filtering case is to filter utility JAR files included in a WAR containing no annotations data.)

The Ignore-Scanning-Archives and Ignore-Scanning-Packages properties are used to specify the subsets of classes to be ignored during annotation processing. All classes in archives specified by Ignore-Scanning-Archives are skipped during annotation processing. All classes in packages specified by Ignore-Scanning-Packages are also skipped during annotation processing.

The Include-Scanning-Archives and Include-Scanning-Packages properties are used to specify the subsets of classes to be scanned during annotation processing. When either property is specified, only those classes that are included are scanned; any other classes are ignored.

A default set of values is provided in the amm.filter.properties file in app_server_root/properties for Ignore-Scanning-Archives and Ignore-Scanning-Packages.

No defaults are provided for Include-Scanning-Archives and Include-Scanning-Packages.

The property values provide both coarse and fine-grained control over the scope for annotations processing, with Ignore-Scanning-Archives providing coarser control than Ignore-Scanning-Packages, and similarly, Include-Scanning-Archives providing coarser control than Include-Scanning-Packages.

The syntax for all four properties follows the comma-separated value convention. No wildcard or regular expressions are permitted and values are case-sensitive.

The use of both the include and exclude properties at the same time is unusual, but it is supported. When an include property is specified with an exclude property, classes are selected for processing when they are included and not excluded. If both Ignore-Scanning-Archives and Include-Scanning-Archives are specified, a class is scanned during annotation processing, but only if the class is within an archive specified by Include-Scanning-Archives and not within an archive specified by Include-Scanning-Archives. Similarly, if both Ignore-Scanning-Archives and Include-Scanning-Packages are specified, a class is scanned during annotation processing, but only if the class is within a package specified by Include-Scanning-Packages and not within an archive specified by Ignore-Scanning-Packages.

Options specified using the amm.filter.properties file are global to the profile. All applications that are encountered by processes that are launched by that profile use the specified options. Options specified as system properties are global to the process on which the properties are set. All applications that are encountered by the process use the specified options.

Manifest attributes can be specified at three different scopes:

• Application (EAR file)

• Module (WAR/RAR/JAR file)

• Web fragment (JAR file)

In all cases, a manifest attribute is applicable to all enclosed scopes. A manifest attribute specified as an application (EAR file) attribute applies to annotation scanning for all modules archives and fragment JAR files. A manifest attribute specified as a module (WAR/RAR/JAR file) applies to annotations within the module. A manifest attribute specified as a web fragment (JAR file) applies to that web fragment.

Manifest attributes specified at multiple scopes are additive. Options specified by using amm.filter.properties, system properties, and manifest attributes are additive.

The default set of values can be changed by an administrator or augmented by using one of the following steps.

• Place an amm.filter.properties file in the profile_root/properties directory. Update the amm.filter.properties file with a combination of property assignments to limit which classes are scanned during annotations.

• Use system properties to supply values for the Ignore-Scanning-Archives and Ignore-Scanning-Packages properties.

  • The com.ibm.ws.amm.scan.context.filter.archives system property supplies values for the Ignore-Scanning-Archives property.

  • The com.ibm.ws.amm.scan.context.filter.packages system property supplies values for the Ignore-Scanning-Packages property.

  • The com.ibm.ws.amm.scan.context.include.archives system property supplies values for the Include-Scanning-Archives property.

  • The com.ibm.ws.amm.scan.context.include.packages system property supplies values for the Include-Scanning-Packages property.

  See the topic on Java virtual machine custom properties.

• Add Ignore-Scanning-Archives, Ignore-Scanning-Packages, Include-Scanning-Archives, and Include-Scanning-Packages entries to the application manifest, META-INF/MANIFEST.MF, to module manifests, or to fragment manifests.

  When you update the application manifest, follow line-length limitations and other constraints for the manifest.gotcha

• Add Ignore-Scanning-Archives and Ignore-Scanning-Packages entries to the module manifest.

  When you update the module manifest, follow line-length limitations and other constraints for the manifest.

  Use caution before you use include type options at profile, process, or application scope. When an include type option is used, all classes except those classes specified to an include option are ignored.

  There are several items to consider when you set options:

  • The amm.filter.properties file and system properties are suggested for frequent cases (for example, for utility JAR files known to never contain annotations data), or for limited testing purposes.

  • Use of manifest attributes is suggested for options that are specific to a single application or application module.

  • When you use the amm.filter.properties file or system properties, ensure that all necessary profiles and processes are updated.

  • When you use manifest attributes, the settings are transported with the enclosing application, module (or fragment). The settings must be made once only. However, to set manifest attributes requires an update to a packaged application, and usually requires a redeployment of the application.

  Other options include setting metadata-complete to true and moving JAR files from a web module to the application library folder. These two options are not always possible. gotcha

What to do next

Install the application again. If deployment continues to be slow, specify more modules and Java packages to ignore.

Related tasks

Troubleshooting deployment

Java virtual machine custom properties