BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | Programming WebLogic EJB | Previous Topic | Next Topic | Contents | View as PDF

Deploying EJBs to WebLogic Server

The following sections provides instructions for deploying EJBs to WebLogic Server at WebLogic Server startup or on a running WebLogic Server.

- Roles and Responsibilities

- Deploying EJBs at WebLogic Server Startup

- Deploying EJBs on a Running WebLogic Server

- Deploying New EJBs into a Running Environment

- Undeploying Deployed EJBs

- Updating Deployed EJBs

- Deploying Compiled EJB Files

- Deploying Uncompiled EJB Files

Roles and Responsibilities

The following sections are written primarily for:

- Deployers who configure EJBs to run in the WebLogic Server container

- Application assemblers who link multiple EJBs and EJB resources to create larger Web application systems

- EJB developers who create and configure new EJB JAR files

You can create, modify, and deploy EJBs in one or more instance of WebLogic Server. You can set up your EJB deployment, and map EJB references to actual resource factories, roles, and other EJBs available on a server by editing the XML deployment descriptor files.

Deploying EJBs at WebLogic Server Startup

To deploy EJBs automatically when WebLogic Server starts:

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

2. Use a text editor or the EJB Deployment Descriptor Editor in the Administration Console to edit the XML deployment descriptor elements, as necessary.

3. Follow the instructions in Compiling EJB Classes and Generating EJB Container Classes to compile implementation classes required for WebLogic Server.

   Compiling the container places the JAR file in the deployment directory specified in the deployment descriptors. If you want the EJB to automatically deploy when WebLogic Server starts, place the EJB be deployed to the following directory:

   wlserver/config/mydomain/applications

   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.

4. Start WebLogic Server.

   When you boot WebLogic Server, it automatically attempts to deploy the specified EJB JAR file or deployment directory.

5. Launch the Administration Console.

6. 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 you deploy EJBs with remote calls to each other different applications, you cannot use call-by-reference to invoke the EJBs. Instead, you use pass-by-value. Components that commonly interact with each other should be located in the same application where call-by-reference can be used. 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 EJBs are called remotely (not from within the server).

Deploying EJBs on a Running WebLogic Server

Although placing the EJB JAR file or deployment directory in the wlserver/config/mydomain/applications directory allows the EJB to be immediately deployed, if you make a change to the deployed EJB, you must redeploy the EJB for the changes to take effect.

Automatic deployment is provided for situations where rebooting WebLogic Server is not feasible and is for development purposes only. Using automatic deployment only deploys the updated EJB to the Administration Server and does not deploy the EJB to any Managed Server on the domain. Using automatic deployment features, you can:

- Deploy a newly developed EJB to a running development 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 automatic deployment features. The following sections describe automatic deployment concepts and procedures.

EJB Deployment Names

When you deploy an EJB JAR file or deployment directory, you specify a name for the deployment unit. This name is 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.

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\

Deploying Pinned EJBs - Special Step Required

There is a known issue with deploying or redeploying EJBs to a single server instance in a cluster—referred to as pinned deployment—if the .jar file contains contain uncompiled classes and interfaces.

During deployment, the uncompiled EJB is copied to each server instance in the cluster, but it is compiled only on the server instance to which it has been deployed. As a result, the server instances in the cluster to which the EJB was not targeted lack the classes generated during compilation that are necessary to invoke the EJB. When a client on another server instance tries to invoke the pinned EJB, it fails, and an Assertion error is thrown in the RMI layer.

If you are deploying or redeploying an EJB to a single server instance in a cluster, compile the EJB with appc or ejbc before deploying it, , to ensure that the generated classes copied to all server instances available to all nodes in the cluster.

Viewing Deployed EJBs

To view deployed EJBs:

- From the command line:

1. To list the EJBs that are deployed on a local WebLogic Server, enter the following:

   >     % java weblogic.deploy list password

where password is the password for the WebLogic Server System account.

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

1. Choose EJB from the Deployments node in the left pane of the Console.

2. View a list of deployed EJBs deployed on the server.

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:

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:

1. Choose EJB from the Deployments node in the left pane of the Console.

2. Click the EJB you want to undeploy from the list.

3. Choose the Configuration tab from the dialog in the right pane and uncheck the undeploy box.

Undeploying an EJB does not remove the EJB deployment name from WebLogic Server. The EJB remains 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 ServerAdministration 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.

weblogic.deploy update and Targets

In WebLogic Server 6.1, updating an application on any single server instance to which it is targeted causes it to be updated on all servers to which is targeted. For instance, if an application is targeted to a cluster, and you update it on one of the clustered servers instances, the application will be updated on all members of cluster. Similarly, if the application is targeted to a cluster and to a standalone server instance, updating it on the standalone server instance will result in its update on the cluster, and vice versa.

If you want to be able to update an application or component selectively on a subset of the server instances to which it is targeted, deploy unique instances to of the application to different targets.

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. At the same time, a new EJB classloader is created, which loads and maintains the revised EJB implementation classes.

The entire EJB will be reloaded; you cannot redeploy part of the EJB JAR..

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:

1. Choose EJB from the Deployments node in the left pane of the Console.

2. Click the EJB you want to update from the list.

3. Choose the Configuration tab from the dialog in the right pane and update the EJB by checking the deployed box.

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

Deploying Compiled EJB Files

To create compiled EJB 2.0 JAR or EAR files:

1. Compile your EJB classes and interfaces using javac.

2. Package the EJB classes and interfaces into a valid JAR or EAR file.

3. Use the weblogic.ejbc compiler on the JAR file to generate WebLogic Server container classes. For instructions on using ejbc, see ejbc.

To create compile EJBs from previous versions of WebLogic Server:

1. Run weblogic.ejbc against the ejb.jar file to generate EJB 2.0 container-classes.

2. Copy the compiled ejb.jar files into wlserver/config/mydomain/applications.

If you change the contents of a compiled ejb.jar file in applications (by repackaging, recompiling, or copying over the existing ejb.jar), WebLogic Server automatically attempts to redeploy the ejb.jar file using the automatic deployment feature.

Note: Because the automatic redeployment feature uses dynamic deployment, WebLogic Server can only redeploy an EJB's implementation classes. You cannot redeploy an EJB's public interfaces

Deploying Uncompiled EJB Files

The WebLogic Server container also enables you to automatically deploy JAR files that contain uncompiled EJB classes and interfaces. An uncompiled EJB file has the same structure as a compiled file, with the following exceptions:

- You do not have to compile individual class files and interfaces.

- You do not have to use weblogic.ejbc on the packaged JAR file to generate WebLogic Server container classes.

The .java or .class files in the JAR file must still be packaged in subdirectories that match their Java package hierarchy. Also, as with all ejb.jar files, you must include the appropriate XML deployment files in a top-level META-INF directory.

After you package the uncompiled classes, simply copy the JAR into the wlserver\config\mydomain\applications directory. If necessary, WebLogic Server automatically runs javac (or a compiler you specify) to compile the .java files, and runs weblogic.ejbc to generate container classes. The compiled classes are copied into a new JAR file in wlserver/config/mydomain/applications, and deployed to the EJB container.

Should you ever modify an uncompiled ejbc .jar in the applications directory (either by repackaging or copying over the JAR file), WebLogic Server automatically recompiles and redeploys the JAR using the same steps.

Note: Because the automatic redeployment feature uses dynamic deployment, WebLogic Server can only redeploy an EJB's implementation classes. You cannot redeploy an EJB's public interfaces.

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