Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
BEA WebLogic Server Enterprise JavaBeans 1.1: Previous topic | Next topic | Contents

Deploying EJBs in WebLogic Server

Overview

Required steps for deploying EJBs

Setting deployment properties

Generating EJB container classes

Loading EJB classes into WebLogic Server

Note for jview Users

Overview of WebLogic Server classloading

Deploying EJBs at startup

Deploying EJBs in a running WebLogic Server (Hot Deployment)

Hot deploy concepts and restrictions

EJB deployment names

Undeployment

Updating deployment units

Viewing deployed EJBs

Deploying new EJBs

Undeploying deployed EJBs

Updating deployed EJBs

Overview

WebLogic Server provides several utilities and methods for deploying EJB 1.1-compliant .jar files. DeployerTool provides a graphical user interface, while the deploy utility runs from a command shell. You can even permanently deploy an EJB by simply editing the weblogic.properties file without using a deployment utility.

The following sections provide an overview of deploying EJBs to WebLogic Server, and explain how to deploy using the deploy utility and weblogic.properties file. They also describe the two different ways you can deploy EJBs to WebLogic Server: permanent deployment and hot deployment. Also refer to Deploying EJBs with DeployerTool for complete information about using the DeployerTool utility.

Required steps for deploying EJBs

Deploying EJBs in WebLogic Server involves three distinct steps:

1. Set EJB deployment properties

2. Generate EJB container classes

3. Load EJB classes into WebLogic Server

Setting deployment properties

The deployment process begins with a .jar file or a deployment directory that contains the compiled EJB interfaces and implementation classes created by the EJB provider. Regardless of whether the compiled classes are stored in a .jar file or a deployment directory, they must reside in subdirectories that match their Java package structures.

The EJB provider should also provide an EJB 1.1-compliant ejb-jar.xml file that describes the bundled EJB(s). ejb-jar.xml, and any other required XML deployment files, must reside in a top-level META-INF subdirectory of the .jar or deployment directory.

Note: The deployer does not need to include a MANIFEST file in the .jar file, as was required with the EJB 1.0 specification. See the JavaSoft EJB 1.1 specification for more information.

As is, the basic .jar or deployment directory cannot be deployed to WebLogic Server. You must first create and configure WebLogic Server-specific deployment properties in the weblogic-ejb-jar.xml file, and add that file to the deployment. weblogic-ejb-jar.xml defines caching, clustering, and performance behavior, and is required for all EJBs. See weblogic-ejb-jar.xml Properties for a complete list of properties available in the file.

If you are deploying an entity EJB that uses container-managed persistence, you must also include an additional deployment file for the bean's persistence type. For WebLogic Server RDBMS-based persistence services the file is generally named weblogic-cmp-rdbms-jar.xml, and you require a separate file for each bean that uses RDBMS persistence. If you use a 3rd-party persistence vendor, the file type as well as its contents may be different; refer to your persistence vendor's documentation for details.

The graphical DeployerTool utility automatically generates the weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml files as necessary when you configure the beans in a .jar file. See Deploying EJBs with DeployerTool for more information.

You can also manually create the required XML deployment files and set deployment properties using a text editor. XML deployment properties describes the WebLogic Server properties and files, and provides guidelines for editing those files by hand.

Generating EJB container classes

After you have compiled the EJB classes and added the required WebLogic Server XML deployment files to your deployment unit, you must generate the container classes that are used to access the bean. Container classes include both the internal representation of the EJB that WebLogic Server uses, as well as implementation of the external interfaces (home and remote) that clients use.

The ejbc compiler generates container classes according to the deployment properties you have specified in WebLogic Server-specific deployment 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.

The DeployerTool utility automatically calls ejbc as necessary to generate container classes for the selected .jar. See Compiling and deploying EJBs for more information. You can also use ejbc directly from the command line by supplying the required options and arguments. See ejbc for more information.

Loading EJB classes into WebLogic Server

The final step in deploying an EJB involves loading the generated container classes into WebLogic Server. You can prompt WebLogic Server to automatically load EJB classes during startup by adding an entry in weblogic.properties, as described in Deploying EJBs at startup. Or, you can prompt a running WebLogic Server to load EJB classes using a utility such as deploy or DeployerTool. See Deploying EJBs in a running WebLogic Server (Hot Deployment) for more information.

