# 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
5. Tips

## Principles

The bean programmer is responsible for providing the deployment descriptor associated to the developed Enterprise Beans. As one goes along the different steps of the application development and deployment life cycle of the Enterprise JavaBeans, (development, assembly, deployment), the deployment descriptor has to be completed.

The Bean Provider's responsibilities and the Application Assembler's responsibilities is to provide a XML deployment descriptor respecting the deployment descriptor's XML DTD defined in the EBJ specification version 2.0. (See `$JONAS_ROOT/xml/ejb-jar_2_0.dtd`).

To be able to deploy Enterprise JavaBeans on the EJB server, information not defined in the standard XML deployment descriptor are needed. Such information includes for example the mapping of the bean to the underlying database for entity bean with container-managed persistence. This information is specified, during the deployment step, in another XML deployment descriptor which is specific to JOnAS. The JOnAS specific deployment descriptor's XML DTD can be found in `$JONAS_ROOT/xml/jonas-ejb-jar_X_Y.dtd`. The file's name of the JOnAS specific XML deployment descriptor must be the file's name of the standard XML deployment descriptor prefixed by '`jonas-`'.

The JOnAS interpretation of the <!DOCTYPE> tag is particular, at the parsing of the deployment descriptor XML files.
The parser try, first, to get the specified DTD via the classpath, and then via the specified URL (or path).

Examples: in these two following examples, the parser get the `jonas-ejb-jar_2_4.dtd` DTD file in the JOnAS jar file

        <!DOCTYPE jonas-ejb-jar PUBLIC "-//ObjectWeb//DTD JOnAS 2.4//EN" "http://www.objectweb.org/jonas/dtds/jonas-ejb-jar_2_4.dtd">
        <!DOCTYPE jonas-ejb-jar SYSTEM "/usr/local/jonas/xml/jonas-ejb-jar_2_4.dtd">

The standard deployment descriptor should contain structural information for each enterprise bean including:

- Enterprise bean's name,
- Enterprise bean's class,
- Enterprise bean's home interface,
- Enterprise bean's remote interface,
- Enterprise bean's type,
- re-entrancy indication for entity bean,
- session bean's state management type,
- session bean's transaction demarcation type,
- entity bean's persistence management,
- entity bean's primary key class,
- container-managed fields,
- environment entries,
- bean's EJB references,
- resource manager connection factory references,
- transaction attributes.

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

- the JNDI name of the Home object that implement the Home interface of the enterprise bean,
- the JNDI name of the DataSource object corresponding to the resource manager connection factory referenced in the enterprise bean's class,
- the JNDI name of each EJB references,
- the JNDI name of JMS administered objects,
- information of the mapping of the bean to the underlying database in case of an entity with container-managed persistence.

## Example of Session Descriptors

    <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://java.sun.com/dtd/ejb-jar_2_0.dtd">
    <ejb-jar>
      <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>

    <!DOCTYPE jonas-ejb-jar PUBLIC "-//ObjectWeb//DTD JOnAS 2.4//EN" "http://www.objectweb.org/jonas/dtds/jonas-ejb-jar_2_4.dtd">
    <jonas-ejb-jar>
      <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)

    <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN" "http://java.sun.com/dtd/ejb-jar_2_0.dtd">
    <ejb-jar>
      <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>
          <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>

    <!DOCTYPE jonas-ejb-jar PUBLIC "-//ObjectWeb//DTD JOnAS 2.4//EN" "http://www.objectweb.org/jonas/dtds/jonas-ejb-jar_2_4.dtd">
    <jonas-ejb-jar>
      <jonas-entity>
        <ejb-name>ExampleTwo</ejb-name>
        <jndi-name>ExampleTwoHome</jndi-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

Some characters, such "<" and "&" are strictly illegal in the XML data.
Others, such ">", are legal, but it is a good habit to replace them by XML entity references.

Here is the list of the predefined entity references in XML:

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