How to add a web fragment to all applications deployed on WildFly

In this article we will learn how to create a Web fragment XML file (web-fragment.xml) and how to make it default for all applications deployed on WildFly by using a the deployment-overlay feature.

Firsr off, we need some definitions:

Web fragments are xml configuration files that contain parts of a standard web.xml configuration file. There can be or or many web fragments, and when the application is deployed, the application server will combine all the fragments and will treat it like a single web.xml.

Web fragments allow a logical partitioning of the web application in such a way that the frameworks being used within the web application can define all the artifacts without requiring you to edit or add information in the web. xml . For example, in the following project, a Web fragment can host the definition of a Servlet filter:

src
└── main
    ├── java
    │   └── org
    │       └── jboss
    │           └── web
    │               └── filter
    │                   └── LoggingFilter.java
    └── resources
        └── META-INF
            ├── MANIFEST.MF
            └── web-fragment.xml

Here is the META-INF/web-fragment.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<web-fragment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns="http://java.sun.com/xml/ns/javaee" xmlns:webfragment="http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-fragment_3_0.xsd"
	id="MyCommonWeb" version="3.0">
	<display-name>MyCommonWeb</display-name>
	<name>MyCommonWeb</name>

	<filter>
		<filter-name>Logging</filter-name>
		<filter-class>org.jboss.web.filter.LoggingFilter</filter-class>
	</filter>

	<filter-mapping>
		<filter-name>Logging</filter-name>
		<url-pattern>/*</url-pattern>
	</filter-mapping>


</web-fragment>

Combining Web fragments with Deployment Overlays

In this paragraph I’m going to introduce the Deployment overlay which is a feature available on WildFly / JBoss EAP. A Deployment overlay is a way to include content into an existing deployment without physically modifying the contents of the deployment archive.

By combining Web fragments with Deployment Overlays, you have a very powerful feature: that is, you can define bits of your application configuration in a Web fragment (which is common to all your applications, for example) and then create a deployment overlay which can link the Web fragment to some or all your applications.

Let’s see an example.

Supposing you have a security-constraints section which is common to all your Web applications.

Firstly, create META-INF/web-fragment.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<web-fragment xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
    http://xmlns.jcp.org/xml/ns/javaee/web-fragment_3_1.xsd"
    version="3.1">

        <security-constraint>
                <web-resource-collection>
                        <web-resource-name>HtmlAuth</web-resource-name>
                        <description>application security constraints</description>
                        <url-pattern>/*</url-pattern>
                        <http-method>GET</http-method>
                        <http-method>POST</http-method>
                </web-resource-collection>
                <auth-constraint>
                        <role-name>Admin</role-name>
                </auth-constraint>
        </security-constraint>
        <login-config>
                <auth-method>BASIC</auth-method>
                <realm-name>UserRoles simple realm</realm-name>
        </login-config>
        <security-role>
                <role-name>Admin</role-name>
        </security-role>
</web-fragment>

Secondly, pack the folder META-INF/web-fragment.xml in a JAR file:

$ jar cvf mysecurity.jar META-INF/web-fragment.xml

Finally, from WildFly CLI, create a deployment-overlay specifying the deployment paths you want them to overlay.add the generated web-fragment-lib.jar to all deployed war:

deployment-overlay add --name=web-fragment-jar --content=WEB-INF/lib/mysecurity.jar=/path/to/mysecurity.jar --deployments=*.war --redeploy-affected

By running the above command, all Web applications (*.war) will include in the WEB-INF/lib folder the file mysecurity.jar (adjust the path to the location of your filesystem where the jar file can be found).

Other examples of Web fragments include, for example, to define a standard way to track HTTP Sessions. By including a session-config element in a Web fragment, you can define the tracking mode, which can be for example COOKIE:

<web-fragment xmlns="http://xmlns.jcp.org/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
    http://xmlns.jcp.org/xml/ns/javaee/web-fragment_3_1.xsd"
    version="3.1">
    <session-config>
        <tracking-mode>COOKIE</tracking-mode>
    </session-config>
    <distributable/>  
</web-fragment>

Pack the above META-INF/web-fragment.xml in a JAR file and define a deployment-overlay, to make the session-config by using COOKIE a standard for all your Web applications.

In conclusion, we have covered what Web fragments are and how to use deployment overlays to make them default for all (or some) of your Web applications.