PI25329: ADD INCLUDE OPTIONS FOR ANNOTATION FILTERING.

Fixes are available

APAR status

Closed as new function.

Error description

Add new "include" type options for annotation filtering.

Local fix

Problem summary

****************************************************************
* USERS AFFECTED:  All users of IBM WebSphere Application      *
*                  Server                                      *
****************************************************************
* PROBLEM DESCRIPTION: Annotation filtering options have       *
*                      exclude type options, but do not have   *
*                      include type options.                   *
****************************************************************
* RECOMMENDATION:                                              *
****************************************************************
This text is a subset of text available in IBM Knowledge
Center.  See the Knowledge Center for additional details.
---
Annotation filtering options provide an "exclude" capability:
At several scopes, one or more archives may be excluded from
annotations processing. At several scopes, one or more
packages may be excluded from annotations processing.
For greater flexibility, new "include" type options are
provided.  The new include type options parallel the
previously available exclude type options: At several scopes,
one or more archives may be included for annotations
processing. At several scopes, one or more packages may be
included for annotations processing.
To exclude archives from annotation processing use:
Java System Property:
com.ibm.ws.amm.scan.context.filter.archives
Manifest Attribute: Ignore-Scanning-Archives
To exclude packages from annotations processing use:
Java System Property:
com.ibm.ws.amm.scan.context.filter.packages
Manifest Attribute: Ignore-Scanning-Packages
To exclude all archives except specifically listed archives
from annotations processing, use:
Java System Property:
com.ibm.ws.amm.scan.context.include.archives
Manifest Attribute: Include-Scanning-Archives
To exclude all packages except specifically listed packages
from annotations processing, use:
Java System Property:
com.ibm.ws.amm.scan.context.include.packages
Manifest Attribute: Include-Scanning-Packages
---
For all annotation filtering options, an option is available
which applies to archives (including module archives), and an
option is available which applies to packages.  Options for
archives use a comma (",") delimited list of archive names.
Options for package names use a "," delimited package list.
Archive names are tested using the simple archive name (for
"WEB-INF/lib/fragment.jar", only "fragment.jar" is used when
matching the archive name against an option value).  Package
names are tested as a prefix text.  That is, class
"myCo.utilities.util1.Utility1.class" is matched against
filter value "myCo.utilities." by testing whether the class
name starts with the filter value.
For all annotation filtering options, an option value may be
specified within "amm.filter.properties", an option value may
be specified as a java system property, and an option value
may be specified within an archive MANIFEST as a main
attribute.
The name of the property used within "amm.filter.properties"
is the same as the name of the manifest main attribute.  A
different name is used for the java system property.  Option
values may be specified in some, all, or none of the
locations, with values in multiple locations being applied to
all classes within the scope encompassed by the locations.
That is, options specified to "amm.filter.properties" apply to
all applications processed by all processes launched from the
enclosing server profile. Options specified as a java system
property apply to all applications processed by the process
which has the java system property assigned.  Options
specified in an EAR file MANIFEST apply to all modules within
the EAR file.  Options specified within a module archive (JAR,
RAR, or WAR) apply to all classes within the module archive.
Options specified within a non-module JAR file apply to the
classes within the JAR file.  (Options specified to a RAR file
or a WAR file MANIFEST do apply to the JAR files contained by
the the RAR or WAR file.)
The meaning of the several "exclude" type options is to list
archives or packages which are to be excluded from annotations
processing.  During annotations processing, before processing
any classes in a particular archive, a test is made to tell if
the archive is listed as an excluded archive.  If the archive
is an excluded archive, annotation processing will be done
on none of classes in the archive.  During annotations
processing, before processing a particular class, a test is
made to tell if the class is listed as an excluded class.  If
the class is an excluded class, annotations processing
is not done on the class.
The meaning of the several new "include" type options is to
list archives or packages which are to be included in
annotation processing.  During annotation processing, before
processing any classes in a particular archive, a test is made
to tell if any archive include options are specified, and
whether the archive is listed as an included archive.  If any
archive include option is specified and the archive is not
listed as an included archive, annotation processing is
done on none of the classes in the archive.  During
annotations processing, before processing a particular class,
a test made to tell if any package include options are
specified, and whether the package of the class is listed as
an included package.  If any package include option
is specified, and if the package of the class is not listed
as an included package, annotations processing is not done on
the class.
The new "include" type options are symmetric with the
"exclude" type options.  Both the current exclude type options
and the new include options type may be specified in the
"amm.filter.properties" file.  Both types of options may be
specified as system properties.  Both types of options may be
specified as manifest properties in the several types of java
archives used to package JavaEE applications.  (The several
types of java archives being EAR files, WAR files, RAR files,
and JAR files.)
The new "include" type options have the same effect of
accumulating from the several locations in which the options
may be specified: Options are processed starting with a
specific archive, then proceed to all enclosing
archives, then to the java system property, then to the
"amm.filter.properties" file.
A key note for "include" type options is that they have
a dramatic effect to remove archives or packages from
annotations processing.  If an include option is specified,
only those archives or packages specified in the option value
will be processed for annotations.  Annotations processing
will skip all other archives or packages. This is important to
note because "amm.filter.properties" and java system properties
have global effects.
The main recommendation for using these annotation filtering
options is to place manifest attributes in applications,
module archives, and jar files.  Placement as manifest
attributes controls the scope of effect of the annotation
filtering options.  In addition, the filtering options are
transported along with the enclosing archive.  Use of
"amm.filter.properties" or of java system properties is
less recommended, since options specified as java system
properties or with "amm.filter.properties" have a very wide
scope, and are not transported along with an application,
module archive, or jar file.  In particular, use of include
options within either "amm.filter.properties" or as a java
system properties must be done very carefully to avoid
accidental side effects.
---
For example, a web module archive (WAR file) has:
sample.war\
META-INF\MANIFEST.MF
WEB-INF\classes\myCo\orders\OrderServlet.class
WEB-INF\lib\billing.jar\myCo\billing\BillingServlet.class
WEB-INF\lib\util1.jar\myCo\utility\utils1\Utility.class
WEB-INF\lib\util2.jar\myCo\utility\utils2\Utility.class
WEB-INF\lib\util3.jar\myCo\utility\utils3\Utility.class
In this example, "fragment.jar" is to be scanned for
annotations, and "util1.jar", "util2.jar", and "util3.jar" are
to be skipped.
Using an "exclude archives" option, the WAR MANIFEST.MF is
updated to add an "Ignore-Scanning-Archives" main attribute:
Manifest-Version: 1.0
Created-By: jvm
Ignore-Scanning-Archives: utils1.jar, utils2.jar, utils3.jar
Using an "include archives" option, the WAR MANIFEST.MF is
updated to add an "Include-Scanning-Archives" main attribute:
Manifest-Version: 1.0
Created-By: jvm
Include-Scanning-Archives: fragment.jar
Using an "exclude packages" option, the WAR MANIFEST.MF is
updated to add an "Ignore-Scanning-Packages" main attribute:
Manifest-Version: 1.0
Created-By: jvm
Ignore-Scanning-Packages: myCo.utility.
Using an "include packages" option, the WAR MANIFEST.MF is
updated to add an "Include-Scanning-Packages" main attribute:
Manifest-Version: 1.0
Created-By: jvm
Include-Scanning-Packages: myCo.orders., myCo.billing.
The trailing "." is included in the package lists to avoid
accidental matching where a package name is a prefix of
another package name.  For example, if packages "myCo.payments"
and "myCo.paymentsHistory" are both package names, a package
value of "myCo.payments" matches classes in both packages.  To
select just the first package, "myCo.payments", a trailing "."
must be included.