Note for jview Users

The following discussion of classloading behavior applies only to JDK 1.1 and 1.2. If you are using jview, WebLogic Server and EJB classes are loaded by a single classloader, and you cannot use hot deployment features.

To deploy EJBs when using jview, you must add the path to all deployable EJB .jar files to the CLASSPATH used boot WebLogic Server. If you start WebLogic Server using the startWebLogic.cmd or startWebLogic.sh scripts, you can add EJB .jar files directly to the POST_CLASSPATH variable, as in:

    POST_CLASSPATH=C:\weblogic\myserver\ejb_basic_beanManaged.jar

This automatically adds EJB .jar files to the end of the CLASSPATH when starting WebLogic Server.

See Setting the classpath for more information about setting the CLASSPATH at the command line when using jview.

Overview of WebLogic Server classloading

Note: If you are using JDK 1.1, note that JDK 1.1 does not use a top-level Java system classloader. However, the basic description of classloading behavior applies to both JDK 1.1 and JDK 1.2.

When you start WebLogic Server, the system begins loading Java classes using two distinct classloaders: The system classloader and the WebLogic Server classloader.

The system classloader is the default Java classloader installed on your system (the classloader provided by your JDK or JRE). The system classloader loads the Java classes specified in the CLASSPATH environment variable. This includes standard Java runtime classes, as well as the WebLogic Server boot classes located in /weblogic/classes/boot.

One of the boot classes available in the /weblogic/classes/boot creates the WebLogic Server classloader, which continues the startup process by loading classes specified in the weblogic.classpath property. These classes include internal WebLogic Server support classes as well as certain user-defined classes, such as WebLogic Server startup classes.

The EJB and servlet classloaders

To support hot deployment for EJBs, Servlets, and JSPs, the WebLogic Server system must dynamically load and unload these classes in response to deployment requests. WebLogic Server provides this support by loading each EJB .jar file and each servlet or JSP in a separate, specialized classloader that understands how to subsequently export and unload required classes. These specialized WebLogic Server classloaders are the EJB classloader and the servlet classloader.

The EJB classloader loads and exports classes in an EJB 1.1-compliant .jar file. EJB implementation classes, as well as supporting classes in the .jar file, are loaded and maintained locally by the EJB classloader. The classloader maintains these classes until they are subsequently redeployed, undeployed, or the server shuts down.

The EJB classloader exports an EJB's home and remote interfaces to its parent classloader, the WebLogic Server classloader. If the EJB's public interfaces reference additional supporting classes, those supporting classes are also exported. Exporting the public interfaces and their supporting classes makes the interfaces available to other clients in WebLogic Server that may need to access the bean (for example, other EJBs, servlets, and JSPs). However, because they are made publicly available, the EJB's public interface and public interfaces cannot be subsequently redeployed, as described in Hot deploy concepts and restrictions.

The servlet classloader provides similar support for redeploying servlets and JSPs; see Deploying servlets from the WebLogic Console for more information on deploying servlets and JSPs using hot deploy.

Classloader hierarchy in WebLogic Server

The multiple classloaders in a WebLogic Server system reside in a hierarchy beginning with the system classloader, which loads the WebLogic Server classloader, and so forth. The following figure shows the hierarchical relationship between classloaders, as well as representative classes that each classloader maintains.

An important concept to consider when deploying EJBs and servlets is that Java class loaders, including the specialized classloaders in WebLogic Server, attempt to locate classes using their parent class loaders, if the class is not currently available in the classloader's cache. Both the EJB classloader and the servlet classloader share the same parent class loader, which can result in errors if you duplicate class names in EJB and servlets, as described below.

Diagnosing ClassCastException errors

A common problem when deploying and using EJBs and servlets is the ClassCastException. ClassCastExceptions can occur when a class of the same name resides in more than one classloader within WebLogic Server. Although the classes may have the same name and use the same bytecode, if the classes are loaded by separate classloaders, they are treated as different classes. A common scenario is as follows:

1. An EJB provider uses a support class, "Address" in an EJB's public interface. Upon deployment, the EJB classloader exports the EJB's public interface, and also exports the "Address" class, to the WebLogic classloader.

2. A servlet developer includes an identical "Address" class as part of a servlet deployment. When the servlet class is deployed, the servlet classloader loads and maintains an identical version of the "Address" class.

