EJB Programmer's Guide: Defining the Deployment Descriptor

Target Audience and Content

The target audience for this guide is the Enterprise Bean provider, i.e. the person in charge of developing the software components on the server side. It describes how the bean provider should build the deployment descriptors of its components.

The content of this guide is the following:

  1. Target Audience and Content
  2. Principles
  3. Example of Session Descriptors
  4. Example of Container-managed Persistence Entity Descriptors (CMP1.1)
  5. Tips

Principles

The bean programmer is responsible for providing the deployment descriptor associated with the developed Enterprise Beans. The Bean Provider's responsibilities and the Application Assembler's responsibilities is to provide an XML deployment descriptor that conforms to the deployment descriptor's XML schema as defined in the EBJ specification version 2.1. (Refer to $JONAS_ROOT/xml/ejb-jar_2_1.xsd or  http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd).

To deploy Enterprise JavaBeans on the EJB server, information not defined in the standard XML deployment descriptor may be needed. For example, this information may include the mapping of the bean to the underlying database for an entity bean with container-managed persistence. This information is specified during the deployment step in another XML deployment descriptor that is specific to JOnAS. The JOnAS-specific deployment descriptor's XML schema is located in $JONAS_ROOT/xml/jonas-ejb-jar_X_Y.xsd. The file name of the JOnAS-specific XML deployment descriptor must be the file name of the standard XML deployment descriptor prefixed by 'jonas-'.

The parser gets the specified schema via the classpath (schemas are packaged in the $JONAS_ROOT/lib/common/ow_jonas.jar file).

The standard deployment descriptor should contain structural information for each enterprise bean that includes the following:

The JOnAS-specific deployment descriptor contains information for each enterprise bean including:

Example of Session Descriptors

<?xml version="1.0" encoding="ISO-8859-1"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"
         version="2.1">
  <description>Here is the description of the test's beans</description>
  <enterprise-beans>
    <session>
      <description>... Bean example one ...</description>
      <display-name>Bean example one</display-name>
      <ejb-name>ExampleOne</ejb-name>
      <home>tests.Ex1Home</home>
      <remote>tests.Ex1</remote>
      <ejb-class>tests.Ex1Bean</ejb-class>
      <session-type>Stateful</session-type>
      <transaction-type>Container</transaction-type>
      <env-entry>
        <env-entry-name>name1</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>value1</env-entry-value>
      </env-entry>
      <ejb-ref>
        <ejb-ref-name>ejb/ses1</ejb-ref-name>
        <ejb-ref-type>session</ejb-ref-type>
        <home>tests.SS1Home</home>
        <remote>tests.SS1</remote>
      </ejb-ref>
      <resource-ref>
        <res-ref-name>jdbc/mydb</res-ref-name>
        <res-type>javax.sql.DataSource</res-type>
        <res-auth>Application</res-auth>
      </resource-ref>
    </session>
  </enterprise-beans>
  <assembly-descriptor>
    <container-transaction>
      <method>
        <ejb-name>ExampleOne</ejb-name>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Required</trans-attribute>
    </container-transaction>
    <container-transaction>
      <method>
        <ejb-name>ExampleOne</ejb-name>
        <method-inter>Home</ejb-name>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Supports</trans-attribute>
    </container-transaction>
    <container-transaction>
      <method>
        <ejb-name>ExampleOne</ejb-name>
        <method-name>methodOne</method-name>
      </method>
      <trans-attribute>NotSupported</trans-attribute>
    </container-transaction>
    <container-transaction>
      <method>
        <ejb-name>ExampleOne</ejb-name>
        <method-name>methodTwo</method-name>
        <method-params><method-param>int</method-param></method-params>
      </method>
      <trans-attribute>Mandatory</trans-attribute>
    </container-transaction>
    <container-transaction>
      <method>
        <ejb-name>ExampleOne</ejb-name>
        <method-name>methodTwo</method-name>
        <method-params><method-param>java.lang.String</method-param></method-params>
      </method>
      <trans-attribute>NotSupported</trans-attribute>
    </container-transaction>
  </assembly-descriptor>
</ejb-jar>


