Web fragments
When developing web applications, if multiple web modules use the same components, consider including the components in a Web fragment 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 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.
Disabling the scanning of web fragments also disables annotation scanning. Therefore, if we need either of these, both are scanned.
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 we are unaware of servlets, filters, or security constraints included in a web fragment. Verify that all configured servlets, filters, and security constraints are functioning as expected.
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.
IBM recommends using the High Performance Extensible Logging (HPEL) log and trace infrastructure . We view HPEL log and trace information using the logViewer .
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 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 we 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.
Use High Performance Extensible Logging to troubleshoot applications Web applications: Resources for learning Web container configuration for JavaServer Pages static file access