Packaging EJBs for the WebLogic Server EJB Container
The following section discusses packaging - also termed "assembling" - issues and procedures specific to Enterprise JavaBeans . Before reading this section, read Assembling and Packaging WebLogic Server Applications" in Developing WebLogic Server Applications for general instructions on packaging WebLogic Server applications and modules, including EJBs. The topics in this section discuss only packaging issues and procedures that are specific to EJBs.
- A Closer Look at EJB Deployment Descriptors
- Compiling EJB Classes and Generating EJB Container Classes
- Referencing Other EJBs and Resources
- Specifying an ejb-client.jar
A Closer Look at EJB Deployment Descriptors
As part of creating and packaging your EJBs, you generate a number of deployment descriptor files and place them in their correct location.The deployment files become part of the EJB deployment when the bean is compiled.
The XML deployment descriptor files should contain the minimum deployment descriptor settings for the EJB. Once the file exists, you can edit it later using the instructions in Editing Deployment Descriptors. The deployment descriptor files must conform to the correct version of the Document Type Definition (DTD) for each file you use.
All element and sub element (attribute) names for each of the EJB XML deployment descriptor files are described in the file's Document Type Definition (DTD) file. For a description of each file, see the following sections.
The Three EJB Deployment Descriptor Files
Enterprise JavaBeans use three deployment descriptors to define their operational attributes:
- An ejb-jar.xml deployment descriptor is a J2EE standard XML document that describes the contents of a JAR file. For detailed information about the elements in ejb-jar.xml, see http://www.java.sun.com/dtd/ejb-jar_2_0.dtd.
- A weblogic-ejb-jar.xml deployment descriptor is an XML document containing WebLogic Server-specific elements for EJBs. For detailed information about the elements in weblogic-ejb-jar.xml, see The weblogic-ejb-jar.xml Deployment Descriptor.
- A weblogic-cmp-rdbms-jar.xml file is an XML document containing WebLogic Server-specific elements that pertain to container-managed persistence. For detailed information about the elements in weblogic-cmp-rdbms-jar.xml, see The weblogic-cmp-rdbms- jar.xml Deployment Descriptor.
Relationships Among the Deployment Descriptors
Descriptors in weblogic-ejb-jar.xml are linked to EJB names in ejb-jar.xml, to resource names in a running WebLogic Server, and to persistence type data defined in weblogic-cmp-rdbms-jar.xml (for entity EJBs using container-managed persistence). The following diagram shows the relationship among the deployment files and WebLogic Server.Figure 7-1 The relationship among the components of the deployment files.
Document Type Definitions and DOCTYPE Header Information
The contents and arrangement of elements in your XML files must conform to the Document Type Definition (DTD) for each file you use. WebLogic Server ignores the DTDs embedded within the DOCTYPE header of XML deployment files, and instead uses the DTD locations that were installed along with the server. However, the DOCTYPE header information must include a valid URL syntax in order to avoid parser errors.
When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose.
The header refers to the location and version of the Document Type Definition (DTD) file for the deployment descriptor. Although this header references an external URL at java.sun.com, WebLogic Server contains its own copy of the DTD file, so your host server need not have access to the Internet. However, still include this <!DOCTYPE...> element in your weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml files, and have them reference the external URL because the version of the DTD contained in this element is used to identify the version of this deployment descriptor.
XML files with incorrect header information may yield error messages similar to the following, when used with a tool that parses the XML (such as appc ):
SAXException: This document may not have the identifier `identifier_name'
identifier_name generally includes the invalid text from the PUBLIC element.
The correct text for the PUBLIC elements for the-WebLogic Server-specific weblogic-ejb-jar.xml file is as follows:
The correct text for the PUBLIC element for the WebLogic Server-specific weblogic-cmp-rdbms-jar.xml files is as follows:
The correct text for the PUBLIC elements for the Sun Microsystem-specific ejb-jar.xml file are as follows:
XML File PUBLIC Element String ejb-jar.xml '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' 'http://java.sun.com/dtd/ejb-jar_2_0.dtd' ejb-jar.xml '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN' 'http://www.java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'
For example, the entire DOCTYPE header for a weblogic-ejb-jar.xml file is as follows:
<!DOCTYPE weblogic-ejb-jar PUBLIC
'-//BEA Systems, Inc.//DTD WebLogic 8.1.0 EJB//EN' 'http://www.bea.com/servers/wls810/dtd/weblogic-ejb-jar.dtd'>
Editing Deployment Descriptors
You can edit deployment descriptors using the following tools:
- Using WebLogic Builder. WebLogic Builder is the BEA preferred WebLogic Server tool for editing deployment descriptors for WebLogic Server applications. It can also deploy WebLogic Server applications to single servers.
- Manually using the BEA XML Editor, which is an entirely Java-based XML stand-alone editor. For more documentation about using the BEA XML Editor and to download it, visit BEA dev2dev Online.
- Using the console Descriptors sub-tab of the Configuration tab. The Descriptors tab has replaced the deprecated Deployment Descriptor Editor in the console.
Using WebLogic Builder to Edit Deployment Descriptors
WebLogic Builder provides a visual environment for editing an application's deployment descriptor XML files. You can view these XML files as you visually edit them in WebLogic Builder, but you do not need to make textual edits to the XML files.
Use WebLogic Builder for the following development tasks:
- Generate deployment descriptor files for a J2EE module
- Edit a module's deployment descriptor files
- View deployment descriptor files
- Compile and validate deployment descriptor files
- Deploy a module to a server
For instructions on using WebLogic Builder, refer to the WebLogic Builder documentation.
Manually Editing XML Deployment Files
To edit XML deployment descriptor elements manually:
- Use an ASCII text editor that does not reformat the XML or insert additional characters that could invalidate the file.
- Open the XML deployment descriptor file that you want to edit.
- Type in your changes. Use the correct case for file and directory names, even if your operating system ignores the case.
- To use the default value for an optional element, either omit the entire element definition or specify a blank value, as in:
Be sure to include the correct DOCTYPE header for each deployment descriptor.
Dynamic Descriptor Updates
This release of WebLogic Server has deprecated the console Deployment Descriptor Editor. A new Descriptors tab in the console has replaced it. The Descriptors tab is intended for administrative purposes.
Using the Descriptors tab, you can view, modify, and persist deployment descriptor elements to the descriptor file within the EJB. Descriptors are modified in the Administration Server copy of the EJB as well as in any deployed copies of the EJB (after deployment). When you modify descriptors using WebLogic Builder or a manual editing tool, changes are made to your (the user's) original copy of the EJB (prior to deployment).
However, updating these descriptor elements takes place dynamically at runtime without requiring that the EJB be redeployed. The descriptor element attributes contained in the Descriptors tab are limited to only those that may be dynamically changed at runtime, as listed in the following table:
Table 7-1 Deployment Descriptor Elements Editable via Descriptors Tab
EJB Type Editable Elements Entity
- idle-timeout-seconds (read-only entity beans only)
Message-Driven Stateless Stateful
Compiling EJB Classes and Generating EJB Container Classes
For part of the process of building your deployment unit, you need to compile your EJB classes, add your deployment descriptors to the deployment unit, and generate the container classes used to access the deployment unit.
- Compile the EJB classes using javac compiler from the command line.
- Add the appropriate XML deployment descriptor files to the compiled unit.
- Generate the container classes that are used to access the bean using appc.
Container classes include both the internal representation of the EJB that WebLogic Server uses, as well as implementation of the external interfaces (home, local, and/or remote) that clients use.
The appc compiler generates container classes according to the deployment descriptors you have specified in WebLogic-specific XML deployment descriptor files. For example, if you indicate that your EJBs will be used in a cluster, ejbc creates special cluster-aware classes that will be used for deployment.
You can also use ejbc directly from the command line by supplying the required options and arguments.
The following figure shows the container classes added to the deployment unit when the EAR or JAR file is generated.Figure 7-2 Generating EJB container classes
Possible Generated Class Name Collisions
Although infrequent, when you generate classes with appc, you may encounter a generated class