When developing web applications, if multiple web modules
use the same components, consider including the components in a Web
fragment Java archive (JAR) file. The web fragment JAR file contains
both the configuration metadata and component class files. This practice
enables easier copying from application to application.
Web module deployment descriptor fragments (web fragments) provide
the same configuration metadata that a web.xml file provides, but
they exist as a web-fragment.xml file that is packaged inside a JAR
file in the WEB-INF/lib directory.
Framework developers provide JAR files that are included in a web
application which uses that specific framework. If that framework
uses servlets, filters, or other web module configuration, web fragments
provide the ability to simply drag the JAR file into an application
without requiring changes to the existing web module configuration.
Previously, web application developers were required to augment their
configuration with additional metadata required by the framework.
Another use case is the aforementioned need to use the same components
across web modules. Also, the use of mock objects or stubs might be
made easier with Web fragments.
Scanning for web fragments decreases performance for each JAR file
that it checks for a web-fragment.xml file. The higher the number
of JAR files in a web application, the higher the performance impact.
If performance concerns demand, disable scanning for web fragments
by setting metadata-complete to
true and include
any necessary configuration in the web.xml file.
Avoid trouble: Disabling the scanning of web fragments also disables
annotation scanning. Therefore, if you need either of these, both
are scanned.
gotcha
Important: Set the metadata-complete
element in the web.xml file to true to disable fragment
scanning. Use the absolute-ordering tag in the web.xml file to force
an order for scanning web fragments or scan a subset of the web fragments.
Use the relative-ordering tag in web-fragment.xml files to specify
order relative to another fragment.
Including fragments in a web application might inadvertently expose
endpoints to security risks if you are unaware of servlets, filters,
or security constraints that are included in a web fragment. Verify
that all configured servlets, filters, and security constraints are
functioning as expected.
Avoid trouble: If there is a conflict
in the web fragments, applications will not deploy. If there is conflict
when installing the application, view the SystemOut.log file to understand
which items are conflicting.
gotcha
Note: This topic references one or more of the application
server log files. As a recommended alternative, you can configure
the server to use the High Performance Extensible Logging (HPEL) log
and trace infrastructure instead of using SystemOut.log , SystemErr.log, trace.log, and activity.log files on distributed and IBM® i systems. You can also use
HPEL in conjunction with your native z/OS® logging facilities. If you are using HPEL, you can access
all of your log and trace information using the LogViewer command-line
tool from your server profile bin directory. See the information
about using HPEL to troubleshoot applications for more information
on using HPEL.
General rules for merging web fragments and annotations in the
Servlet 3.0 specification:
- JAR files are only scanned for annotations or web fragment metadata
if they are in the WEB-INF/lib directory. Shared libraries are not
scanned for annotations or web fragment metadata.
- Annotations that are in classes in the WEB-INF/classes directory
are merged first and take precedence over any metadata in the WEB-INF/lib
directory.
- All JAR files in the WEB-INF/lib directory are considered Web
fragments, regardless of whether they contain a web-fragment.xml file.
If a web-fragment.xml file does not exist in a JAR file, it is considered
to have an implicit, empty web-fragment.xml file.
- Annotations for each JAR file in the WEB-INF/lib directory are
merged into the corresponding web-fragment.xml file before checking
for conflicting web fragments. Therefore, annotations conflicts in
different fragments prevents the application from deploying.
- If you define web fragment ordering, both the annotation and Web
fragment metadata for one web fragment is merged before another fragment
that is later in the order.
- Because all JAR files in the WEB-INF/lib directory are considered
fragments, the <others> element in an <absolute-ordering> element
applies to all JAR files that are not mentioned elsewhere in the ordering.