5
Migrating Enterprise JavaBean Components

This chapter provides the information you need to migrate Enterprise JavaBean components from WebLogic Server to Oracle Application Server. It addresses the migration of simple EJB JARs, as well as J2EE web applications in the form of EAR files or in an exploded directory format.

This chapter contains these topics:

• Introduction

• Migration Steps

• Migrating EJBs in a EAR or JAR File

• Migrating an Exploded EJB Application

• Configuring EJBs using Deployment Descriptors

• Writing Finders for RDBMS Persistence

• WebLogic Query Language (WLQL) and EJB Query Language (EJB QL)

• Message Driven Beans

• Configuring Security

• Migrating Cluster-Aware EJB Applications to OC4J

Introduction

Migrating Enterprise JavaBeans (EJB) from WebLogic Server to Oracle Application Server is straightforward, requiring little or no code changes to the EJBs migrated. Both application servers support the EJB 2.0 specification.

All EJBs written and designed to the EJB 2.0 specifications should work correctly and require minimal migration effort. The primary effort goes into configuring and deploying the applications in the new environment. Only in cases where proprietary extensions are used will the migration effort get complex.

In this chapter we cover the migration of EJBs deployed in the form of EAR files or in an exploded directory format.

Comparison of WebLogic Server and Oracle Application Server EJB Features

Since both WebLogic Server and Oracle Application Server Containers for J2EE (OC4J) have implemented the same versions of the Enterprise JavaBeans specifications, there are no differences between the two in the core areas. The following table summarizes the EJB features available from both application servers:

Table 5-1 Comparison of EJB features 

Feature	Oracle Application Server 10g	WebLogic Server 7.0
Session Beans	Available	Available
Container Managed Persistence Entity Beans (CMP)	Available	Available
Bean Managed Persistence Entity Beans (BMP)	Available	Available
Message Driven Beans	Available	Available
JTA Transactions	Available	Available
JCA Enterprise Connectivity	Available	Available
IMS Messaging	Available	Available
Dynamic EJB Stub Generation	Available	Available
Full EAR File Based Deployment	Available	Available
Automatic Deployment of EJB Applications	Available	Available
Stateless and Stateful EJB Clustering	Available	Available
Local Interfaces for Enterprise JavaBeans	Available	Available
EJB Query Language (EJBQL) - Automatic Code Generation - Oracle and Non    Oracle Database Support - CMP with Relationships	Available	Available
RMI-over-IIOP Support	Available	Available
CMP with Relationships	Available	Available
Concurrency Control - Read-Only Locking - Pessimistic Locking - Optimistic Locking	Available	Available

The following sections go into detail on some of the abovementioned features:

More Efficient Container Managed Persistence

There are two specific facts that reflect the significant performance advantages in using OC4J's container-managed persistence (CMP) implementation compared to WebLogic Server's implementation:

• Automatic Detection of Modified EJBs--When using CMP, Oracle Application Server's J2EE container can automatically detect whether you have modified an EJB and writes the EJB's state to the database; it does an ejbStore only when necessary. WebLogic Server does not provide such automatic detection requiring a user to code is-modified methods which the WebLogic Server container uses to know whether or not to do the ejbStore operation.

• Simple and Complex Database mapping for CMP--When using CMP, Oracle Application Server's J2EE container supports both simple (1:1, 1:many) and complex (many:many) database field mappings very efficiently. In contrast, WebLogic Server provides rudimentary support for simple CMP database field mapping (1:many). For instance, it is difficult to qualify a where clause string in WebLogic Server and this results in doing unnecessary full table scans.

Clustering Support

Application server clustering essentially means the use of a group of application servers that coordinate their actions in order to provide scalable, highly available services in a transparent manner.

From a comparative point of view, Oracle Application Server's J2EE container provides the following facilities:

• Servlet Clustering--Oracle Application Server provides facilities to cluster servlets without requiring any changes to the user's application. The changes are deployment configuration modifications which are transparent to the J2EE application.

