• A bean deployment descriptor can describe several beans.
• The deployment descriptor file should describe all the beans which are to be packaged within the same jar file.
• The deployment descriptor file should be called "ejb-jar.xml".
• The ejb-jar.xml should be placed in the jar file's /META-INF root folder.
• Some application servers provide tools to generate the descriptor, some don't. The file can be created using a simple text file editor.
• The contents of the XML file are case sensitive.
• The deployment description file is really divided into two sections. The first describes the beans, specifying the home interface class, remote interface class etc... The second section is used to assign security and transaction details to the beans.

The first line of the file should be:

<?xml version="1.0" encoding="UTF-8" ?>

Next we can optionally specify the DTD (Document Type Definition) version.

<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN' 'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>

All the contents of the jar file are enclosed within an <ejb-jar>...</ejb-jar> pair of tags. The syntax is:

<!ELEMENT ejb-jar (description?, display-name?, small-icon?, large-icon?, enterprise-beans, assembly-descriptor?, ejb-client-jar?)>

Names ending with a '?' represent optional entries.

Enterprise Bean Descriptions

<enterprise-beans>...</enterprise-beans> start the EJB descriptions. The syntax for this tag is:

<!ELEMENT enterprise-beans (session | entity)+>

The above means that all beans are contained within the <enterprise-beans>...</enterprise-beans> tags.

• We can have many <session>...</session> and <entity>...</entity> tag pairs (each pair encloses one bean description).
• There must be at least one tag pair enclosed within the <enterprise-beans>...</enterprise-beans> tags.
• This article focusses on the <entity>...</entity> tags, because we are describing entity beans.

<entity>...</entity> starts the description of one entity bean. The syntax for this tag is:

<!ELEMENT entity (description?, display-name?, small-icon?, large-icon?, ejb-name, home, remote, ejb-class, persistence-type, prim-key-class, reentrant, cmp-field*, primkey-field?, env-entry*, ejb-ref*, security-role-ref*, resource-ref*)>

• Names ending with a '?' represent optional entries.
• Names ending with a '*' mean that there may be zero or more entries of this type.
• Some of the names are for container managed persistence, these are: cmp-field and primkey-field.

<description>...</description> tags are optional, but it's usually a good idea to put a brief description of what the bean ecapsulates. Any descriptive text can be placed between these tags. An application server might display this.

<display-name>...</display-name> is used to enter a name tipically used by EJB tools. This tag is optional.

Example:

<display-name>Person Entity Bean</display-name>

<ejb-name>...</ejb-name> encloses the name of the bean. The name should be a unique bean name contained within the jar file. The name is not meant to be the JNDI name used to instantiate the bean. It is aimed at uniquely identifying the bean within the XML deployer, so that other sections of the file can refer to the bean (such as when specifying security roles). The name should be a valid "NMTOKEN", that is to say that it should look like a programming identifier, which can contain a '.' character.

Example Names:

J3Beans.Person

Person

<home>...</home> tags specify the fully qualified bean home interface class.

For example:

<home>com.j3.PersonHome</home>

<remote>...</remote> tags specify the fully qualified bean remote interface class.

For example:

<remote>com.j3.Person</remote>

<persistence-type>Bean</persistence-type> for bean managed persistence

<persistence-type>Container</persistence-type> for container managed persistence

For example:

<prim-key-class>java.lang.Integer</prim-key-class>

or

<prim-key-class>com.j3.PersonPK</prim-key-class>

For example:

<reentrant>False</reentrant>

The syntax for the tag is:

<!ELEMENT env-entry (description?, env-entry-name, env-entry-type, env-entry-value?)>

• env-entry-name should be a valid JNDI name
• env-entry-type should be a fully qualified Java type of the environment entry value. Valid types are java.lang.Boolean, java.lang.Byte, java.lang.Double, java.lang.Float, java.lang.Long, java.lang.Short, java.lang.String
• env-entry-value this optional tag supplies the value of the environment property

  Example

  <env-entry>
  	<env-entry-name>male/retirementAge</env-entry-name>
  	<env-entry-type>java.lang.Integer</env-entry-type>
  	<env-entry-value>65</env-entry-value>
  </env-entry>

  In the entity bean's implementation class we could write the following code to get the environment value:

  ...
  Context ctx = new InitialContext();
  Context env = (Context) ctx.lookup("java:comp/env");
  Integer retiresAt = (Integer) env.lookup("male/retirementAge");
  ...

<ejb-ref>...</ejb-ref> tags are used to list all other enterprise Java beans this bean uses. They also provide the JNDI names this bean should use to create these other beans.

The syntax for the tag is:

<!ELEMENT ejb-ref (description?, ejb-ref-name, ejb-ref-type, home, remote, ejb-link?)>

• description is optional and allows the bean provider to supply some information about the referenced bean's use.
• ejb-ref-name is the environment name the bean should use to create the referenced bean using JNDI. It is recommended that the name be in the ejb subcontext (for example java:comp/env/ejb)
• ejb-ref-type should be Session or Entity, depending on the referenced bean type.
• home should be the fully qualified class of the referenced bean's home interface
• remote should be the fully qualified class of the referenced bean;s remote interface
• ejb-link is optional, and typically used in application jar files. It is the ejb-name of the referenced bean within this jar file, or within another jar file.

  Example:

  <ejb-ref>
  	<description>Used to get the person's employer</description>
  	<ejb-ref-name>ejb/Employer</ejb-ref-name>
  	<ejb-ref-type>Entity</ejb-ref-type>
  	<home>com.j3.EmployerHome</home>
  	<remote>com.j3.Employer</remote>
  </ejb-ref>

  The code to create the referenced bean's home (factory) could be written as follows:

  ...
  Context ctx = new InitialContext();
  Object beanObject = ctx.lookup("java:comp/env/ejb/Employer");
  EmployerHome employerFactory = (EmployerHome) 
  	javax.rmi.ProtableRemoteObject.narrow(beanObject,
  						EmployerHome.class);
  ...
  
  

