EJB Deployment Descriptors

Before we can attempt to deploy our bean, we have to create a set of deployment descriptors that essentially describe the bean to the container and identify several deployment-time properties. An individual playing the role of a deployer in the application context typically manages these files. The descriptors tell the container how to manage the bean at runtime. Think of the deployment descriptor as a property file that's used by several standalone applications. The advantage of these files is that the code and the runtime properties of an application are clearly demarcated, which enables us to change the runtime properties without rebuilding the application. Deployment descriptors also play a similar role in the world of EJBs.

Some of the information that the descriptors tell the container includes the JNDI name where the bean will be looked up, security, transactional context, and so on. As is obvious from the previous sections, the code did not address any of these properties. An individual who plays the role of a developer in an application context writes the code. This demarcation clearly allows the separation of the two roles. The developer simply assumes that some things, such as transactions and security, will be available when the bean is deployed. The deployer makes these available by editing the deployment descriptors.

There are essentially two deployment descriptors that are needed for deploying a bean into a WebLogic container. A third deployment descriptor is needed for Entity beans. All these are files in the XML format and can be edited using any text editor. Because of this, it's suggested that you familiarize yourselves with the basics of writing an XML file before you continue with this section. This section will address only the format of these XML files as advocated by the specification and WebLogic. For the sake of brevity, this section won't address all possible fields that could be present in the deployment descriptor. You can refer to Sun's and BEA's documentation for a complete list of fields that go into these descriptors as well as the respective DTDs.