• Clustering Architecture and Simplicity--An important differentiator for Oracle Application Server's J2EE container is the ease with which different instances can be clustered and the robustness of the architecture used for clustering. Specifically, Oracle Application Server requires modification of a single XML file (can be done through Application Server Control) to configure various OracleAS instances to belong to a single cluster/island whether they are multiple servers with load balancing on a single machine or multiple servers with load balancing on different machines.

  In contrast, it is much more complex to configure WebLogic Server clusters with load balancing either with multiple instances on one machine or on multiple machines. For instance, if you indicate that your EJBs will be used in a cluster, then you need to specify it during the time the EJB stubs are created using ejbc, which then results in the creation of special cluster-aware classes that will be used for deployment. Overall, Oracle Application Server's J2EE container, together with other Oracle Application Server components, provide a more robust clustering architecture with better ease-of-use.

• Stateless Session Bean Clustering--Oracle Application Server supports clustering of stateless session beans.

• Stateful Session Bean and Entity Bean Clustering--Oracle Application Server supports clustering of stateful session beans and entity beans. Two aspects of design are focused upon:
  • Clustered Performance--Existing clustering facilities such as those in WebLogic Server impose a severe performance penalty when running the instances in a stateful fashion with clustering. As a result, most application developers choose to keep their middle tier completely stateless and write their state to a persistent store, such as a database. In delivering clustered EJBs, Oracle is working on optimizing the EJB clustering implementation to avoid introducing performance penalties.

  • Programmatic Simplicity--Additionally, unlike servlets which have a natural session boundary at which to failover their state, EJBs do not have such a clear boundary. As a result, Oracle Application Server provides simple programmatic facilities to allow developers to use EJB clustering without any changes to their applications.

Scalability and Performance Enhancements

• Entity Bean Scalability--Oracle Application Server enhances entity beans scalability by enabling multiple clients to concurrently look up and invoke methods on the same entity bean instance, using a configurable pool of bean wrapper instances per primary key value.

• Better Concurrency Control--Oracle Application Server introduces a number of new concurrency control options to improve scalability and performance of large J2EE applications:
  • Read-Only Locking--For read-only beans that are not updating the database, the bean developer can instruct the OC4J container to avoid calling or generating ejbStore(). The appropriate isolation mode will be selected, depending on whether the state of the bean can be updated by external systems, such as non-EJB applications using SQL.

  • Pessimistic Locking--Oracle Application Server can serialize access to bean state while providing each client with its own bean instance for deterministic timeout and deadlock detection.

  • Optimistic Locking--Oracle Application Server also supports an alternate locking scheme, which does not use row locking - data consistency will depend on the isolation mode of the bean ("Non- Repeatable-Reads" or "Serializable") and the order in which clients are updating the rows.

WebLogic Server provides a similar set of features.

Security and LDAP Integration

One of the key distinguishing features of OC4J is the seamless integration with Single Sign On (SSO) and Oracle Internet Directory (OID). This is achieved through Oracle's implementation of the Java Authentication and Authorization Service (JAAS) standard. See Oracle Application Server Containers for J2EE User's Guide and Oracle Application Server 10g Security Guide.

WebLogic Server Caveats

The following are additional notes on the WebLogic Server EJB implementation:

• The WebLogic Server implementation of BMP security is not in total compliance with the J2EE specification. According to the specification, an exception needs to be thrown when there is a violation in a BMP security role permission. While OC4J throws an exception in compliance with the specification, WebLogic Server does not do so.

• Unlike WebLogic Server, OC4J does not make it necessary for the developers to create a proprietary XML file for EJB deployment such as the WebLogic Server weblogic-ejb-jar.xml. For OC4J, orion-ejb-jar.xml is created by the OC4J container for internal purposes. Developers have the ability to modify this file, if needed, but it is not necessary for developers to create this file. Hence, OC4J has a simpler process for deployment of EJBs.

EJB Migration Considerations

One of the goals of the EJB initiative is to deliver component portability between different environments not only at source code level, but also at a binary level, to ensure portability of compiled, packaged components. While it is true that EJBs do offer portability, there are still a number of non portable, implementation-specific aspects that need to be addressed when migrating components from one platform to another. Typically, an EJB component requires low level interfaces with the container in the form of stub and skeleton classes that will need to stay implementation-specific. In effect, a clear partitioning between portable and non portable elements of an EJB component can be drawn.