Problem conclusion

Include options have been added..

The fix for this APAR is currently targeted for inclusion in
fix packs 8.5.5.4 and 8.0.0.10.  Please refer to the
Recommended Updates page for delivery information:
http://www.ibm.com/support/docview.wss?rs=180&uid=swg27004980

Temporary fix

Comments

APAR Information

APAR number
PI25329
Reported component name
WEBSPHERE APP S
Reported component ID
5724J0800
Reported release
850
Status
CLOSED PER
PE
NoPE
HIPER
NoHIPER
Special Attention
NoSpecatt
Submitted date
2014-09-09
Closed date
2014-11-19
Last modified date
2014-11-19

APAR is sysrouted FROM one or more of the following:
APAR is sysrouted TO one or more of the following:

Fix information

Fixed component name
WEBSPHERE APP S
Fixed component ID
5724J0800

Applicable component levels

R800 PSY
UP
R850 PSY
UP

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"8.5","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
28 April 2022

Tips

PI25329: ADD INCLUDE OPTIONS FOR ANNOTATION FILTERING.

Fixes are available

Subscribe

APAR status

Closed as new function.

Error description

Local fix

Problem summary

Problem conclusion

Temporary fix

Comments

APAR Information

APAR number

Reported component name

Reported component ID

Reported release

Status

PE

HIPER

Special Attention

Submitted date

Closed date

Last modified date

APAR is sysrouted FROM one or more of the following:

APAR is sysrouted TO one or more of the following:

Fix information

Fixed component name

Fixed component ID

Applicable component levels

R800 PSY

R850 PSY

Document Information

Share your feedback

Need support?