<security-role-ref>...</security-role-ref> is used to specify security roles that the bean uses in its business methods. The use of security code within beans should be kept to a minimum. It is better to let the container apply security checks in a manner that is transparent to the bean.

<resource-ref>...</resource-ref> is used to specify which resources the bean uses. This is very important for entity beans, as it is used to specify which JDBC data sources is/are used.

This tag must be used to specify the following types of resources used by a bean:

• JDBC API data sources
• JMS connections
• JavaMail connections
• URL connections
• Additional resources as they are added to the EJB spec, such as Connector objects.

  The syntax for this tag is:

  <!ELEMENT resource-ref (desciption?, res-ref-name, res-type, res-auth)>

• description is an optional description of the resource.
• res-ref-name is the resource name string the bean uses to access the resource via JNDI. For example jdbc/BeanAppDB
• res-type is the fully qualified class name of the resource for example javax.sql.DataSource.
• res-auth specifies if the bean is responsible for writing the code to "log in" to the resource, or if the container supplies the resource already logged in to the bean. The valid values are:
  • Application: the bean is responsible for writing the code to "log in" to the resource
  • Container: the container supplies the resource already logged in to the bean

Assembly Descriptors

The assemlby descriptor allows security and transaction details to be assigned to beans. This section is optional. When writing EJB bean jar files, the security is most probably best left out. However, there are good reasons to make sure the transaction details are present for EJB BMP beans.

The EJB specification states that transaction details are manadatory, it just allows them to be defined in diferent ways and in diferent places. The bean provider will typically be aware of the transaction requirements of the business methods in the beans. Hence it makes sense to have the beans' deployment descriptor hold the transaction details.

The EJB specification states that the transaction attributes must be specified for all the methods in the home and remote interfaces, including their superinterfaces. Some methods are listed as exceptions. In effect, the deployment descriptor should list all the methods in the bean's home and remote interface, as well as the remove() methods defined in EJBHome and EJBObject.

<assembly-descriptor>...</assembly-descriptor> this tag starts the assembly descriptor for the deployment file.

The syntax for the tag is:

<!ELEMENT assembly-descriptor (security-role*, method-permission*, container-transaction*)>

<container-transaction>...</container-transaction> Each tag represents a particular transaction type. All methods which use use a given transaction type can be listed for one of these tag. Or multiple container-transaction tags can be used, one per method.

The syntax for the tag is:

<!ELEMENT container-transaction (description?, method+, trans-attribute>

• The description is optional
• One or more methods must be specified
• The trans-attribute specifies the transaction type.

<method>...</method> tag is used to denote a method in an enterprise bean's home or remote interface. There are many ways of using this tag. A description of the ways the tag can be used follows.

The syntax for the tag is:

<!ELEMENT method (description, ejb-name, method-intf?, method-name, method-params?)>

• ejb-name is the bean name, as defined for one the the beans within the enterprise-beans tag of the this deployment descriptor file.
• method-intf is used to specify if the method is in a remote interface or a home interface (should the bean use the same method name in both interfaces). If method-intf is left out, the method tag can refer to both interfaces. Possible values for this tag are:
  • <method-intf>Home</method-intf>
  • <method-intf>Remote</method-intf>
• method-name is used to identify one or more methods in the bean's interfaces. There are three possible styles for this tag:
  1. <method-name>*</method-name> refers to all the methods in the bean's home and/or remote interfaces of the bean.
  2. <method-name>METHOD</method-name> where METHOD is the name of the bean method you wish to refer to. This style refers to the all the methods with the given METHOD name. This is handy when referring to the Create() methods, which can be overloaded with different parameter lists: just one <method-name> can refer to all of the create methods in a bean's interface.
  3. The third style uses the method name along with the <method-params> tag to identify a single method within the bean.
• <method-params>...<method-params> is an optional tag used to describe a given method's parameter signature. Thi stag is described below.

<method-params>...</method-params> is used to specify a method's parameter signature.

The syntax for the tag is:

<!ELEMENT method-params (method-param*)>

• method-param is used to specify the fully qualified parameter class name.

Example:

if the method signature is void myMethod(String param1, int param2, MyClassName[][] param3), we would write:

<method-params>
	<method-param>java.lang.String</method-param>
	<method-param>int</method-param>
	<method-param>myPackageName.MyClassName[][]</method-param>
</method-params>

<trans-attribute>...</trans-attribute> is used to specify which transaction type the container should use for the methods listed. See method to learn how the trans-attribute and method tags are used together.

The syntax for the tag is:

<!ELEMENT trans-attribute (#PCDATA)>

#PCDATA is one of:

• NotSupported The container does not supply a transaction context to the method(s), not even if the client has one.
• Supports The container passes on the client's transaction context if it has one, otherwise the container passes no transaction context.
• Required If the client has a transaction context, the container passes it, otherwise:
  • the container creates a new transaction, starts it, calls the method, commits the transaction, returns to the client
• RequiresNew The container suspends any transaction associated with the current thread, creates a new transaction, invokes the method, commits the transaction, resumes any transaction suspended then returns to the client.
• Mandatory the client must have a transaction context when calling the method. If none is there, the container throws javax.transaction.TransactionRequiredException.
• Never The client must make sure it has no transaction context. If the client the method calls with a transaction context, the container throws java.rmi.RemoteException.