Portable EJB elements include:

• The actual component implementation classes and interfaces (bean class, and remote and home interfaces).

• The assembly and deployment descriptor that describes generic component properties such as JNDI names and transactional attributes.

• Security attributes.

Implementation-specific elements include:

• Low level helper implementation classes (stubs and skeletons) to interface with the host container.

• O-R mapping definitions for CMP entity beans, including search logic for custom finder methods that are declared in an implementation-specific format proprietary to each platform.

• Every component has a set of properties that require systematic configuration at deployment time. For example, mapping of security roles declared in an EJB component to actual users and groups is a task that is systematically performed at deployment time because mappings may not be known in advance. Also, they may have dependencies on the structure and population of the user directory on the target deployment server.

Migration Steps

The tasks involved in migrating EJBs are best analyzed by looking at the steps required for deploying EJBs to an EJB container:

• Setting the EJB deployment descriptors, particularly the vendor-specific deployment descriptors

• Generating EJB container classes

• Loading EJB classes in the server

• Deploying the EJBs in the form of an EAR file or in an exploded directory format

• Configuring the EJBs for deployment at startup

We can address the migration tasks along the same lines.

Setting Deployment Properties

The deployment process starts with a JAR file or a J2EE standard deployment directory that contains the compiled EJB interfaces and implementation classes created by the EJB provider. There should also be an EJB-compliant ejb-jar.xml file that describes the bundled EJB(s). The ejb-jar.xml file and other required XML deployment files, typically the vendor-specific deployment descriptors, must reside in a top level META-INF directory of the JAR file or deployment directory as follows:

Figure 5-1 EJB JAR File Contents and Structure

Text description of the illustration ejbjar.gif

Vendor-specific Deployment Descriptors

WebLogic Server

You would have first created and configured the WebLogic Server-specific and mandatory deployment descriptor, weblogic-ejb-jar.xml, and then added the file to the deployment file or directory. The weblogic-ejb-jar.xml file is used for specifying caching, clustering, and performance behavior.

If you were deploying an entity EJB that used container managed persistence, you would have also included an additional deployment file for specifying the O-R mapping details, or, in other words, the RDBMS-based persistence services in a file called weblogic-cmp-rdbms-jar.xml. A separate file would have been required for each bean that used RDBMS persistence.

OC4J

In the case of OC4J, only one file is required. Via Application Server Control, the OC4J-specific and mandatory deployment descriptor, orion-ejb-jar.xml, is created and added to the deployment file or directory. The orion-ejb-jar.xml file is used for defining caching, clustering, and performance behavior. The details on O-R mapping or the RDBMS-based persistence services are also specified in the orion-ejb-jar.xml file. This is different from WebLogic Server where two separate files were required.

Generating and Deploying EJB Container Classes

The next step after compiling the EJB classes and adding the required XML deployment descriptors (the J2EE deployment descriptor as well as the vendor-specific deployment descriptors) is generation of the container classes that are used to access the EJB. The container classes include implementation of the external interfaces (home and remote) that clients use, as well as the classes that the application server uses, for the internal representation of the EJBs.

WebLogic Server

In WebLogic Server, you would have used the ejbc compiler to generate container classes according to the deployment properties specified in the WebLogic Server-specific XML deployment files. For example, if you indicate that your EJBs are to 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.

Once the container classes have been generated, you need to package the classes into a JAR or EAR file and deploy the classes using the console GUI.

OC4J

For OC4J, explicit compilation is not required. The EJB JAR file is packaged into a EAR file (together with a WAR file, if any). Then, you can use the Application Server Control GUI to specify the EAR file for deployment. The container classes are generated for OC4J and any J2EE Web application in the EAR file is bound to the OC4J container. In lieu of the Application Server Control, you can also use the dcmctl command to deploy the EAR file. Refer to Distributed Configuration Management Reference Guide for more information.

Loading EJB Classes in the Server

WebLogic Server

The final step in deploying an EJB involves loading the generated container classes into WebLogic Server. However, you can prompt WebLogic Server to automatically load EJB classes by starting WebLogic Server. This places the EJB in the deployment directory where it is automatically deployed when the server is started.

OC4J