3. The servlet invokes the EJB to obtain a new object of the "Address" class. In this case, WebLogic Server yields a ClassCastException error. Because the "Address" class exists in both the WebLogic classloader and Servlet classloader, they are treated as completely different classes.

To correct such ClassCastException errors, EJB and servlet developers must ensure that no two classloaders ever load an identical class. Specifically, you should always ensure that EJB classes reside only in the deployed EJB .jar file or EJB directory, and that they are not included in other EJB .jar files or classpath definitions.

Diagnosing ClassNotFoundException errors

A less common problem when deploying and using EJBs is the ClassNotFoundException. ClassNotFoundExceptions occur when a given class cannot be loaded by a given classloader or any of its parent classloaders. Because WebLogic Server uses a hierarchy of classloaders, diagnosing ClassnotFoundExceptions can sometimes be difficult. The following describes a potential class loading problem:

1. An EJB provider uses a support class, "Class1," in an EJB implementation class. Upon deployment, the EJB classloader loads and maintains the EJB implementation class, which references "Class1." "Class1" is not exported to the WebLogic classloader, because it is not used in any of the EJB's public interfaces.

2. A second EJB (or servlet) accesses the newly-deployed EJB, and attempts to create an instance of class "Class1".

3. The classloader for the second EJB (or servlet) attempts to find "Class1," in its local cache. If it cannot find "Class1", the parent classloader (the WebLogic classloader) attempts to find the class. Since "Class1" was not exported at deployment time, the next parent classloader (the system classloader) attempts to find the class.

   If "Class1" cannot be loaded using any of the classloaders in this hierarchy, the client receives a ClassNotFoundException. This error occurs even though "Class1" resides in the EJBs classloader.

To avoid class loading problems, always ensure that all support classes that must be available to internal clients of the EJB are included in the EJB's public interfaces, or are themselves implemented as Java interfaces. Doing so ensures that the EJB's classloader exports the required classes to the WebLogic classloader, where they are publicly available to WebLogic Server clients.

Classloading between WebLogic Servers

WebLogic Server cannot load classes "over the network" for RMI objects that reside on a remote WebLogic Server system. If an EJB or servlet on one WebLogic Server acts as a client to another EJB or RMI object on a second server, you must ensure that the stub classes for the remote EJB or RMI object reside in the local server's CLASSPATH.

Deploying EJBs at startup

To deploy EJBs at automatically when WebLogic Server starts:

1. Follow the instructions in Setting deployment properties to ensure that your deployable EJB .jar file or deployment directory contains the required WebLogic Server XML deployment files.

2. Follow the instructions in Generating EJB container classes to compile implementation classes required for WebLogic Server.

3. Use a text editor to open the weblogic.properties file for WebLogic Server to which you will deploy the EJB.

4. Add a definition for the weblogic.ejb.deploy property in the weblogic.properties file. The basic syntax of this property is:

       weblogic.ejb.deploy=source

   where source specifies the complete path and filename of the .jar to deploy, or the complete path to the EJB deployment directory. For example:

       weblogic.ejb.deploy=C:/weblogic510/myserver/ejb_basic_beanManaged.jar

When you boot WebLogic Server, it automatically attempts to deploy the specified EJB .jar file or deployment directory. You can observe the EJBs as they are loaded by examining the WebLogic Server log file or by using the console utility.

Deploying EJBs in a running WebLogic Server (Hot Deployment)

Although editing the weblogic.ejb.deploy provides automatic deployment for EJBs, it requires that you start or reboot the server before the bean can be used. Once a bean has been deployed, another edit and reboot is required to remove the bean.

Hot deployment is provided for situations where rebooting WebLogic Server is not feasible. Using hot deployment features, you can:

- Deploy a newly-developed EJB to a running, production system

- Remove a deployed EJB to restrict access to data

- Update a deployed EJB implementation class to fix a bug or test a new feature

Both the deploy command shell utility and the DeployerTool graphical interface use hot deploy features for deploying and updating EJBs. Some features, such as removing a deployed EJB, are available only by using deploy. For this reason, the following section provides details for using the deploy at the command shell. See Deploying EJBs with DeployerTool for information on using hot deploy with via a graphical interface.

Hot deploy concepts and restrictions

