Deploying EJBs to WebLogic Server


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs \| Site Map \| Search \| Contact \| Glossary \| WebLogic Server Documentation

Programming WebLogic Enterprise JavaBeans: Previous topic \| Next topic \| Contents

The following sections provide an overview of deploying EJBs to WebLogic Server, and explain how to set the deployment properties used to EJBs. They also describe the two different ways you can deploy EJBs to WebLogic Server: static deployment and dynamic deployment.

Required Steps for Deploying EJBs

Deploying EJBs to WebLogic Server involves the following steps:

Setting the EJB deployment descriptors
Generating EJB container classes
Loading EJB classes in
Deploying EJBs at WebLogic Server startup or dynamically

The following sections described these steps in detail.

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 supply an EJB compliant ejb-jar.xml file that describes the bundled EJB(s). The ejb-jar.xml file and any other required XML deployment file must reside in a top-level META-INF subdirectory of the .jar or deployment directory.

Note: The deployment descriptors do 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 or 2.0 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 descriptions 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 Deployment Descriptor File 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 third-party persistence vendor, the file type as well as its contents may be different from weblogic-cmp-rdbms-jar.xml; refer to your persistence vendor's documentation for details.

If you do not have an ejb-jar.xml file, you must manually create or edit an existing one to set the necessary deployment properties for the EJB. You can use a text editor to edit the properties.

See Manually Editing XML Deployment Files for a description of the WebLogic Server Version 6.0 specific properties and files, and guidelines for editing those files by hand.

See Manually Editing XML Deployment Files for a description of the WebLogic Server 5.1 specific properties and files, and guidelines for editing those files by hand. These properties are provided for reference purposes, in case you need to edit the deployment files for 1.0 or 1.1 EJBs. To deploy an EJB to a WebLogic Server 2.0 EJB container, you can either edit the deployment properties of existing EJB 1.0 or 1.1 beans, or use the DDConverter utility, provided with WebLogic Server Version 6.0, to convert the deployment descriptors.

Generating EJB Container Classes

After you compile the EJB classes and add the required WebLogic Server XML deployment files identified in Setting Deployment Properties to your deployment unit, you must generate the container classes that are used to access the EJB. 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 XML 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.

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

Classloaders in Weblogic Server are hierarchical. When you start WebLogic Server, the Java system classloader is active and is the parent of all subsequent classloaders that WebLogic Server creates. When WebLogic Server deploys an application, it creates two new classloaders: one for EJBs and one for Web applications. The EJB classloader is a child of the Java system classloader and the Web application classloader is a child of the EJB classloader.

For more information on classloading, see "Classloader Overview" and "About Application Classloaders" in Developing WebLogic Server Applications.

Deploying EJBs at WebLogic Server Startup

To deploy EJBs automatically when WebLogic Server starts:

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.
Use a text editor to edit the XML deployment properties, as necessary.
Follow the instructions in Generating EJB Container Classes to compile implementation classes required for WebLogic Server.
Compiling the container places the .jar file in the weblogic/config/examples/applications directory, where it is automatically deployed when WebLogic Server starts. If your EJB .jar file is located in a different directory, make sure that you copy it to this directory if you want to deploy it at startup.
Start WebLogic Server.
When you boot WebLogic Server, it automatically attempts to deploy the specified EJB .jar file or deployment directory.
Launch the Administration Console.
In the right pane, click EJB Deployments.
A list of the EJB deployments for the server displays in the right-hand pane.

Deploying EJBs in Different Applications

When EJBs are not depoyed in the same application, call by reference cannot be used to invoke on the EJBs. Instead, pass by value would be used. Components that commonly interact with each other should be located in the same application where they can do call by reference. By default, EJB methods called from within the same server pass arguments by reference. This increases the performance of method invocation because parameters are not copied. Pass by value is always necessary when the EJB is called remotely (not from within the server

Deploying EJBs in a Running WebLogic Server (Dynamic Deployment)

Although placing the EJB .jar file or deployment directory in the weblogic/config/examples/applications directory allows you to automatically deploy the EJB, 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.

Dynamic deployment is provided for situations where rebooting WebLogic Server is not feasible. Using dynamic 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

Whether you deploy or update the EJB from the command line or the Administration Console, you use the dynamic deployment features. The following sections describe dynamic deployment concepts and procedures.

To work with beans in a dynamic deployment environment (running server), you first follow the steps described in Required Steps for Deploying EJBs.

EJB Deployment Names

When you deploy an EJB .jar file or deployment directory, 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, 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 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.

Viewing Deployed EJBs

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

From the command line:

Enter the following:
```
% 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
```

From the WebLogic Server Administration Console:

Choose EJB Deployments from J2EE node in the right-hand pane of the Console.
View a list of deployed EJBs.

Deploying New EJBs into a Running Environment

To deploy an EJB .jar file or deployment directory that has not 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

Undeploying an EJB effectively prohibits all clients from using the EJB. When you undeploy the EJB, 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.

Undeploying EJBs

To undeploy a deployed EJB, use the following steps:

From the command line:

you need only reference the assigned deployment unit name, as in:

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

From the WebLogic Server Administration Console:

Choose EJB Deployments from J2EE node in the right-hand pane of the Console.
Click the EJB you want to undeploy from the list.
Choose the Target tab and undeploy the EJB by toggling the server to the Available column.

Undeploying an EJB does not remove the EJB deployment name from WebLogic Server. The EJB will remain undeployed for the duration of the Server session, as long as you do not change it once it had been undeployed. 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 in the following section.

Updating Deployed EJBs

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 to be automatically deployed), or
You update the EJB deployment using the WebLogic Server Administration Console.

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.

The Update Process

When you update 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.

Updating the EJB

To update or redeploy the EJB implementation class, use the following steps:

From the command line:

Use the update argument and specify the active EJB deployment name:

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

From the WebLogic Server Administration Console:

Choose EJB Deployments from J2EE node in the right-hand pane of the Console.
Click the EJB you want to update from the list.
Choose the Target tab and update the EJB by toggling the server to the Chosen column.

You can update only the EJB implementation class, not the public interfaces or public support classes