Deployment Overlays: A new feature of the JBoss EAP 6.1

| Heinz Wilming

The Java EE platform provides a component-based architecture, which supports modular concepts to develop applications and reuse components in different applications and environments. Dependencies to the application server specific environment can be defined in deployment descriptors, such as ejb-jar.xml for EJB components.

A simple example of a portable resource injection of a JMS connection factory object:

@Stateless
public class MyEjbComponent {

   @Ressource(name="JMSConnectionFactory")
   private ConnectionFactory connectionFactory;

   …
}

The following descriptor linked the resource reference to the JNDI name outside the application code.

<ejb-jar>
   <enterprise-beans>
      <session>
         <ejb-name>MyEjbComponent</ejb-name>
         <resource-ref>
            <res-ref-name>JMSConnectionFactory</res-ref-name>
            <lookup-name>java:/ConnectionFactory</lookup-name>
         </resource-ref>
      </session>
   </enterprise-beans>
</ejb-jar>

According to the Java EE specification the responsiblility of the deployer is to bind the resource references to the actual resource factories configured in the target environment. The configuration in deployment descriptors decouples the implementations of vendor specific and environment specific configurations. But it is still necessary to modify the deployment archive.

To avoid modifications of the deployment archive, the JBoss Enterprise Application Platform supports with the version 6.1 deployment overlays. This feature allows the developer to override deployment descriptor, static resources, and adding libraries to the deployment without modifications.

Deployment overlay can be created with the Command Line Interface of the application server. The following example shows the commands to define overlay content for a deployment.

[standalone@localhost:9999 /] deployment-overlay add --name=jms-example-overlay --content=/META-INF/ejb-jar.xml=/overlayed-ejb-jar.xml --deployments=jms-example.jar

[standalone@localhost:9999 /] deploy /jms-example.jar

After the deployment of the jms-example.jar archive, the ejb-jar.xml deployment descriptor will be shaded by the overlayed-ejb-jar.xml descriptor.