bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming WebLogic Enterprise JavaBeans

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

- Redeploying EJBs

- Deploying Compiled EJB Files

- Deploying Uncompiled EJB Files

- Deployment Restriction with Container Managed Relationships

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 Specifying and Editing the EJB Deployment Descriptors 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 classes places the JAR file in the deployment directory. If you want the EJB to automatically deploy when WebLogic Server starts, place the EJB you want to deploy in the following directory:

   mydomain\applications directory

   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 left pane, click Deployments and then the EJB node.

   A list of the EJB deployments for the server displays under the node.

Deploying EJBs in Different Applications

When you deploy EJBs with remote calls to each other in different applications, you cannot use call-by-reference to invoke the EJBs. Instead, you use pass-by-value. You should place components that commonly interact with each other 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:

1. Start the WebLogic Server Administration Console.

2. Select the Domain in which you will be working.

3. In the left pane of the Console, click Deployments.

4. In the left pane of the Console, click EJB. A table displays in the right pane of the Console showing all the deployed EJBs.

5. Select the Configure a new EJB option.

6. Locate the EAR, WAR or JAR file you would like to configure. You can also configure an exploded application or component directory. Note that WebLogic Server will deploy all components it finds in and below the specified directory.

7. Click [select] to the left of a directory or file to choose desired file and proceed to the next step.

8. Select a Target Server from among Available Servers.

9. Enter a name for the EJB or application in the provided field.

10. Click Configure and Deploy to install the EJB or application. The Console will display the Deploy panel, which lists deployment status and deployment activities for the EJB.

11. Using the available tabs, enter the following information:

    - Configuration—Edit the staging mode and enter the deployment order.

    - Targets—Indicate the Targets-Server for this configured EJB or application by moving the server from the Available list to the Chosen list.

    - Deploy—Deploy the EJB or application to all or selected targets or undeploy it from all or selected targets.

    - Monitoring—Enable session monitoring for the EJB or application.

    - Notes—Enter notes related to the EJB or application.

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 ejbc before deploying it, to ensure that the generated classes copied to all server instances available to all nodes in the cluster.

For more information on pinned deployments, see Setting Up WebLogic Clusters.

Viewing Deployed EJBs

To view deployed EJBs:

1. Start the Administration Console.

2. Click the Deployments node in the left pane and then choose the EJB sub-node. A list of EJBs deployed on your domain displays under EJB and in the right pane.

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 WebLogic Server Administration Console:

1. Select the component in the left panel.

2. In the component Deployments table, select the component to undeploy.

3. Click Apply.

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.

Redeploying EJBs

When you change a deployed EJB's classes, these changes are not reflected in WebLogic Server until:

- You reboot the server (if the JAR or directory is to be automatically deployed),

  or

- you redeploy the EJB deployment.

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

The Redeploy Process

When you redeploy, the classes currently loaded 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 classes.

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

Steps to Redeploy

You can redeploy an EJB that is standalone or part of an application, using the weblogic.Deployer tool or via the Administration Console.

To redeploy using weblogic.Deployer:

1. Use the -deploy flag:

   java weblogic.Deployer -deploy ejb_name

To redeploy via the WebLogic Server Administration Console:

1. Choose EJB from the Deployments node in the left pane of the Console, or—if the EJB is part of an application—choose Applications, then the application name.

2. Click the name of the EJB you want to redeploy.

3. Click the Deploy tab in the right pane.

4. Click Redeploy.

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

   >     mydomain\applications\DefaultWebApp directory

Note: You should manually recompile any EJBs from previous versions before deploying then to the EJB container. Otherwise, WebLogic Server automatically recompiles the EJBs and if there are errors, the output from the compile is sent to a separate log file.

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.

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 mydomain\applications\DefaultWebApp, and deployed to the EJB container.

Should you ever modify an uncompiled ejb .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.

Deployment Restriction with Container Managed Relationships

Two EJBs that have a container-managed relationship must be deployed in the same JAR file. For more information on container-managed relationships, see Container-Managed Relationships.