Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation
BEA WebLogic Server Enterprise JavaBeans:   Previous topic   |   Next topic   |   Contents

Overview

Requirements

Text deployment descriptor

Compiled classes and interfaces

Step 1: Convert the text deployment descriptor

Optional conversion tasks

Step 2: Package EJB Classes and Interfaces

Step 3: Edit deployment properties and check compliance

WebLogic Server Version 5.1 provides an updated implementation of the Enterprise JavaBeans API that is compliant with JavaSoft's EJB 1.1 specification. To use existing EJBs with WebLogic Server Version 5.1, you must ensure that all components of your EJB system - the EJB classes, interfaces, clients, and deployment descriptors - are compliant with the new specification.

This section describes how to upgrade an existing EJB deployment unit to work with WebLogic Server. The upgrade process involves the following steps, each of which is described in the next sections:

• Step 1: Convert the text deployment descriptor. Use the DDConverter utility to convert existing WebLogic Server EJB text deployment descriptors to EJB 1.1-compliant XML descriptors.

• Step 2: Package EJB Classes and Interfaces. Create a new .jar file containing the EJB classes, interfaces, and XML deployment descriptor files.

• Step 3: Edit deployment properties and check compliance. Load the .jar file into DeployerTool and adjust deployment properties as necessary.

Requirements

To convert an existing WebLogic Server EJB deployment, you must have the following:

• the text version of an earlier WebLogic Server deployment descriptor

• the compiled EJB classes and interfaces

  Note: The WebLogic Server conversion utilities cannot update deployment description files from non-WebLogic Server application servers.

Text deployment descriptor

Obtain the WebLogic Server text deployment description of the deployment unit you want to upgrade. The text description file must be compatible with an earlier version of WebLogic Server. For example, you should be able to successfully create a .ser file from the text description using tools included with your earlier WebLogic Server version.

Note: You cannot use an existing .ser file with the DDConverter tool. Instead, obtain the text description file that you used to generate the .ser.

Your EJB classes, home interfaces, and remote interfaces must be compiled using a supported JDK. (See WebLogic Platform Support for more information.) Ideally, you should also make the changes to EJB code described in Required changes for EJB 1.1 compliance before compiling.

If you did not yet update your code to observe the EJB 1.1 restrictions, you can still begin converting the deployment unit to WebLogic Server Version 5.1. However, DeployerTool may indicate that the code in the final .jar file is not 1.1 compliant. In this case, you will need to fix all reported problems, recompile, and repackage the .jar before actually deploying the EJB.

In WebLogic Server Version 5.1, XML deployment descriptors replace serialized descriptors as the means of defining deployment properties. WebLogic Server provides the DDConverter utility to generate 1.1-compliant XML files. DDConverter takes an existing WebLogic Server text description and generates the following XML files:

• ejb-jar.xml, which defines the basic EJB deployment properties such as the bean class name, home and remote interfaces. This file is required as part of the EJB 1.1 specification.

• weblogic-ejb-jar.xml, which defines WebLogic Server-specific deployment properties such as timeout values and clustering behavior.

• weblogic-cmp-rdbms-jar.xml, which defines properties for entity EJBs that use WebLogic Server RDBMS-based container-managed persistence services. This file is not created for session EJBs, entity beans using bean-managed persistence, or entity beans using third-party persistence services.

Follow these steps to upgrade an existing 1.0-compliant WebLogic Server EJB text descriptor to the required 1.1-compliant XML files:

1. If necessary, use the instructions in Text deployment descriptor to verify that your text deployment description is EJB 1.0-compliant.

2. Move to the directory that contains the text deployment description you want to update. For example:

   $ cd \weblogic_old\testbean1

3. Create a new directory in which to store the new XML deployment description files:

   $ mkdir converted_xml

4. Use the setEnv.cmd or setEnv.sh script to set your environment for WebLogic Server Version 5.1:

   $ cd \weblogic51

   $ setenv

5. Use the WebLogic Server Version 5.1 DDConverter utility to convert the text descriptor to EJB 1.1-compliant XML files. The syntax for DDConverter is:

   $ java weblogic.ejb.utils.DDConverter -d targetDir oldDDFile

   where:

   • targetDir is the directory in which to store the new XML files

   • oldDDFile is the name of the text deployment description to convert

     For example:

     $ cd \weblogic_old\testbean1

     $ java weblogic.ejb.utils.DDConverter -d converted_xml 
     DeploymentDescriptor.txt 

     DDConverter updates 1.0 properties to their 1.1-equivalent properties and creates new XML files in the specified directory. DDConverter displays non-fatal error messages if any 1.0 properties are no longer used in WebLogic Server Version 5.1, or if "placeholder" values are used to define required Version 5.1 properties.

6. If DDConverter displays non-fatal error messages, address those errors before you package the new XML files into a .jar. Common error messages and their required actions include:

   Error	Action
   All user defined <env-entry> items were set to String. You will need to manually change the types as necessary.	Continue with Step 2: Package EJB Classes and Interfaces. Then follow the instructions in Step 3: Edit deployment properties and check compliance to change assigned environment entry types to their correct Java types. You will also need to change your EJB implementation to access environment entries using JNDI. See EJBContext.getEnvironment() Deprecated for more information.
   Required tag <ejb-name> was set arbitrarily to the JNDI name for the bean: bean_name. You should manually change the tag.	If you want to accept the default EJB name, no action is required. To change the default name, open both the ejb-jar.xml and weblogic-ejb-jar.xml files with a text editor, and change the name specified in the ejb-name property. For example: <ejb-name>new.ejb.name</ejb-name> Always make identical changes to the ejb-name in both ejb-jar.xml and weblogic-ejb-jar.xml.
   runAsMode is no longer supported. Property is not being set for method: method_name	No action is required.

