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 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. If we 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

This topic references one or more of the application server log files. As a recommended alternative, we 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. We can also use HPEL in conjunction with the native z/OS logging facilities. If we are using HPEL, we can access all of the log and trace information using the LogViewer command-line tool from the 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 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.

Related tasks

Use High Performance Extensible Logging to troubleshoot applications

Web applications: Resources for learning

Web container configuration for JSP static file access