Similarly, you can specify classes belonging to an application to be loaded when OC4J starts by specifying the auto-start="true" parameter in the <application> tag in server.xml.

Migrating EJBs in a EAR or JAR File

EAR and JAR files containing EJBs which are deployed in WebLogic Server can be migrated to Oracle Application Server. However, you should unarchive and rearchive the EAR file to ensure its contents are complete and that the XML descriptors have the correct entries. Use the following points as a guideline:

• Ensure that the EJB client XML descriptors specify the JNDI names of the EJB stubs. If the client is a Web application, the JNDI names should be specified in web.xml. If the client is standalone, the names should be specified in application-client.xml.

• For the case where the EJB client is standalone, the client classes and XML descriptor file, application-client.jar, should be archived into a JAR file, which in turn should be archived into the EAR file where the EJBs are.

• If the EJB(s) to be migrated from WebLogic are in a JAR file, you need to repackage them in a EAR file with the EAR's application.xml.

• Deploy the EAR file on Oracle Application Server using Application Server Control or dcmctl.

• You do not need to pre-compile EJB stubs using ejbc, rmic, or other such facilities into the client application. The OC4J EJB container generates EJB stubs on demand as it needs them.

Migrating an Exploded EJB Application

EJB applications can also be deployed as a collection of files that use a standard directory structure defined in the J2EE specification. This type of deployment deploys applications in an exploded directory format. Deploying an EJB application in exploded directory format is done most often whilst developing your application and only for standalone OC4J instances. This is because the exploded directory format is more suitable for developers to modify source files and test the application quickly. In Oracle Application Server production environments, however, the application should be packaged in a EAR file and deployed using Application Server Control or dcmctl.

When deploying an exploded directory structure to WebLogic Server, you would have copied the top level directory containing an EJB application in exploded directory format into the mydomain/config/applications/ directory of your WebLogic Server distribution (where mydomain is the name of your WebLogic Server domain). Once copied, WebLogic Server automatically deploys the EJB application.

For OC4J, copy the top level directory containing the EJB application in exploded directory format into the following directory in your OC4J installation:

UNIX:
<ORACLE_HOME>/j2ee/home/applications/

Windows:
<ORACLE_HOME>\j2ee\home\applications\

Then, modify the default J2EE application deployment descriptor, server.xml, located in the <ORACLE_HOME>/j2ee/home/config/ directory in UNIX, or <ORACLE_HOME>\j2ee\home\config\ in Windows, to include your EJB module.

In WebLogic Server, if a file is modified using the administration console, or otherwise, it requires a server restart before the updated configuration is picked up. In the case of OC4J, the timestamp change for server.xml will cause OC4J to effect the changes in the XML file.

Configuring EJBs using Deployment Descriptors

There are two deployment descriptors that are used to configure and deploy EJBs. The first deployment descriptor, ejb-jar.xml, is defined in the EJB specifications and provides a standardized format that describes an EJB application. The second deployment descriptor is a vendor-specific deployment descriptor that maps resources defined in the ejb-jar.xml file to resources in the application server. It is also used to define other aspects of the EJB container such as EJB behavior, caching, and vendor-specific features.

The WebLogic Server specific deployment descriptors are weblogic-ejb-jar.xml and weblogic-cmp-rdbms-jar.xml, and the OC4J-specific deployment descriptor is orion-ejb-jar.xml.

A typical J2EE application directory structure would look like this:

Figure 5-2 Directory Structure of a J2EE Application

Text description of the illustration appdir.gif

The WebLogic Server-specific deployment descriptor, weblogic-ejb-jar.xml, defines EJB deployment descriptor DTDs which are unique to WebLogic Server. The DTD for weblogic-ejb-jar.xml includes elements for enabling stateful session EJB replication, configuring entity EJB locking behavior, and assigning JMS Queue and Topic names for message-driven beans.

Elements configured in the EJB weblogic-ejb-jar.xml include:

• weblogic-enterprise-bean
  • ejb-name

  • entity-descriptor

  • stateless-session-descriptor

  • stateful-session-descriptor

  • message-driven-descriptor

  • transaction-descriptor

  • reference-descriptor

  • enable-call-by-reference

  • jndi-name

