Jboss-deployment-structure.xml

External

• Developer Guide jboss-deployment-structure.xml https://docs.jboss.org/author/display/AS71/Developer+Guide#DeveloperGuide-JBossDeploymentStructureFile

Internal

• WildFly Deployment Descriptors
• WildFly Modules

Overview

jboss-deployment-structure.xml is a WildFly proprietary deployment descriptor that allows finely grained class loading control.

It must be placed in the META-INF (or the WEB-INF, if the deployment is a WAR) directory of the deployment.

It can be used for the following:

• To prevents implicit dependencies from being added.
• To add module dependencies.
• To define additional modules. What for? How is that useful?
• To change an EAR deployments isolated class loading behavior, independently of the general setting described here: ear-subdeployments-isolated setting.
• To add additional resource roots to a module.

Example

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2">

  <!-- 
         Override the global 'ear-subdeployments-isolated' setting. 
  -->
  <ear-subdeployments-isolated>true</ear-subdeployments-isolated>

  <!-- 
         This configuration element corresponds to the top level deployment. For a WAR this is 
         the WAR's unique module, for an EAR is the top level module, which contains the classes
         in the EAR's lib folder.
   -->
  <deployment>

     <!-- 
         'exclude-subsystem' prevents a subsystems deployment unit processors running on 
          a deployment. This is equivalent with removing the subsystem only for this deployment.
      -->
     <exclude-subsystems>
         <subsystem name="resteasy"/>
     </exclude-subsystems>

     <!--
         The 'exclusion' element prevents the addition of the specified implicit dependencies.
     -->
     <exclusions>
        <module name="org.javassist"/>
     </exclusions>

    <!-- 
           This is how additional dependencies are defined (also 'Dependencies:' manifest attribute
           can be used. export="true" must be specified if the dependencies should be seen by the
           sub deployments. The default value is "false", and in this case, the dependencies are only 
           visible to the classes in the jars in the EAR's lib 
     -->
    <dependencies>
        <module name="deployment.javassist.proxy" export="true"/>
        <module name="deployment.myjavassist" export="true"/>
        <!-- 
               Import META-INF/services for ServiceLoader implementations
         -->
        <module name="myservicemodule" services="import"/>
    </dependencies>

    <!-- 
          Use this element to add additional classes to the module. For EARs is similar to including the
          JAR to the EAR's lib directory.
    -->
    <resources>
        <resource-root path="my-library.jar" />
        </resources>
  </deployment>

  <!-- 
        The 'sub-deployment' element corresponds to the module for a WAR deployment and it can
        use the same tags as the main 'deployment' element.
  -->
  <sub-deployment name="myapp.war">
     ...
    <dependencies>
        <!-- 
              Can be used to add a dependency on a sibling EJB jar, while there are no implicit dependencies
              on all others. This could also be done with a Class-Path entry.
         -->
        <module name="deployment.myear.ear.myejbjar.jar" />
    </dependencies>

    <!-- 
          Specifies that a local resources to have the lowest priority: if the same class is both in the 
          sub-deployment and in another sub-deployment that is visible to the WAR, then the class 
          from the other deployment will be loaded,  rather than the class actually packaged in the 
          WAR. This can be used to resolve ClassCastExceptions  if the same class is in multiple 
          sub-deployments
     -->
     <local-last value="true" />
  </sub-deployment>

  <!-- 
         The element can be used to define additional modules.
  -->
  <module name="deployment.myjavassist" >
      <resources>
          <resource-root path="javassist.jar" >
     
           <!-- 
                  We want to use the servers version of javassist.util.proxy.* so we filter it out
           -->
           <filter>
                <exclude path="javassist/util/proxy" />
           </filter>
         </resource-root>
     </resources>
  </module>

  <!-- 
           This is a module that re-exports the containers version of javassist.util.proxy. This means that 
           there is only one version of the Proxy classes defined.
  -->
  <module name="deployment.javassist.proxy" >
    <dependencies>
      <module name="org.javassist" >
        <imports>
          <include path="javassist/util/proxy" />
          <exclude path="/**" />
        </imports>
      </module>
    </dependencies>
  </module>
</jboss-deployment-structure>

Declaring a Dependency on another Module

<jboss-deployment-structure ...>
  <deployment>
    <dependencies>
        <module name="io.novaordis.playground.wildfly.custommodule" slot="1.0"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

More details:

How to specify a dependency on a JBoss Module in JBoss EAP 6 / 7 https://access.redhat.com/solutions/341703

Note that the dependency on a module can also be declared in the MANIFEST.MF of the JAR that needs the module. For more details, see WildFly Modules - Explicit Dependencies

Accessing JDK Classes

Not all JDK classes are exposed to a deployment by default. They can be exposed to the deployment via the <dependencies> mechanism:

<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.1">
    <deployment>
        <dependencies>
            <system export="true">
                <paths>
                    <path name="com/sun/corba/se/spi/legacy/connection"/>
                </paths>
            </system>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

TODO: validate this and de-red or remove:

<jboss-deployment-structure>
      <deployment>
         <dependencies>
            <module name="sun.jdk"/>
            <module name="javax.api"/>
         </dependencies>
      </deployment>
</jboss-deployment-structure>