JBoss.org Community Documentation

Chapter 37. Partial Deployment Descriptors

EJB 3.0 allows for partial deployment descriptors to augment or override the behavior of source code annotations. This tutorial describes the use of partial deployment descriptors.

Overview :

Beans in EJB 3.0 can be specified via source code annotations and/or a deployment descriptor. The deployment descriptor is used to augment or override the source code annotations. There are some limitations on which annotations may be overridden, however. The annotations that specify the bean itself (e.g. @Stateless, @Stateful, @MessageDriven, @Service, @Consumer) cannot be overridden. The EJB 3.0 ejb-jar.xml deployment descriptor xsd specifies the majority of tags as optional in order to support annotation augmentation and overrides. The deployment descriptor does not need to specify all of the required information, just that additional information to override or augment the source code annotations.

Example :

This section contains examples of complete and partial deployment descriptors for completely specifying or overriding specific behaviors of EJBs.

Complete deployment descriptor :

Take a look at the META-INF/ejb-jar.xml. The ejb-jar.xml in this tutorial configures the CompleteXMLDD bean only through the deployment descriptor. The PartialXMLDD bean is configured through the deployment descriptor as well as through annotations. 

					
<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar
        xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
                            http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
        version="3.0">
	<description>Partial deployment descriptors for EJB in JBoss</description>
   	<display-name>Partial deployment descriptors</display-name>
   	<enterprise-beans>
      <session>
         <ejb-name>CompleteXMLDD</ejb-name>
         <business-remote>org.jboss.tutorial.partial_deployment_descriptor.bean.CompleteXMLDD</business-remote>
         <ejb-class>org.jboss.tutorial.partial_deployment_descriptor.bean.CompleteXMLDDBean</ejb-class>
         <session-type>Stateless</session-type>
         <transaction-type>Container</transaction-type>
         <ejb-ref>
            <ejb-ref-name>ejb/PartialXMLDD</ejb-ref-name>
            <ejb-ref-type>Session</ejb-ref-type>
            <mapped-name>PartialXMLDD/remote</mapped-name>
            <injection-target>
             	<injection-target-class>org.jboss.tutorial.partial_deployment_descriptor.bean.CompleteXMLDDBean</injection-target-class>
             	<injection-target-name>partialXMLDDBean</injection-target-name>
             </injection-target>
         </ejb-ref>
         <resource-ref>
             <res-ref-name>TimerService</res-ref-name>
             <res-type>javax.ejb.TimerService</res-type>
             <res-auth>Container</res-auth>
             <res-sharing-scope>Shareable</res-sharing-scope>
             <injection-target>
             	<injection-target-class>org.jboss.tutorial.partial_deployment_descriptor.bean.CompleteXMLDDBean</injection-target-class>
             	<injection-target-name>timerService</injection-target-name>
             </injection-target>
         </resource-ref>
         <post-construct>
         	<lifecycle-callback-class>org.jboss.tutorial.partial_deployment_descriptor.bean.ExternalCallbackListener</lifecycle-callback-class>
         	<lifecycle-callback-method>postConstruct</lifecycle-callback-method>
         </post-construct>

         <security-identity>
            <run-as>
               <role-name>admin</role-name>
            </run-as>
         </security-identity>
      </session>
      <session>
         <ejb-name>PartialXMLDD</ejb-name>
         <business-remote>org.jboss.tutorial.partial_deployment_descriptor.bean.PartialXMLDD</business-remote>
         <ejb-class>org.jboss.tutorial.partial_deployment_descriptor.bean.PartialXMLDDBean</ejb-class>
         <session-type>Stateful</session-type>
         <init-method>
         	<create-method>
         		<method-name>create</method-name>
         	</create-method>
         	<bean-method>
         		<method-name>init</method-name>
         	</bean-method>
         </init-method>
         <remove-method>
         	<bean-method>
         		<method-name>remove</method-name>
         	</bean-method>
         </remove-method>
         <transaction-type>Container</transaction-type>

         <env-entry>
            <env-entry-name>id</env-entry-name>
            <env-entry-type>java.lang.String</env-entry-type>
            <env-entry-value>5678</env-entry-value>
         </env-entry>
         <resource-ref>
            <res-ref-name>DefaultDS</res-ref-name>
            <res-type>javax.sql.DataSource</res-type>
            <res-auth>Container</res-auth>
            <res-sharing-scope>Shareable</res-sharing-scope>
            <injection-target>
            	<injection-target-class>org.jboss.tutorial.partial_deployment_descriptor.bean.PartialXMLDDBean</injection-target-class>
            	<injection-target-name>ds</injection-target-name>
            </injection-target>
         </resource-ref>
      </session>
   </enterprise-beans>
   <interceptors>
   	<interceptor>
   		<interceptor-class>org.jboss.tutorial.partial_deployment_descriptor.bean.FirstInterceptor</interceptor-class>
   		<around-invoke>
   			<method-name>interceptorMethod</method-name>
   		</around-invoke>
   	</interceptor>
   	<interceptor>
   		<interceptor-class>org.jboss.tutorial.partial_deployment_descriptor.bean.SecondInterceptor</interceptor-class>
   	</interceptor>
   </interceptors>
   <assembly-descriptor>
   	  <security-role>
         <role-name>admin</role-name>
      </security-role>
      <security-role>
         <role-name>normal</role-name>
      </security-role>
      <method-permission>
         <role-name>normal</role-name>
         <method>
            <ejb-name>CompleteXMLDD</ejb-name>
            <method-name>sayHello</method-name>
         </method>
      </method-permission>
      <method-permission>
         <unchecked/>
         <method>
            <ejb-name>CompleteXMLDD</ejb-name>
            <method-name>sayBye</method-name>
         </method>
      </method-permission>
      <method-permission>
         <role-name>admin</role-name>
         <method>
            <ejb-name>PartialXMLDD</ejb-name>
            <method-name>echoMessage</method-name>
         </method>
         <method>
            <ejb-name>PartialXMLDD</ejb-name>
            <method-name>changeMessage</method-name>
         </method>
      </method-permission>
      <container-transaction>
         <method>
            <ejb-name>CompleteXMLDD</ejb-name>
            <method-name>greetWithNotSupportedTransaction</method-name>
         </method>
         <trans-attribute>NotSupported</trans-attribute>
      </container-transaction>
      <container-transaction>
         <method>
            <ejb-name>CompleteXMLDD</ejb-name>
            <method-name>greetWithRequiredTransaction</method-name>
            <method-params>
               <method-param>java.lang.String</method-param>
            </method-params>
         </method>
         <trans-attribute>Required</trans-attribute>
      </container-transaction>
      <interceptor-binding>
      	<ejb-name>CompleteXMLDD</ejb-name>
      	<interceptor-class>org.jboss.tutorial.partial_deployment_descriptor.bean.FirstInterceptor</interceptor-class>
      	<interceptor-class>org.jboss.tutorial.partial_deployment_descriptor.bean.SecondInterceptor</interceptor-class>
   	  </interceptor-binding>
      <exclude-list>
         <method>
            <ejb-name>CompleteXMLDD</ejb-name>
            <method-name>uncallableMethod</method-name>
         </method>
      </exclude-list>

   </assembly-descriptor>

