# JBoss EJB 3.0 partial deployment descriptors

EJB 3.0 allows for partial deployment descriptors to augment or override the behavior of source code annotations. This chapter 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 DTD 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.

## Examples

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

### Complete deployment descriptor

The following ejb-jar.xml file contains a complete specification for a series of EJBs, including tags for security, transactions, resource injection, references, callbacks, callback listeners, interceptors, etc.

    <ejb-jar>
       <description>jBoss test application </description>
       <display-name>Test</display-name>
       <enterprise-beans>
          <session>
             <ejb-name>Teller</ejb-name>
             <remote>org.jboss.ejb3.test.bank.Teller</remote>
             <ejb-class>org.jboss.ejb3.test.bank.TellerBean</ejb-class>
             <session-type>Stateless</session-type>
             <transaction-type>Container</transaction-type>
             <ejb-ref>
                <ejb-ref-name>ejb/Bank</ejb-ref-name>
                <ejb-ref-type>Session</ejb-ref-type>
                <remote>org.jboss.ejb3.test.bank.Bank</remote>
                <ejb-link>Bank</ejb-link>
                <injection-target>bank</injection-target>
             </ejb-ref>
             <resource-ref>
                 <res-ref-name>java:/TransactionManager</res-ref-name>
                 <res-type>javax.transaction.TransactionManager</res-type>
                 <res-auth>Container</res-auth>
                 <res-sharing-scope>Shareable</res-sharing-scope>
                 <injection-target>setTransactionManager</injection-target>
             </resource-ref>
             <resource-ref>
                 <res-ref-name></res-ref-name>
                 <res-type>javax.ejb.TimerService</res-type>
                 <res-auth>Container</res-auth>
                 <res-sharing-scope>Shareable</res-sharing-scope>
                 <injection-target>ts</injection-target>
             </resource-ref>
             <security-identity>
                <run-as>
                   <role-name>bankTeller</role-name>
                </run-as>
             </security-identity>
          </session>
          <session>
             <ejb-name>Bank</ejb-name>
             <remote>org.jboss.ejb3.test.bank.Bank</remote>
             <ejb-class>org.jboss.ejb3.test.bank.BankBean</ejb-class>
             <session-type>Stateful</session-type>
             <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>java: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>customerDb</injection-target>
             </resource-ref>
             <interceptor>org.jboss.ejb3.test.bank.FirstInterceptor</interceptor>
             <interceptor>org.jboss.ejb3.test.bank.SecondInterceptor</interceptor>
             <callback-listener>org.jboss.ejb3.test.bank.ExternalCallbackListener</callback-listener>
          </session>
       </enterprise-beans>
       <assembly-descriptor>
          <callback>
             <annotation>PostConstruct</annotation>
             <method>
                <ejb-name>Teller</ejb-name>
                <method-name>postConstruct</method-name>
             </method>
          </callback>
          <remove-list>
             <method>
                <ejb-name>Bank</ejb-name>
                <method-name>remove</method-name>
             </method>
          </remove-list>
          <init-list>
             <method>
                <ejb-name>Bank</ejb-name>
                <method-name>init</method-name>
             </method>
          </init-list>
          <security-role>
             <role-name>bankCustomer</role-name>
          </security-role>
          <security-role>
             <role-name>bankTeller</role-name>
          </security-role>
          <method-permission>
             <role-name>bankCustomer</role-name>
             <method>
                <ejb-name>Teller</ejb-name>
                <method-name>greetChecked</method-name>
             </method>
          </method-permission>
          <method-permission>
             <unchecked/>
             <method>
                <ejb-name>Teller</ejb-name>
                <method-name>greetUnchecked</method-name>
             </method>
          </method-permission>
          <method-permission>
             <role-name>bankTeller</role-name>
             <method>
                <ejb-name>Bank</ejb-name>
                <method-name>getCustomerId</method-name>
             </method>
             <method>
                <ejb-name>Bank</ejb-name>
                <method-name>storeCustomerId</method-name>
             </method>
          </method-permission>
          <container-transaction>
             <method>
                <ejb-name>Teller</ejb-name>
                <method-name>greetWithNotSupportedTransaction</method-name>
             </method>
             <trans-attribute>NotSupported</trans-attribute>
          </container-transaction>
          <container-transaction>
             <method>
                <ejb-name>Teller</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>
          <container-transaction>
             <method>
                <ejb-name>Bank</ejb-name>
                <method-name>*</method-name>
             </method>
             <trans-attribute>Required</trans-attribute>
          </container-transaction>
          <exclude-list>
             <method>
                <ejb-name>Teller</ejb-name>
                <method-name>excludedMethod</method-name>
             </method>
          </exclude-list>
       </assembly-descriptor>
    </ejb-jar>

### Security

The following `ejb-jar.xml` file overrides any `@RolesAllowed`, `@PermitAll`, or `@DenyAll` source code annotations for the `bar` method of the `FooB` EJB and adds a `@RolesAllowed` annotation for the `allowed` role.

    <ejb-jar>
       <assembly-descriptor>
          <method-permission>
             <role-name>allowed</role-name>
             <method>
                <ejb-name>FooB</ejb-name>
                <method-name>bar</method-name>
             </method>
         </method-permission>
       </assembly-descriptor>
    </ejb-jar>

### Transactions

The following `ejb-jar.xml` file overrides any `@TransactionAttribute` annotations for the `bar` method of the `FooA` EJB and adds a `@TransactionAttribute` annotation for `NOT SUPPORTED`.

    <ejb-jar>
       <assembly-descriptor>
          <container-transaction>
             <method>
                <ejb-name>FooA</ejb-name>
                <method-name>bar</method-name>
             </method>
             <trans-attribute>NotSupported</trans-attribute>
          </container-transaction>
       </assembly-descriptor>
    </ejb-jar>

### References

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

    <ejb-jar>
       <enterprise-beans>
          <session>
             <ejb-name>Teller</ejb-name>
             <ejb-ref>
                <ejb-ref-name>ejb/Bank</ejb-ref-name>
                <ejb-ref-type>Session</ejb-ref-type>
                <remote>org.jboss.ejb3.test.bank.Bank</remote>
                <ejb-link>Bank</ejb-link>
    	    <injection-target>bank</injection-target>
             </ejb-ref>
          </session>
       </enterprise-beans>
    </ejb-jar>

### Callbacks

The following `ejb-jar.xml` file adds a `@PostConstruct` annotation to the `postConstruct` method of the `Teller` EJB.

    <ejb-jar>
       <assembly-descriptor>
          <callback>
             <annotation>PostConstruct</annotation>
             <method>
                <ejb-name>Teller</ejb-name>
                <method-name>postConstruct</method-name>
             </method>
          </callback>
       </assembly-descriptor>
    </ejb-jar>