|
|
|
|
| |
Deploying EJBs in WebLogic Server
Required steps for deploying EJBs
Generating EJB container classes
Loading EJB classes into WebLogic Server
Overview of WebLogic Server classloading
Deploying EJBs in a running WebLogic Server (Hot Deployment)
Hot deploy concepts and restrictions
WebLogic Server provides several utilities and methods for deploying EJB 1.1-compliant .jar files. EJB Deployer 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 EJB Deployer for complete information about using the EJB Deployer utility.
Required steps for deploying EJBs
Deploying EJBs in WebLogic Server involves three distinct steps:
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 EJB Deployer 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 EJB Deployer 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 EJB Deployer 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 EJB Deployer. 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:
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:
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.
Also, network classloading is not designed to solve the problem of testing many versions of a continually changing class on the server. The network classloaders will not automatically fetch the new class if the class is changed only on the server. When a server-side class changes, a reload of the dependent applications is necessary.
To deploy EJBs at automatically when WebLogic Server starts:
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:
Both the deploy command shell utility and the EJB Deployer 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 EJB Deployer 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:
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:
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.
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
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
% java weblogic.deploy -port 7001 -host localhost deploy
weblogicpwd CMP_example
c:\weblogic\myserver\unjarred\containerManaged\
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.
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.
|