Packaging EJBs for the WebLogic Server Container

 

The following sections describe how to package EJBs into a WebLogic Server container for deployment. They includes a description of the contents of a deployment package, including the source files, deployment descriptors, and the deployment mode.

• Required Steps for Packaging EJBs

• Reviewing the EJB Source File Components

• WebLogic Server EJB Deployment Files

• Specifying and Editing the EJB Deployment Descriptors

• Creating the Deployment Files

• Setting WebLogic Server Deployment Mode

• Packaging EJBs into a Deployment Directory

• Compiling EJB Classes and Generating EJB Container Classes

• Loading EJB Classes into WebLogic Server

• Specifying an ejb-client.jar

• Manifest Class-Path

 

---

Required Steps for Packaging EJBs

Packaging EJBs for deployment to WebLogic Server in an EJB container involves the following steps:

1. Review the EJB source file components.

2. Create the EJB deployment files.

3. Edit the EJB deployment descriptors.

4. Set the deployment mode.

5. Generate the EJB container classes.

6. Package the EJBs into a JAR or EAR file.

7. Load EJB classes into WebLogic Server.

 

---

Reviewing the EJB Source File Components

To implement entity and session beans, use the following components:

Component	Description
Bean Class	The bean class implements the bean's business and life cycle methods.
Remote Interface	The remote interface defines the beans's business logic that can be access from applications outside of the bean's EJB container.
Remote Home Interface	The remote home interface defines the bean's file cycle methods that can be accessed from applications outside of the bean's EJB container.
Local Interface	The local interface defines the bean's business methods that can be used by other beans that are co-located in the same EJB container.
Local Home Interface	The local home interface defines the bean's life cycle methods that can be used by other beans that are co-located in the same EJB container.
Primary Key	The primary key class provides a pointer into the database. Only entity beans need a primary key.

 

---

WebLogic Server EJB Deployment Files

Use the following WebLogic Server deployment files to specify the deployment descriptor elements for the EJB.

• ejb-jar.xml

• weblogic-ejb-jar.xml

• weblogic-cmp-rdbms-jar.xml (optional, for CMP only)

The deployment files become part of the EJB deployment when the bean is compiled. The XML deployment descriptor files should contain the minimum deployment descriptor settings for the EJB. Once the file exists, it can later be edited using the instructions in Specifying and Editing the EJB Deployment Descriptors. The deployment descriptor files must conform to the correct version of the Document Type Definition (DTD) for each file you use. All element and sub element (attribute) names for each of the EJB XML deployment descriptor files are described in the file's Document Type Definition (DTD) file. For a description of each file, see the following sections.

ejb-jar.xml

The ejb-jar.xml file contains the Sun Microsystem-specific EJB DTD. The deployment descriptors in this file describe the enterprise bean's structure and declares its internal dependences and the application assembly information, which describes how the enterprise bean in the ejb-jar file is assembled into an application deployment unit. For a description of the elements in this file, see the JavaSoft specification.

weblogic-ejb-jar.xml

The weblogic-ejb-jar.xml file contains the WebLogic Server-specific EJB DTD that defines the caching, clustering, and performance behavior of EJBs. It also contains descriptors that map available WebLogic Server resources to EJBs. WebLogic Server resources include security role names and data sources such as JDBC pools, JMS connection factories, and other deployed EJBs. For a description of the elements in this file, see weblogic-ejb-jar.xml Document Type Definitions.

weblogic-cmp-rdbms.xml

The weblogic-cmp-rdbms.xml file contains the WebLogic Server-specific EJB DTD that defines container-managed persistence services. Use this file to specify how the container handles synchronizing the entity beans's instance fields with the data in the database. For a description of the elements in this file, see weblogic-cmp-rdbms- jar.xml Document Type Definitions.

Relationships Among the Deployment Files

Descriptors in weblogic-ejb-jar.xml are linked to EJB names in ejb-jar.xml, to resource names in a running WebLogic Server, and to persistence type data defined in weblogic-cmp-rdbms-jar.xml (for entity EJBs using container-managed persistence). The following diagram shows the relationship among the deployment files and WebLogic Server.

Figure 6-1 The relationship among the components of the deployment files.

 

---

Specifying and Editing the EJB Deployment Descriptors

You specify or edit EJB deployment descriptors by any of the following methods:

• Using a text editor to manually editing the bean's deployment files. For instructions on manually editing the deployment files, see Manually Editing EJB Deployment Descriptors.

• Using the EJB Deployment Descriptor Editor in the WebLogic Server Administration Console to edit the bean's deployment files. For instructions on using the EJB Deployment Descriptor Editor, see Using the EJB Deployment Descriptor Editor.

• Using a WebLogic Server command line utility tool called DDConverter to convert EJB 1.1 deployment descriptors to EJB 2.0 XML. For instructions on using the DDConverter tool, see DDConverter.

 

