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.
New feature: 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.
newfeat
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
New feature: This topic
references one or more of the application server log files. Beginning
in WebSphere Application Server Version 8.0 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 or 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.
newfeat
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 conflicts between web fragments. Therefore, conflicts between
annotations 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 lower 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.