The deployment descriptor

This is an XML file and you can open it in Internet Explorer (as of this writing, Netscape Navigator does not have XML display built-in) and examine its structure.  You will notice that this is a tree-like structure, with nodes containing branches.

The top level node is named "ejb-jar".   Underneath it, there is a brief textual "description" node, and another node called "enterprise-beans".  The "enterprise-beans" node further contains a "session" and/or "entity" nodes, depending upon what kind of EJBs are present.  (Multiple EJBs may be included in a single Jar file.)

If you drill down in the tree further, you will notice that "session" or "entity" nodes contain the name of the EJB, fully qualified names of the home and remote classes, and the ejb-class (the implementation class for the remote interface.)  For entity beans, the primary class is also specified, and a node specifies that "persistence-type" is "Container".   Normally, for an entity bean, the "persistence" is managed automatically by the container.  If you wish to load and unload the bean data yourself, you can set persistence-type to user and write the body of the ejbLoad and ejbStore functions to load and store the data.

There are some nodes called "cmp-fields".  The "cmp" stands for "container managed persistence", so these are only needed if the persistence-type is container.  There should be a "cmp-field" for each field of the EJB that is to be managed by the container.

Most of the other things should be relatively obvious.  Note the "level" of the nodes.  In the next few chapters, we will be talking about the "level" of a node and adding items "below" or "at the same level as" it.  Or alternatively, some nodes being "children" of some other node and some nodes being "siblings".

For instance, at the same level as the "enterprise-beans" node, another node can be added, called "assembly-descriptor".  This means the XML will look like:

<ejb-jar>
<enterprise-beans>
    .... details of enterprise beans...
</enterprise-beans>
<assembly-descriptor>
    ... details of assembly descriptor
</assembly-descriptor>
</ejb-jar>

Note that the "assembly-descriptor" goes after the end of "enterprise-beans", but before the end of the parent node "ejb-jar".  Here "assembly-descriptor" is a sibling of "enterprise-beans" node and "ejb-jar" is the parent of both.

As another example, the "env-entry" and "ejb-refs" nodes go "below" the "session" node, at the same level but after "transaction-type" node.  So this might look like:

<session>
....
<transaction-type>Container</transaction-type>
<env-entry>
... details of env-entry ...
</env-entry>
<ejb-refs>
... details of ejb-refs ...
</ejb-refs>
</session>

Notice that the env-entry and ejb-refs node go before "session" node has been closed, making them go "below" or "as children of" the session node.  But they go after the "transaction-type" node has been closed, making them "at the same level at" or "as siblings" of the "transaction-type" node.

The full syntax of the deployment descriptor has a lot of detail.  The goal in this tutorial is not to provide a reference for the deployment descriptor (you can find the reference in other places) but to familiarize you with its structure and usages so you will be easily able to make sense of reference documents.

Exercise:  Familiarize yourself with the deployment descriptors of all the EJBs we have created.  In the next lessons, we will be making changes to these deployment descriptors.