---

Creating the Deployment Files

You create the basic XML deployment files for the EJB that conforms to the correct version of the Document Type Definition (DTD) for each file. You can use an existing EJB deployment file as a template or copy one from the EJB examples in your WebLogic Server distribution:

wlserver\samples\examples\ejb20

Manually Editing EJB Deployment Descriptors

To edit XML deployment descriptor elements manually:

1. Use an ASCII text editor that does not reformat the XML or insert additional characters that could invalidate the file.

2. Open the XML deployment descriptor file that you want to edit.

3. Type in your changes. Use the correct case for file and directory names, even if your operating system ignores the case.

4. To use the default value for an optional element, either omit the entire element definition or specify a blank value, as in:

   <max-beans-in-cache></max-beans-in-cache>
   

Using the EJB Deployment Descriptor Editor

To edit the EJB deployment descriptors in the WebLogic Server Administration Console:

1. Start WebLogic Server.

2. Start the Administration Console and select EJB from the right pane.

3. In the left pane, choose the Deployments node under your server domain.

4. Expand the Deployments node and choose EJB.

5. From the expanded list of deployed EJBs, right-click on the bean to be edited.

6. Click Edit EJB Descriptor...

7. When the EJB Deployment Descriptor Editor is displayed, click the chosen EJB to expand the node.

   You should see the following items that represent the EJB deployment descriptor files:

   • EJB Jar: represents the ejb-jar.xml file deployment descriptors for this EJB.

   • WebLogic EJB Jar: represents the weblogic-ejb-jar.xml file deployment descriptors for this EJB.

   • CMP: represents the weblogic-cmp-rdbms-jar.xml file deployment descriptors for this EJB.

8. Expand the node for the deployment descriptors that you want to edit.

   The current settings for the deployment descriptor file that you selected appear in the left pane. When you right-click on an item in the list, a dialog window for that item appears in the right pane.

9. Clicking on the circles displays a dialog window in the right pane with various settings.

   You can change the settings in the dialog window to edit those deployment descriptors.

10. Clicking on the folders displays tables in the right pane where you can view your settings.

    Here you can usually configure a new descriptor or customize your view of the existing settings. If an item in the table is underlined, you can click on it to display a dialog where you can change the settings.

11. By right-clicking on deployment descriptor items in the right pane, you can also delete descriptors.

Note: For more information on the EJB deployment descriptors, see either the online help in the Administration Console or weblogic-ejb-jar.xml Document Type Definitions, and weblogic-cmp-rdbms- jar.xml Document Type Definitions.

 

---

Setting WebLogic Server Deployment Mode

You deploy the enterprise archive file (EAR) or EJB to WebLogic Server by one of the following methods:

• Automatic mode, which automatically deploys the EJB or EAR to the applications directory on your server

• Production mode, which deploys the EJB or EAR as specified in the config.xml file.

Using the Automatic Mode for Deployment

The automatic mode deployment option is the default. This feature automatically polls the application directory of the active server during startup and while the server is running, to determine whether an EJB deployment has changed. If a deployment has changed, it is automatically deployed when the server is polled. Use the applications directory for EJBs or EARs that you want to deploy in development mode. Once deployed, these EJBs/EARs are automatically persisted to the config.xml file.

WebLogic Server also checks the contents of applications every ten seconds to determine whether an EJB deployment has changed. If a deployment has changed, it is automatically redeployed using the dynamic deployment feature.

Automatically Deploying the EJB Examples

The EJB examples shipped with WebLogic Server are automatically deployed in the wlserver/config/applications directory.

• The examples in the wlserver/samples/examples/ejb directory are shipped built and automatically deploy when the examples server is started.

• The examples in the wlserver/samples/examples/ejb20 directory are shipped pre-built and need to be built before they can be deployed to the server.

Using the Production Mode for Deployment

The production mode deployment option turns off automatic deployment. When production deployment mode is enabled, applications specified in the config.xml file are deployed when the server is started.

To enable this mode, at the command line set the following to true:

-d production mode enabled true 

For more information on this production mode, see "Starting the WebLogic Administration Server from the Command Line" in startstop.html of the Administration Guide.

 

---

Packaging EJBs into a Deployment Directory

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. The following diagram shows the first stage of packaging the the EJB and the deployment descriptor files into a deployment directory or JAR file.

Figure 6-2 Packaging the EJB classes and deployment descriptors into a deployment directory

As is, the basic JAR or deployment directory cannot be deployed to WebLogic Server. You must first create and configure the WebLogic-specific deployment descriptor elements in the weblogic-ejb-jar.xml file, and add that file to the deployment directory or ejb.jar file. For more information on creating the deployment descriptor files, see WebLogic Server EJB Deployment Files.