These deployment descriptors should be present under a directory called META-INF/, which is at the same level as your class files and packages. For instance, the base directory test would contain the packages com/wlsunleashed/.../*.class and META-INF/ as its subdirectories.

The required descriptor files for deploying the different types of beans are as follows:

• The first XML file is called ejb-jar.xml, which is part of the EJB 2.0 specification. This file defines several standard parameters that define the bean, such as its home, remote, local home, local object, and bean classes, transaction type supported, whether it's a Stateless or Stateful bean, and so forth. Later in this section, we take a detailed look at some of the attributes of this XML file.

• The second XML file complements the ejb-jar.xml file and is called weblogic-ejb-jar.xml. This file defines several properties that are specific to the deployment of the bean in WebLogic Server. The properties defined in this file include the JNDI name of the bean, the clustering properties of the bean, the properties affecting the bean's method-ready pool, and more.

• The last of the XML deployment descriptors is the weblogic-cmp-rdbms-jar.xml. This is specific to CMP Entity beans and is used to represent Entity beans that are handled by the WebLogic RDBMS CMP persistence type by defining persistence services, such as synchronization of the instance fields with the corresponding fields in the database.

The deployment descriptors can be edited using a text editor or with an XML editor. The descriptor elements can be viewed through the Descriptors tab as shown in Figure 20.7. This is useful for all deployed beans. The XML descriptors can be edited using the WebLogic Builder, which is covered later in the chapter.

J2EE Descriptor—ejb-jar.xml

The first deployment descriptor is the ejb-jar.xml. This descriptor is part of the Sun Microsystems' EJB specification. This file describes several properties of the bean to the container, which uses it to identify the runtime behavior of the bean. In this section, let's look at some of the properties that are common to most bean types and specific deployment elements and will be covered in detail in the next three chapters. Deployed beans are configured using the deployment elements defined in Table 20.5. The parent element for these elements is the bean type—that is, Session, Entity, or Message-Driven—that's defined under the enterprise-bean deployment element.

Table 20.5. EJB JAR Deployment Elements

Element Name	Description
ejb-name	Represents the EJB name. This identifies the bean in the container and should be unique. In our naming convention, this should be the bean name with EJB suffix; for example, AirlineReservationEJB.
home
local-home	Represents the fully qualified name of the EJB's home interface and the local home interface, respectively. Does not apply for Message-Driven beans. For example, AirlineReservationRemoteHome and AirlineReservationLocalHome.
remote
local	Represents the fully qualified name of the EJB's remote interface and local interface, respectively. Does not apply for Message-Driven beans. For example, AirlineReservationRemoteObject and AirlineReservationLocalObject.
ejb-class	Represents the fully qualified name of the EJB's bean class. For example, AirlineReservationBean.
transaction-type	Defines whether the transaction is container-managed or bean-managed. This does not apply to Entity beans.

The configuration section must contain at least one of the two pairs of home and component interfaces: either the remote interfaces, or the local interfaces, or both. Apart from these elements, the enterprise-beans deployment element can also list information about entries that the bean's implementation expects to be present in its environment at runtime, resource references, references to other beans that are used by this bean, security identities, and so on. We'll go over all these optional entries in reasonable detail in the other EJB chapters.

After the EJB deployer has defined all the beans that form the application, the deployer has to express some of the properties that describe the assembly of the beans in this deployment using the <assembly-descriptor> deployment element and major element within the <ejb-jar> stanza. This stanza describes two key elements of bean deployment: the transaction attributes of the bean's methods and the security. We'll look at these aspects in detail in later sections of this chapter. For a full definition of the deployment elements in the ejb-jar.xml, refer to the DTD defined at http://java.sun.com/dtd/ejb-jar_2_0.dtd. Listing 20.1 illustrates a simple bean example. This defines a Stateless Session bean: TraderEJB. In the assembly-descriptor element, we define a method tag that defines the transaction properties of this bean. In this case, all methods have a transaction attribute of Required that was explained earlier in the chapter.

Listing 20.1 ejb-jar.xml

<ejb-jar>
 <enterprise-beans>
  <session>
   <ejb-name>TraderEJB</ejb-name>
   <home>wlsunleashed.statelessSession.TraderHome</home>
   <remote>wlsunleashed.statelessSession.Trader</remote>
   <ejb-class>wlsunleashed.statelessSession.TraderBean</ejb-class>
   <session-type>Stateless</session-type>
   <transaction-type>Container</transaction-type>
   <env-entry>
    <env-entry-name></env-entry-name>
    <env-entry-type>java.lang.Double</env-entry-type>
    <env-entry-value>10.0</env-entry-value>
   </env-entry>
  </session>
 </enterprise-beans>
 <assembly-descriptor>
  <container-transaction>
   <method>
    <ejb-name>statelessSession</ejb-name>
    <method-name>*</method-name>
   </method>
   <trans-attribute>Required</trans-attribute>
  </container-transaction>
 </assembly-descriptor>
</ejb-jar>

WebLogic-Specific Descriptors

This section describes the WebLogic-specific deployment descriptors that contain elements specific to the WebLogic Server and not identified by the EJB 2.0 specification.

weblogic-ejb-jar.xml

This file contains more properties of the bean's deployment, but only those that are specific to WebLogic Server, including concurrency, caching, and clustering of the beans. This file also maps different resources (JDBC DataSources, EJBs, security roles, names, and so on) identified in the ejb-jar.xml to actual WebLogic server resources. The DTD governing this XML file can be found at the URL http://www.bea.com/servers/wls810/dtd/weblogic-ejb-jar.dtd . At deployment time, the XML parser used by WebLogic Server verifies the XML file against the rules mentioned in the DTD and ensures that the XML follows all the mentioned rules.

The weblogic-ejb-jar.xml file contains one root-level element called <weblogic-ejb-jar>. Within this root element, you may have the following element stanzas:

• Definitely one and possibly more <weblogic-enterprise-bean> stanzas that correspond to the <enterprise-bean> stanzas of the ejb-jar.xml file

• Optional security role assignments to the roles defined in the ejb-jar.xml (<security-role-assignment>)

• Optional transaction isolation settings on a method level of the bean; this applies only to Entity beans (<transaction-isolation>)

• Optional idempotent methods that can be called over and over again producing the same results, without affecting the integrity of the data (<idempotent-methods>)

Among these, the most important and mandatory stanza is the <weblogic-enterprise-bean> stanza. Here, we look into the contents of this stanza for a Stateless Session bean. Each of these properties identifies several parameters to the WebLogic container that further define the deployment properties of the beans. In this section, you can read about some of the important properties that can be defined for a session bean in a <weblogic-ejb-jar> stanza. Several other properties can be defined here. Refer to BEA's documentation for a complete list of possible parameters that can be defined in this XML file.

• The tag <ejb-name> identifies the EJB for which the following properties are defined. This name must match that of one bean that is defined in the ejb-jar.xml file.

• The <stateless-session-descriptor> stanza that identifies several properties for a stateless session bean.

• The <transaction-descriptor> stanza that identifies transaction related properties for the bean. More about this tag in the section that discusses transactions later in this chapter.

• The <reference-descriptor> stanza that concretely identifies all the resources that are referenced in the ejb-jar.xml file. More on this tag in the section that discusses bean references later in this chapter.

• A <enable-call-by-reference> property that tells the container whether it should use call by reference for making local EJB calls. By default, call by reference is disabled. When it's turned on and a client located in the same container as a bean invokes this bean using remote interfaces, WLS automatically optimizes the call, bypassing the RMI communication. The remote object will in effect perform like a local object. By default, parameters are passed by value. This parameter is set either to True or False. By default, the WebLogic Server container disables call by reference. Enabling call by reference causes any changes that are made to the parameter objects to be visible to the caller. If your bean can handle this, you can explicitly enable call by reference.

• The name under which this bean has to be loaded to be looked up remotely. This can be done by using the <jndi-name> tag. Use this tag only if you're using remote interfaces.

• The name under which this bean has to be loaded to be looked up locally. This can be done by using the <local-jndi-name> tag. Use this tag only if you are using local interfaces.

For a detailed reference on the parameters in the weblogic-ejb-jar.xml, refer to the BEA documentation at http://edocs.bea.com/wls/docs81/ejb/reference.html. Listing 20.2 is a simple example of a WebLogic EJB deployment descriptor.

Listing 20.2 weblogic-ejb-jar.xml

<weblogic-ejb-jar>
 <weblogic-enterprise-bean>
  <ejb-name>TraderEJB</ejb-name>
  <jndi-name>wlsunleahesd-TraderHome</jndi-name>
 </weblogic-enterprise-bean>
</weblogic-ejb-jar>

weblogic-cmp-rdbms-jar.xml

This XML deployment descriptor file for CMP Entity beans is WebLogic Server–specific. It's used to define entity relationships managed by CMP as well as parameters such as the data source and the table name for the Entity bean. For a full list of deployment elements, along with the syntax, refer to the BEA documentation at http://edocs.bea.com/wls/docs81/ejb/EJB_reference.html and the DTD documentation at http://www.bea.com/servers/wls810/dtd/weblogic-rdbms20-persistence-810.dtd.

Creating the Deployment Descriptor

As mentioned in the previous sections, the deployment descriptors are simply XML files and can be created using any text editor. But you typically don't start off creating the descriptors from scratch. WebLogic provides some handy-dandy tools that can be used to create a basic set of descriptors for your bean deployment. You can execute the class file weblogic.ant.taskdefs.ejb20.DDInit and pass to it the base directory of the classes you want to deploy. This tool scans through the class files and creates the deployment files for you. This tool uses Ant to generate the deployment descriptors. The generated deployment descriptors conform to the EJB 2.0 specification. For more information about using this tool, refer to BEA's documentation at http://edocs.bea.com/wls/docs81/toolstable/ToolsTable.html.

Alternatively, deployment descriptors can be created using the WebLogic Builder utility packaged with your WebLogic installation. The next section focuses on using this tool to both create a basic set of deployment descriptors and to deploy your bean into the WebLogic container.