|[ Team LiB ]|
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 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.
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.
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.
<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>
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:
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.
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.
<weblogic-ejb-jar> <weblogic-enterprise-bean> <ejb-name>TraderEJB</ejb-name> <jndi-name>wlsunleahesd-TraderHome</jndi-name> </weblogic-enterprise-bean> </weblogic-ejb-jar>
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.
|[ Team LiB ]|