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 allows you to define additional dependencies, it is the same as using the Dependencies: manifest attribute -->
    <!-- Note that the export="true" is necessary if these dependencies are to be seen by the sub-deployments -->
    <!-- if export is not set or is set to false, then the dependencies are only visible to the classes in the jars in the ear 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>