To deploy beans into a running server, you must follow the same steps described under Required steps for deploying EJBs. Hot deployment introduces several additional concepts:

- EJB deployment names

- Undeploying EJBs

- Updating EJBs

EJB deployment names

When you deploy an EJB .jar file or deployment directory using the deploy utility, you must specify a name for the deployment unit. This name provides a shorthand reference to the EJB deployment that you can later use to undeploy or update the EJB.

When you deploy an EJB by editing weblogic.properties, WebLogic Server implicitly assigns a deployment name that matches the path and filename of the .jar file or deployment directory. You can use this assigned name with deploy to undeploy or update the bean after the server has started.

Note: The EJB deployment name remains active in WebLogic Server until the server is rebooted. Undeploying an EJB does not remove the associated deployment name, because you may later re-use that name to deploy the bean.

Undeployment

Undeploying an EJB effectively prohibits all clients from using the EJB. When you use the deploy utility with the undeploy argument, the specified EJB's implementation class is immediately marked as unavailable in the server. WebLogic Server automatically removes the implementation class and propagates an UndeploymentException to all clients that were using the bean.

Undeployment does not automatically remove the specified EJB's public interface classes. Implementations of the home interface, remote interface, and any support classes referenced in the public interfaces, remain in the server until all references to those classes are released. At that point, the public classes may be removed due to normal Java garbage collection routines.

Similarly, undeploying an EJB does not remove the deployment name associated with the EJB .jar file or deployment directory. The deployment name remains in the server to allow for later updates of the EJB.

Updating deployment units

When you update the contents of an EJB .jar file or deployment directory that has been deployed to WebLogic Server, those updates are not reflected in WebLogic Server until:

- you reboot the server (if the .jar or directory is automatically deployed using the weblogic.properties file), or

- you update the EJB deployment using the deploy utility

Updating an EJB deployment enables an EJB provider to make changes to a deployed EJB's implementation classes, recompile, and then "refresh" the implementation classes in a running server.

When you use the deploy utility with the update argument, the currently-loaded implementation classes for the EJB are immediately marked as unavailable in the server, and the EJB's classloader and associated classes are removed. WebLogic Server automatically propagates a RedeploymentException to all clients that were using the bean. At the same time, a new EJB classloader is created, which loads and maintains the revised EJB implementation classes.

When clients next acquire a reference to the EJB, their EJB method calls use the updated EJB implementation classes.

Note: You can update only the EJB implementation classes, as described in Loading EJB classes into WebLogic Server. You cannot update the EJB's public interfaces, or any support classes that are used by the public interfaces. If you make any changes to the EJB's public classes and attempt to update the EJB, WebLogic Server displays an incompatible class change error when a client next uses the EJB instance.

Viewing deployed EJBs

To view EJBs that are deployed on a local WebLogic Server, use the command:

    % java weblogic.deploy list password

where password is the password for the WebLogic Server System account. To list deployed EJBs on a remote server, specify the port and host options as follows:

    % java weblogic.deploy -port port_number -host host_name
      list password

Deploying new EJBs

To deploy an EJB .jar file or deployment directory that has not yet been deployed to WebLogic Server, use the command:

    % java weblogic.deploy -port port_number -host host_name
      deploy password name source

where:

- name is the string you want to assign to this EJB deployment unit

- source is the full path and filename of the EJB .jar file you want to deploy, or the full path of the EJB deployment directory

For example:

    % java weblogic.deploy -port 7001 -host localhost deploy
      weblogicpwd CMP_example
      c:\weblogic\myserver\unjarred\containerManaged\

Undeploying deployed EJBs

To remove a deployed EJB, you need only reference the assigned deployment unit name, as in:

    % java weblogic.deploy -port 7001 -host localhost undeploy
      weblogicpwd CMP_example

Note: Undeploying an EJB does not remove the EJB deployment name from WebLogic Server. You cannot re-use the deployment name with the deploy argument until you reboot the server. You can re-use the deployment name to update the deployment, as described below.

Updating deployed EJBs

To update the EJB implementation class, use the update argument and specify the active EJB deployment name:

    % java weblogic.deploy -port 7001 -host localhost update
      weblogicpwd CMP_example

Note: You can update only the EJB implementation classes - not the public interfaces or public support classes. See Updating deployment units for more information.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.