• Security-role-assignment

• transaction-isolation

The WebLogic Server-specific deployment descriptor, weblogic-cmp-rdbms-jar.xml, defines deployment properties for an entity EJB that uses WebLogic Server RDBMS-based persistence services.

Each weblogic-cmp-rdbms-jar.xml defines the following persistence options:

• EJB connection pools or data source for CMPs

• EJB field-to-database-element mappings

• Foreign key mappings for relationships

• WebLogic Server-specific deployment descriptors for queries

The OC4J-specific deployment descriptor, orion-ejb-jar.xml, contains extended deployment information for session beans, entity beans, message driven beans, and security.

An entity EJB can save its state in any transactional or non transactional persistent storage (bean-managed persistence), or it can ask the container to save its non-transient instance variables automatically (container-managed persistence). WebLogic Server and OC4J allow both choices and a mixture of the two.

In the case of an EJB that uses container-managed persistence, the weblogic-ejb-jar.xml or the orion-ejb-jar.xml deployment descriptor file specifies the type of persistence services that an EJB uses. In the case of WebLogic Server, the automatic persistence services requires the use of additional deployment files to specify their deployment descriptors, and to define entity EJB finder methods. WebLogic Server RDBMS-based persistence services obtain deployment descriptors and finder definitions from a particular bean using the bean's weblogic-cmp-rdbms-jar.xml file. This configuration file must be referenced in the weblogic-ejb-jar.xml file. In the case of OC4J, the type of persistence service as well as the details regarding the RDBMS-based persistence services are configured and obtained from the same deployment descriptor - orion-ejb-jar.xml.

Some of the attributes such as Development Mode are unique to OC4J.

See Also: Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for more information on the attributes.

Writing Finders for RDBMS Persistence

For EJBs that use RDBMS persistence, WebLogic Server provides a way to write dynamic finders. The EJB provider writes the method signature of a finder in the EJBHome interface, and defines the finder's query expressions in the ejb-jar.xml deployment file. The ejbc compiler creates implementations of the finder methods at deployment time, using the queries in ejb-jar.xml.

The key components of a finder for RDBMS persistence are:

• The finder method signature in EJBHome

• A query stanza defined within ejb-jar.xml

• An optional WebLogic Server query stanza within weblogic-cmp-rdbms-jar.xml

OC4J simplifies the whole process by automatically generating the finder methods.

Specifying the findByPrimaryKey method is easy to do in OC4J. All the fields for defining a simple or complex primary key are specified within the ejb-jar.xml deployment descriptor. To define other finder methods in a CMP entity bean, do the following:

1. Add the finder method to the home interface

2. Add the finder method definition to the OC4J-specific deployment descriptor--the orion-ejb-jar.xml file

WebLogic Query Language (WLQL) and EJB Query Language (EJB QL)

In WebLogic Server 5.1 and 6.0, each finder query stanza in the weblogic-cmp-rdbms-jar.xml file had to include a WLQL string that defines the query used to return EJBs. These releases of WebLogic Server implemented an EJB 1.1 container and did not support standardized EJB QL.

With the emergence of EJB Query Language, which is a standard based on the EJB 2.0 specification, use of WLQL is deprecated. With WebLogic Server 7.0, its EJB container is EJB 2.0 compliant and supports EJB QL. This EJB container additionally provides a WLQL extension to EJB QL. This extension is proprietary to WebLogic Server.

Oracle Application Server provides complete support for EJB QL including the following features:

• Automatic Code Generation: EJB QL queries are defined in the deployment descriptor of the entity bean. When the EJBs are deployed to Oracle Application Server, the container automatically translates the queries into the SQL dialect of the target data store. Because of this translation, entity beans with container-managed persistence are portable -- their code is not tied to a specific type of data store.

• Optimized SQL Code Generation: Further, in generating the SQL code, Oracle Application Server makes several optimizations such as the use of bulk SQL and batched statement dispatch to make database access efficient.

• Support for Oracle and Non-Oracle Databases: Oracle Application Server provides the ability to execute EJB QL against any database - Oracle, MS SQL-Server, IBM DB/2, Informix, and Sybase.

