Jboss-deployment-structure.xml
External
- Developer Guide jboss-deployment-structure.xml https://docs.jboss.org/author/display/AS71/Developer+Guide#DeveloperGuide-JBossDeploymentStructureFile
Internal
TODO
Deplete: https://home.feodorov.com:9443/wiki/Wiki.jsp?page=JbossDeploymentStructure.xml
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.
For classes like "javax.security.auth.spi.LoginModule", this works:
<jboss-deployment-structure>
<deployment>
<dependencies>
<module name="javax.api"/>
</dependencies>
</deployment>
</jboss-deployment-structure>
For other JDK-included classes, this may also work:
<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>
Elements
<deployment>
<dependencies>
<module>
name
slot
servces specifies whether and how services found in this dependency are used (default is "none"). Specifying a value of "import" for this attribute is equivalent to adding a filter at the end of the import filter list which includes the META-INF/services path from the dependency module. Setting a value of "export" for this attribute is equivalent to the same action on the export filter list.