<?xml version="1.0" encoding="ISO-8859-1"?>
<jonas-ejb-jar xmlns="http://www.objectweb.org/jonas/ns"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.objectweb.org/jonas/ns
               http://www.objectweb.org/jonas/ns/jonas-ejb-jar_4_0.xsd" >
  <jonas-session>
    <ejb-name>ExampleOne</ejb-name>
    <jndi-name>ExampleOneHome</jndi-name>
    <jonas-ejb-ref>
      <ejb-ref-name>ejb/ses1</ejb-ref-name>
      <jndi-name>SS1Home_one</jndi-name>
    </jonas-ejb-ref>
    <jonas-resource>
      <res-ref-name>jdbc/mydb</res-ref-name>
      <jndi-name>jdbc_1</jndi-name>
    </jonas-resource>
  </jonas-session>
</jonas-ejb-jar>
    

Example of Container-managed Persistence Entity Descriptors (CMP 1.1)

<?xml version="1.0" encoding="ISO-8859-1"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
         http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"
         version="2.1">
         
  <description>Here is the description of the test's beans</description>
  <enterprise-beans>
    <entity>
      <description>... Bean example one ...</description>
      <display-name>Bean example two</display-name>
      <ejb-name>ExampleTwo</ejb-name>
      <home>tests.Ex2Home</home>
      <remote>tests.Ex2</remote>
      <local-home>tests.Ex2LocalHome</local-home>
      <local>tests.Ex2Local</local>
      <ejb-class>tests.Ex2Bean</ejb-class>
      <persistence-type>Container</persistence-type>
      <prim-key-class>tests.Ex2PK</prim-key-class>
      <reentrant>False</reentrant>
      <cmp-version>1.x</cmp-version>
      <cmp-field>
        <field-name>field1</field-name>
      </cmp-field>
      <cmp-field>
        <field-name>field2</field-name>
      </cmp-field>
      <cmp-field>
        <field-name>field3</field-name>
      </cmp-field>
      <primkey-field>field3</primkey-field>
      <env-entry>
        <env-entry-name>name1</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>value1</env-entry-value>
      </env-entry>
    </entity>
  </enterprise-beans>
  <assembly-descriptor>
    <container-transaction>
      <method>
        <ejb-name>ExampleTwo</ejb-name>
        <method-name>*</method-name>
      </method>
      <trans-attribute>Supports</trans-attribute>
    </container-transaction>
  </assembly-descriptor>
</ejb-jar>


<?xml version="1.0" encoding="ISO-8859-1"?>
<jonas-ejb-jar xmlns="http://www.objectweb.org/jonas/ns"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.objectweb.org/jonas/ns
               http://www.objectweb.org/jonas/ns/jonas-ejb-jar_4_0.xsd" >
  <jonas-entity>
    <ejb-name>ExampleTwo</ejb-name>
    <jndi-name>ExampleTwoHome</jndi-name>
    <jndi-local-name>ExampleTwoLocalHome</jndi-local-name>
    <jdbc-mapping>
      <jndi-name>jdbc_1</jndi-name>
      <jdbc-table-name>YourTable</jdbc-table-name>
      <cmp-field-jdbc-mapping>
        <field-name>field1</field-name>
        <jdbc-field-name>dbf1</jdbc-field-name>
      </cmp-field-jdbc-mapping>
      <cmp-field-jdbc-mapping>
        <field-name>field2</field-name>
        <jdbc-field-name>dbf2</jdbc-field-name>
      </cmp-field-jdbc-mapping>
      <cmp-field-jdbc-mapping>
        <field-name>field3</field-name>
        <jdbc-field-name>dbf3</jdbc-field-name>
      </cmp-field-jdbc-mapping>
      <finder-method-jdbc-mapping>
        <jonas-method>
          <method-name>findByField1</method-name>
        </jonas-method>
        <jdbc-where-clause>where dbf1 = ?</jdbc-where-clause>
      </finder-method-jdbc-mapping>
    </jdbc-mapping>
  </jonas-entity>
</jonas-ejb-jar>
    

Tips

Although some characters, such as ">", are legal, it is good practice to replace them with XML entity references.

The following is a list of the predefined entity references for XML:

&lt; < less than
&gt; > greater than
&amp; & ampersand
&apos; ' apostrophe
&quot; " quotation mark