• CMP with Relationships: Oracle Application Server supports EJB QL for both single entity beans and also with entity beans that have relationships, with support for any type of multiplicity and directionality.

For more information on EJB QL in Oracle Application Server, refer to Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.

Message Driven Beans

In WebLogic Server, in addition to the new ejb-jar.xml elements, the weblogic-ejb-jar.xml file includes only one new message-driven-descriptor stanza to associate the message-driven bean with an actual destination in WebLogic Server. The XML element is destination-jndi-name.

In OC4J, to create a message-driven bean, you perform the following steps:

1. Implement a message-driven bean as defined in the EJB specification

2. Create the message-driven bean deployment descriptors

3. Configure the JMS Destination type (queue or topic) in the OC4J JMS XML file, jms.xml.

4. Map the JMS Destination type to the message-driven bean in the OC4J-specific deployment descriptor, orion-ejb-jar.xml

5. If a database is involved in your message-driven bean application, configure the data source that represents your database in data-sources.xml.

6. Create an EJB JAR file containing the bean and the deployment descriptor; once created, configure the application.xml file, create an EAR file, and deploy the EJB in OC4J.

Configuring Security

Security can be handled by the application server, or it can be incorporated programmatically into your EJB classes. Both WebLogic Server and OC4J provide similar support for security such as authentication, authorization, and digital certificates.

See Also: The configuring security chapter in Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide.

Migrating Cluster-Aware EJB Applications to OC4J

Oracle Application Server provides clustering features that are superior to WebLogic Server in performance as well as ease of use. Further, migrating cluster-aware applications from WebLogic Server to OC4J is straightforward.

EJB Clustering in WebLogic Server

In-Memory Replication for Stateful Session EJBs

The WebLogic Server EJB container can replicate the state of an EJB across clustered WebLogic Server instances.

Replication support for stateful session EJBs is transparent to clients of the EJB. When a stateful session EJB is deployed, WebLogic Server creates a cluster-aware EJBHome stub and a replica-aware EJBObject stub for the stateful session EJB. The EJBObject stub maintains a list of the primary WebLogic Server instance on which the EJB instance runs and the name of a secondary WebLogic Server to use for replicating the bean's state.

Each time a client of the EJB commits a transaction that modifies the EJB's state, WebLogic Server replicates the bean's state to the secondary server instance. Replication of the bean's state occurs directly in memory, for best performance in a clustered environment.

Should the primary server instance fail, the client's next method invocation is automatically transferred to the EJB instance on the secondary server. The secondary server becomes the primary WebLogic Server for the EJB instance, and a new secondary server is used to account for the possibility of additional failovers. Should the EJB's secondary server fail, WebLogic Server enlists a new secondary server instance from the cluster.

By replicating the state of a stateful session EJB, clients are generally guaranteed to have the last committed state of the EJB, even if the primary WebLogic Server instance fails. However, in certain rare failover scenarios, the last committed state may not be available. This can happen when:

• A client commits a transaction involving a stateful EJB, but the primary WebLogic Server fails before the EJB's state is replicated. In this scenario, the client's next method invocation will work against the previous committed state, if available.

• A client creates an instance of a stateful session EJB and commits an initial transaction, but the primary WebLogic Server fails before the EJB's initial state can be replicated. In this scenario the client's next method invocation will fail to locate the bean instance, because the initial state could not be replicated. The client would need to recreate the EJB instance using the clustered EJBHome stub and restart the transaction.

• Both the primary and secondary servers fail. In this scenario the client would need to recreate the EJB instance and restart the transaction.

Requirements and Configuration

To replicate the state of a stateful session EJB in a WebLogic Server cluster, ensure that the cluster is homogeneous for the EJB class. In other words, deploy the same EJB class to every WebLogic Server instance in the cluster, using the same deployment descriptors. In-memory replication is not supported for heterogeneous clusters.

By default, WebLogic Server does not replicate the state of stateful session EJB instances in a cluster. To enable replication, set the replication type deployment parameter to InMemory in the weblogic-ejb-jar.xml deployment file. For example:

<stateful-session-clustering>
...
...
...
<replication-type>InMemory</replication-type>
</stateful-session-clustering>

EJB Clustering in Oracle Application Server

