BEA Logo BEA WebLogic Server Release 1.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

   BEA WebLogic Server Enterprise JavaBeans:   Previous topic   |   Next topic   |   Contents   


Upgrading EJBs to WebLogic Server Version 5.1




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:


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

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.

Compiled classes and interfaces

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.

Step 1: Convert the text deployment descriptor

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:

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 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


  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:



    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:


    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.

Optional conversion tasks

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.

Step 2: Package EJB Classes and Interfaces

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 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:

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

Step 3: Edit deployment properties and check compliance

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:

To open the EJB deployment .jar in DeployerTool:

  1. Use the setEnv.cmd or 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:

  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:

  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.