When DDConverter updates the deployment descriptor for an entity bean with container-managed persistence, it always defines a compound primary key in the ejb-jar.xml deployment file. If your bean uses a simple primary key, consider editing ejb-jar.xml to define a simple key. See Primary key changes for container-managed EJBs for more information.

Also, you may want to change the default value of the jndi-name property in ejb-jar.xml. During the upgrade process, DDConverter sets jndi-name to the value of the beanHomeName property from your 1.0 text deployment file.

The converted XML description files, along with compiled EJB classes, must be packaged into a .jar file before compiling stubs and skeleton classes with ejbc or loading into the WebLogic Server DeployerTool. The structure of the EJB .jar file must observe the following requirements:

• The .jar must include a top-level directory named META-INF that contains the XML deployment files.

• The .jar must store EJB classes and interfaces in a directory hierarchy that matches the files' Java package hierarchy.

The following steps explain how to create an EJB 1.1-compliant .jar file that you can load into the WebLogic Server DeployerTool utility:

1. Create a temporary directory to use for staging the .jar file directories and files. For example:

   $ mkdir jartemp

2. Move into the temporary directory:

   $ cd jartemp

3. Within the temporary directory, create a top-level META-INF directory to store the XML deployment files:

   $ mkdir META-INF

4. Create a directory hierarchy to store your EJB classes and interfaces. The directory hierarchy must exactly match the package hierarchy of the classes and interfaces you will include in the .jar.

   For example, if you store your EJB files in the package examples.ejb.basic.beanManaged, create the directories:

   $ mkdir examples

   $ mkdir examples\ejb

   $ mkdir examples\ejb\basic

   $ mkdir examples\ejb\basic\beanManaged

5. Copy the compiled EJB classes and interfaces, and the 1.1-compliant XML deployment descriptor files, into the appropriate subdirectories of the staging directory. For example:

   $ copy c:\dev\examples\ejb\basic\beanManaged\*.class c:\jartemp\examples\ejb\basic\beanManaged

   $ copy c:\dev\ejb\basic\beanManaged\converted_xml\*.xml c:\jartemp\META-INF

6. While at the top level of the temporary directory, use the jar utility included with your Java SDK to create the EJB jar file. For example:

   $ jar cf beanManaged.jar examples\ejb\basic\beanManaged META-INF

   Note: You do not need to include a MANIFEST file in the .jar file, as was required with the EJB 1.0 specification.

7. Use the jar utility once again to verify the structure of the newly-created .jar file. The output should indicate that:

   • The .jar includes your EJB classes in directories that match your package hierarchy, and

   • The generated XML files reside in a top-level META-INF directory.

     For example:

     $ jar tf beanManaged.jar

     META-INF/

     META-INF/MANIFEST.MF

     examples/ejb/basic/beanManaged/

     examples/ejb/basic/beanManaged/Account.class

     examples/ejb/basic/beanManaged/AccountBean.class

     examples/ejb/basic/beanManaged/AccountHome.class

     examples/ejb/basic/beanManaged/AccountPK.class

     examples/ejb/basic/beanManaged/ProcessingErrorException.class

     META-INF/ejb-jar.xml

     META-INF/weblogic-ejb-jar.xml

Follow the steps in Step 3: Edit deployment properties and check compliance to load the new .jar file into DeployerTool.

The EJB 1.1 specification defines new deployment properties that were not part of the text deployment description you converted in Step 1: Convert the text deployment descriptor. Follow the steps below to load the EJB deployment unit into the WebLogic Server DeployerTool utility and:

• set values for undefined deployment properties

• change deployment property "placeholder" values that were set by the DDConverter utility

To open the EJB deployment .jar in DeployerTool:

1. Use the setEnv.cmd or setEnv.sh script to set your environment for WebLogic Server Version 5.1:

   $ cd \weblogic51

   $ setenv

2. Start DeployerTool using the command:

   % java -ms24m -mx24m weblogic.EJBDeployerTool

   If you installed WebLogic Server under Windows NT, you can also start DeployerTool using the Start menu.

3. Select the Servers category in the object panel.

4. Click the Add button in the edit panel. DeployerTool creates a blank server entry in the edit panel:

5. Fill in the fields of the new server entry as follows:

   • Name: Enter the name to use for this WebLogic Server within DeployerTool.

   • Protocol: Select the protocol to use for connecting to the WebLogic Server

   • Host: Enter the host name of the machine on which the WebLogic Server is running.

   • Listen port: Enter the WebLogic Server listen port for this server.

   • System password: Enter a valid password for the server's System account.

   • Default: Click this box to have DeployerTool use this server as the default for deployment.

6. Select File->Open...

7. Type in the complete path to the .jar file you created in Step 2: Package EJB Classes and Interfaces, or navigate to select the file.

8. Click Open to open the selected .jar file. DeployerTool places the new .jar file in the deployer projects category:

9. Use the following DeployerTool links to address any non-fatal errors you received in Step 2: Package EJB Classes and Interfaces:

   • Setting EJB class properties

   • Adding, removing, and changing environment entries

10. Check the .jar file for EJB 1.1 compliance using the instructions in Validating deployment units.

11. Select File->Save to save your changes to the .jar file.

12. Deploy the .jar using the instructions in Compiling and deploying EJBs.