EJB clustering in Oracle Application Server provides EJB load balancing and failover. For Oracle Application Server, the mechanisms used to achieve these are different from HTTP session load balancing and failover. For EJBs, load balancing redirection is performed by the EJB client stubs and state replication for failover is done without using cluster islands (a future release of Oracle Application Server will implement cluster islands for EJBs).

To create an EJB cluster, you need to specify which OC4J nodes are part of the cluster and configure each of them with the same multicast address, username, and password. The EJBs to be clustered can then be deployed to each of these nodes. Configuring all nodes in the cluster with the same multicast username and password allows authentication to all nodes with a single username/password combination. If you use a different username/password combination with the same multicast address, another cluster is actually defined. The Application Server Control provides a user interface to specify the multicast username and password.

Load Balancing

Load balancing for EJBs is performed at the EJB client end. The client stubs obtain the addresses of nodes in the cluster in one of two ways: static discovery or dynamic discovery. Once all nodes in the same cluster are known, a client stub selects one at random. Load balancing is performed using a random methodology.

Static and dynamic discovery is performed as follows:

Static Discovery

At lookup time, the JNDI addresses of all nodes in the cluster are provided in the lookup URL property. This requires knowledge of the node name and ormi port for each node. For example:

java.naming.provider.url = ormi://serverA:23791/ejb, ormi://serverB:23792/ejb,
                           ormi://serverC:23791/ejb;

Dynamic Discovery

For dynamic discovery, at the first lookup made, the first node that is contacted communicates with the other nodes with the same multicast address and username/password. The ormi addresses of these nodes are retrieved and returned to the client stubs, which select one of the addresses at random. To enable dynamic discovery, "lookup:" is inserted before the ormi URL:

ic.lookup("lookup:ormi://serverA:23791/ejb");

Failover

Depending on the type of EJB that is clustered, failover in an EJB cluster is achieved by request redirection and state replication.

Stateless Session EJBs

Load balancing and failover for stateless session EJBs is performed by EJB client stubs by redirecting requests to randomly picked nodes after the nodes have been discovered statically or dynamically. Because of the stateless nature of the EJBs, replication of bean state is not required.

Stateful Session EJBs

Load balancing for stateful session EJBs is the same as for stateless session EJBs. For failover, state replication is required, and by default, is replicated to all nodes in the cluster at the end of every method call to each EJB instance. Though reliable, this obviously incurs a significant amount of CPU overhead in all the nodes and degrades performance. Hence, two more replication modes are provided to allow replication without compromising performance significantly: JVM termination and stateful session context replication modes.

The JVM termination mode replicates the state of all stateful session EJBs to one other node when the JVM executing these EJBs terminates gracefully. The replication logic uses JDK termination hooks (JDK 1.3 or later is required). This mode is the most performant among all because replication is done only once. However, reliability is not the best as it is dependent on the JVM's ability to shutdown properly.

Stateful session context mode replicates state programatically. An OC4J-proprietary class, com.evermind.server.ejb.statefulSessionContext, is provided to allow you to specify the information to be replicated. By setting this information as parameters for the setAttribute method, this information can be replicated to all nodes in the EJB cluster. Hence, EJB providers have more control on when and what to replicate.

Entity EJBs

Replication for entity EJBs allows EJB state to be stored in a database. Each time the state of an entity EJB changes, it is updated in the database. The entity EJB that changes the state notifies the other nodes in the cluster that their equivalent entity EJBs are out-of-date. If the node hosting the "up-to-date" EJB fails, the client stub redirects to another node and the out-of-date entity EJB in that node resynchronizes its state with the information in the database.

See Also: Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for information on how to configure EJB clustering.

JNDI Namespace Replication

When EJB clustering is enabled, JNDI namespace replication is also enabled between the OC4J instances that have a role in the EJB cluster. New bindings to the JNDI namespace in one OC4J instance are propagated to other OC4J instances that are participating in the EJB cluster. Rebindings and unbindings are not replicated.

JNDI replication is completed outside the scope of OC4J islands. In other words, multiple islands in an OC4J instance have visibility into the same replicated JNDI namespace. For more information see the Oracle Application Server Containers for J2EE Services Guide.