</ejb-jar>

Transactions :

The following ejb-jar.xml file overrides any @TransactionAttribute annotations for the greetWithNotSupportedTransaction method of the CompleteXMLDD bean and adds a @TransactionAttribute annotation for NOT SUPPORTED. 

            	
@TransactionAttribute (TransactionAttributeType.REQUIRES_NEW)
public String greetWithNotSupportedTransaction(String name)
{

...
<container-transaction>
   <method>
      <ejb-name>CompleteXMLDD</ejb-name>
      <method-name>greetWithNotSupportedTransaction</method-name>
   </method>
   <trans-attribute>NotSupported</trans-attribute>
</container-transaction>
...

References :

The following ejb-jar.xml file creates a EJB reference and injects the EJB to the injection target of the partialXMLDDBean member variable. 

<ejb-name>CompleteXMLDD</ejb-name>
...
<ejb-ref>
   <ejb-ref-name>ejb/PartialXMLDD</ejb-ref-name>
   <ejb-ref-type>Session</ejb-ref-type>
   <mapped-name>PartialXMLDD/remote</mapped-name>
   <injection-target>
    	<injection-target-class>org.jboss.tutorial.partial_deployment_descriptor.bean.CompleteXMLDDBean</injection-target-class>
    	<injection-target-name>partialXMLDDBean</injection-target-name>
    </injection-target>
</ejb-ref>
...

Callbacks :

The following ejb-jar.xml file adds a @PostConstruct annotation to the postConstruct method of the CompleteXMLDD bean. 

            	
<ejb-name>CompleteXMLDD</ejb-name>
...
<post-construct>
	<lifecycle-callback-class>org.jboss.tutorial.partial_deployment_descriptor.bean.ExternalCallbackListener</lifecycle-callback-class>
	<lifecycle-callback-method>postConstruct</lifecycle-callback-method>
</post-construct>
...

Building and Running

Note

To build and run the example, make sure you have installed JBoss 5.x. See the Section 1.1, “JBoss Application Server 5.x” for details.

From the command prompt, move to the "partial_deployment_descriptor" folder under the Section 1.3, “Set the EJB3_TUTORIAL_HOME”

Ant Users:

Make sure your JBossAS-5.x is running 

			
$ ant
$ ant run

run:
     [java] jai is a normal user
     [java] Hello, jai. I am the CompleteXMLDDBean. I have the following resources with me:
     [java] Timer Service : org.jboss.ejb3.timerservice.jboss.TimerServiceFacade@184a6b9
     [java] PartialXMLDD Bean : Proxy to jboss.j2ee:jar=jboss-ejb3-tutorial-partial_deployment_descriptor.jar,name=PartialXMLDD,service=EJB3 implementing [interface org.jboss.ejb3.proxy.intf.EjbProxy, interface org.jboss.tutorial.partial_deployment_descriptor.bean.PartialXMLDD, interface org.jboss.ejb3.proxy.intf.StatefulSessionProxy, interface org.jboss.ejb3.proxy.intf.SessionProxy]
     [java]
     [java] Welcome jai, you are in a method with no transaction supported
     [java] Welcome jai, you are in a method with a REQUIRED transaction
     [java] Bye, jai. Hope to see you again
     [java] We'll try calling an uncallable method
     [java] Caught expected exception : Caller unauthorized
     [java] bill is an admin
     [java] Sending Hello World message to bean. We expect the bean to change it
     [java] This message has been changed
     [java] Now calling echo message
     [java] Hello World
     [java] We are done with the bean, let's remove it
     [java] Bean removed

Maven Users: Make sure the AS is not running. 

$ mvn clean install -PRunSingleTutorial