If you are deploying an entity EJB that uses container-managed persistence, you must also add the WebLogic -specific deployment descriptor elements for the bean's persistence type. For WebLogic Server container-managed persistence (CMP) services, the file is generally named weblogic-cmp-rdbms-jar.xml. You require a separate file for each bean that uses CMP. 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 any of the deployment descriptor files needed for your EJB, you must manually create one. The best method is to copy an existing file and edit the settings to conform to the needs of your EJB. Use the instructions in Specifying and Editing the EJB Deployment Descriptors to create the files.

ejb.jar file

You create the ejb.jar file with the Java Jar utility (javac). This utility bundles the EJB classes and deployment descriptors into a single Java ARchive (JAR) file that maintains the directory structure. The ejb-jar file is the unit that you deploy to WebLogic Server.

 

---

Compiling EJB Classes and Generating EJB Container Classes

For part of the process of building your deployment unit, you need to compile your EJB classes, add your deployment descriptors to the deployment unit, and generate the container classes used to access the deployment unit.

1. Compile the EJB classes using javac compiler from the command line.

2. Add the appropriate XML deployment descriptor files to the compiled unit using the guidelines in WebLogic Server EJB Deployment Files.

3. Generate the container classes that are used to access the bean using ejbc.

   Container classes include both the internal representation of the EJB that WebLogic Server uses, as well as implementation of the external interfaces (home, local, and/or remote) that clients use.

The ejbc compiler generates container classes according to the deployment descriptors you have specified in WebLogic-specific XML deployment descriptor 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 ejbcfor more information.

The following figure shows the container classes added to the deployment unit when the JAR file is generated

Figure 6-3 Generating the EJB container classes

 

Once you have generated the deployment unit, you can designate the file extension as either a JAR, EAR, or WAR archive.

 

---

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 automatically 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.

 

---

Specifying an ejb-client.jar

WebLogic Server supports the use of ejb-client.jar files.

The ejb-client.jar contains the home and remote interfaces, the primary key class (as applicable), and the files they reference. WebLogic Server does not add files referenced in your classpath to ejb-client.jar. This enables WebLogic Server to add necessary custom classes to the ejb-client.jar without adding generic classes such as java.lang.String.

For example, the ShoppingCart remote interface might have a method that returns an Item class. Because this remote interface references this class, and it is located in the ejb-jar file, it will be included in the client jar.

You configure the creation of an ejb-client.jar file in the bean's ejb-jar.xml deployment descriptor file.When you compile the bean with ejbc, WebLogic Server creates the ejb-client.jar.

To specify an ejb-client.jar:

1. Compile the bean's Java classes into a directory, using the javac compiler from the command line.

2. Add the EJB XML deployment descriptor files to the compiled unit using the guidelines in WebLogic Server EJB Deployment Files.

3. Edit the ejb-client-jar deployment descriptor in the bean's ejb-jar.xml file, as follows, to specify support for ejb-client.jar:

   <ejb-client-jar>ShoppingCartClient.jar</ejb-client-jar>

4. Generate the container classes that are used to access the bean using weblogic.ejbc and create the ejb-client.jar using the following command:

   $ java weblogic.ejbc <ShoppingCart.jar>

   Container classes include both the internal representation of the EJB that WebLogic Server uses, as well as implementation of the external interfaces (home, local, and/or remote) that clients use.

External clients can include the ejb-client.jar in their classpath. Web applications would include the ejb-client.jar in their /lib directory.

Note: WebLogic Server classloading behavior varies, depending on whether or not the client is stand-alone. Stand-alone clients with access to the ejb-client.jar can load the necessary classes over the network. However, for security reasons, programmatic clients running in a server instance cannot load classes over the network.

 

---

Manifest Class-Path

Use the manifest file to specify that a JAR file can reference another JAR file. Standalone EJBs cannot use the Manifest Class-Path. It is only supported for components that are deployed within an EAR file. The clients should reference the client.jar in the classpath entry of the manifest file.

To use the manifest file to reference another JAR file:

1. Specify the name of the referenced JAR file in a Class-Path header in the referencing JAR file's Manifest file.

   The referenced JAR file is named using a URL relative to the URL of the referencing JAR file.

2. Name the manifest file META-INF/MANIFEST.MF in the JAR file

3. The Class-Path entry in the Manifest file is as follows:

   Class-Path: AAyy.jar BByy.jar CCyy.jar.

Note: The entry is a list of JAR files separated by spaces.

To place the home/remote interfaces for the EJB in the classpath of the calling component:

1. Use ejbc to compile the EJB into a JAR file.

2. Create a client.jar file. For instructions on using the client.jar, see Specifying an ejb-client.jar.

3. Place the client.jar, along with all the clients of the bean in an EAR.

4. Reference the EAR in the manifest file.

.