JBoss / WildFly XML descriptors reference

by

WildFly uses a set of custom XML descriptors which can be used to customize Enterprise applications. Today they are not used so widely as once, because they have been replaced by their equivalent annotations. Though it can be useful to have a reference to most common XML configuration file, if you prefer to maintain your configuration separated from your code.

jboss-deployment-structure.xml

The file jboss-deployment-structure.xml can be used to set application dependency against modules. The advantage of using this file (compared to the Manifest’s entry) is that you can define dependencies across top-level deployments and subdeployments.

Location: META-INF or WEB-INF of the top level deployment

Here is an example of how to add a module (deployment.itextpdf-5.4.3.jar) to a deployment (MyWebApp.war) as jar file. At the same time, we are selecting which packages to use in the module so that we exclude for example the com/itextpdf/awt/geom package:

<jboss-deployment-structure>
   <sub-deployment name="MyWebApp.war">
    <dependencies>
      <module name="deployment.itextpdf-5.4.3.jar" />
    </dependencies>
  </sub-deployment>
   <module name="deployment.itextpdf-5.4.3.jar" >
    <resources>
     <resource-root path="itextpdf-5.4.3.jar" >
         <filter>
         <exclude path="com/itextpdf/awt/geom" />
       </filter>
     </resource-root>
    </resources>
  </module>
</jboss-deployment-structure>

jboss-ejb3.xml

The is the EJB deployment descriptor and can be used to override settings from ejb-jar.xml, and to set some ejb3 specific settings:

Location: WEB-INF of a war, or META-INF of an EJB jar

Example: how to decare an EJB 3.X and set a custom Transaction Timeout:

 <jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
                  xmlns="http://java.sun.com/xml/ns/javaee"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd
                     http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
                  version="3.1"
                  impl-version="2.0">
    <enterprise-beans>
        <session>
            <ejb-name>DescriptorGreeter</ejb-name>
            <ejb-class>org.jboss.as.test.integration.ejb.descriptor.DescriptorGreeterBean</ejb-class>
            <session-type>Stateless</session-type>
        </session>
    </enterprise-beans>
        <assembly-descriptor>
        <container-transaction>
            <method>
                <ejb-name>DescriptorGreeter</ejb-name>
                <method-name>*</method-name>
                <method-intf>Local</method-intf>
            </method>
            <tx:trans-timeout>
                <tx:timeout>10</tx:timeout>
                <tx:unit>Seconds</tx:unit>
            </tx:trans-timeout>
        </container-transaction>
    </assembly-descriptor>
</jboss:ejb-jar>

Example 2: How to define an MDB and link it to a JMS Destination:

<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
                  xmlns="http://java.sun.com/xml/ns/javaee"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd
                     http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
                  version="3.1"
                  impl-version="2.0">
    <enterprise-beans>
                <message-driven>
                        <ejb-name>ReplyingMDB</ejb-name>
                        <ejb-class>org.jboss.as.test.integration.ejb.mdb.messagedestination.ReplyingMDB</ejb-class>
                    <activation-config>
                           <activation-config-property>
                                   <activation-config-property-name>destination</activation-config-property-name>
                                   <activation-config-property-value>java:jboss/mdbtest/messageDestinationQueue</activation-config-property-value>
                            </activation-config-property>
                        </activation-config>
                </message-driven>
    </enterprise-beans>
</jboss:ejb-jar>

Example 3: How to link an EJB with a Security Domain:

<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
               xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:s="urn:security"
               xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
               version="3.1" impl-version="2.0">

    <assembly-descriptor>
        <s:security>
            <ejb-name>Hello</ejb-name>
            <s:security-domain>MySecurityDomain</s:security-domain>
        </s:security>
    </assembly-descriptor>
</jboss:ejb-jar>

Example 4: How to link an EJB with a Container Interceptor:

<jboss xmlns="http://www.jboss.com/xml/ns/javaee"
       xmlns:jee="http://java.sun.com/xml/ns/javaee"
       xmlns:ci ="urn:container-interceptors:1.0">

    <jee:assembly-descriptor>
        <ci:container-interceptors>
            <!-- Class level container-interceptor -->
            <jee:interceptor-binding>
                <ejb-name>AnotherFlowTrackingBean</ejb-name>
                <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.ClassLevelContainerInterceptor</interceptor-class>
            </jee:interceptor-binding>
            <!-- Method specific container-interceptor -->
            <jee:interceptor-binding>
                <ejb-name>AnotherFlowTrackingBean</ejb-name>
                <interceptor-class>org.jboss.as.test.integration.ejb.container.interceptor.MethodSpecificContainerInterceptor</interceptor-class>
                <method>
                    <method-name>echoWithMethodSpecificContainerInterceptor</method-name>
                </method>
            </jee:interceptor-binding>
        </ci:container-interceptors>
    </jee:assembly-descriptor>
