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 directory of the deployment.

It can be used for the following:

• To prevents automatic 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>false</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 automatic 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 impls as well -->
      <module name="myservicemodule" services="import"/>
    </dependencies>
    <!-- These add additional classes to the module. In this case it is the same as including the jar in the EAR's lib directory -->
    <resources>
      <resource-root path="my-library.jar" />
    </resources>
  </deployment>
  <sub-deployment name="myapp.war">
    <!-- This corresponds to the module for a web deployment -->
    <!-- it can use all the same tags as the <deployment> entry above -->
    <dependencies>
      <!-- Adds a dependency on a ejb jar. This could also be done with a Class-Path entry -->
      <module name="deployment.myear.ear.myejbjar.jar" />
    </dependencies>
    <!-- Set's 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>
  <!-- Now we are going to define two additional modules -->
  <!-- This one is a different version of javassist that we have packaged -->
  <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>