</jboss>

jboss-web.xml

JBoss Web deployment descriptor. This can be use to override settings from web.xml, and to set WildFly specific options

Location: WEB-INF

Example 1: How to use a Security Domain:

<jboss-web>
    <security-domain>ejb3-tests</security-domain>
</jboss-web>

Example 2: How to define the number of maximum active Sessions:

<jboss-web version="14.1" xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <max-active-sessions>1</max-active-sessions>
</jboss-web>

Example 3: How to use a custom worker from the io subsystem:

<jboss-web>
  <executor-name>test-worker</executor-name>
</jboss-web>

jboss-app.xml

WildFly application deployment descriptor. Can be used to override settings application.xml, and to set application specific settings.

Location: META-INF of an EAR

Example: Setting Security Roles for a Security Domain:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE jboss-app PUBLIC "-//JBoss//DTD J2EE Application 4.2//EN" "http://www.jboss.org/j2ee/dtd/jboss-app_4_2.dtd">
<jboss-app>
  <security-domain>mydomain</security-domain>
  <security-role>
    <role-name>Administrator</role-name>
    <principal-name>j2ee</principal-name>
  </security-role>
  <security-role>
    <role-name>Manager</role-name>
    <principal-name>javajoe</principal-name>
  </security-role>
</jboss-app>

jboss-permissions.xml

This file allows you to specify the permissions needed by the deployment. Can override those available in permissions.xml

Location: META-INF

Example: Setting Permission for a Specific Class name referenced by the deployment unit:

<permissions version="7">
  <permission>
  <class-name>java.util.PropertyPermission</class-name>
  <name>*</name>
  <actions>read</actions>
  </permission>
</permissions>

ironjacamar.xml

Deployment descriptor for Resource Adaptor deployments.

Location: META-INF of a rar archive

Example: Define a ConnectionFactory:

<ironjacamar>
   <connection-definitions>
     <connection-definition class-name="org.jboss.as.test.smoke.rar.HelloWorldManagedConnectionFactory"
                            jndi-name="java:/eis/HelloWorld"/>
   </connection-definitions>
</ironjacamar>

jboss-client.xml

The WildFly specific deployment descriptor for application client deployments.

Location: META-INF of an application client jar

Example: Setting an environment entry for a client deployment:

<jboss-client>
      <env-entry>
        <env-entry-name>stringValue</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>OverridenEnvEntry</env-entry-value>
    </env-entry>
</jboss-client>

jboss-webservices.xml

The JBossWS 4.0.x specific deployment descriptor for JAX-WS Endpoints.

Location: META-INF for EJB webservice deployments or WEB-INF
for POJO webservice deployments/EJB webservice endpoints bundled in .war

Example: how to set a JAX-WS property at application level:

<webservices xmlns="http://www.jboss.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee http://www.jboss.org/j2ee/schema/jboss_web_services_1.2.xsd">
    <property>
        <name>org.jboss.ws.cxf.disableHandlerAuthChecks</name>
        <value>true</value>
    </property>
</webservices>

JMS Deployment descriptors (*-jms.xml)

Can be used to define application scoped JMS destinations.

Location: deployments folder of the application server or META-INF or WEB-INF of the application.

Example:

<messaging-deployment xmlns="urn:jboss:messaging-activemq-deployment:1.0">
    <server>
        <jms-destinations>
            <jms-queue name="queue1">
                <entry name="java:/queue1"/>
                <durable>true</durable>
            </jms-queue>
            <jms-topic name="topic1">
                <entry name="java:/topic1"/>
            </jms-topic>
        </jms-destinations>
    </server>
</messaging-deployment>

Datasource Deployment descriptors (*-ds.xml)

Can be used to define application scoped Datasources.

Location: deployments folder of the application server or META-INF or WEB-INF of the application.

Example:

<datasources xmlns="http://www.jboss.org/ironjacamar/schema">
    <datasource jndi-name="java:jboss/datasources/DeployedDS" enabled="true" use-java-context="true"
                pool-name="H2DS">
        <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
        <driver>h2</driver>
        <pool></pool>
        <security>
            <user-name>sa</user-name>
            <password>sa</password>
        </security>
    </datasource>
    <xa-datasource jndi-name="java:/H2XADS" pool-name="H2XADS">
        <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
        <xa-datasource-property name="URL">jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</xa-datasource-property>
        <driver>h2</driver>
        <security>
            <user-name>sa</user-name>
            <password>sa</password>
        </security>
    </xa-datasource>
</datasources>