Skip Headers

Oracle® Application Server 10 g Migrating From WebLogic 10g Release 3 (10.1.3) B16027-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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 session and entity EJBs, as well as J2EE Web applications in the form of EAR files or in an exploded directory format.

This chapter contains these topics:

- Section 5.1, "Introduction"

- Section 5.2, "Migration Approach"

- Section 5.3, "Migrating EJBs in a EAR or JAR File"

- Section 5.4, "Migrating an Exploded EJB Application"

- Section 5.5, "Writing Finders for RDBMS Persistence"

- Section 5.6, "WebLogic Query Language (WLQL) and EJB Query Language (EJB-QL)"

- Section 5.7, "Message Driven Beans"

## 5.1 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 with OC4J extending support to EJB 2.1 and EJB 3.0 Early Draft Review.

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.

### 5.1.1 Comparison of WebLogic Server and Oracle Application Server EJB Features

Since WebLogic Server 8.1 supports EJB 2.0 and Oracle Containers for J2EE (OC4J) supports EJB 2.1 and the EJB 3.0 Early Draft Review, some differences exist in the two implementations. The following table summarizes the EJB features available from both application servers.

Table 5-1 Comparison of EJB features

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

#### 5.1.1.1 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 invokes `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 perform `ejbStore` operations.

- Simple and Complex Database mapping for 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). Additionally, qualifying a `where` clause string in WebLogic Server results in unnecessary full table scans.

#### 5.1.1.2 Clustering Support

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

- 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 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 Console) to configure various Oracle Application Server instances to belong to a single cluster whether they are multiple servers with load balancing on a single machine or multiple servers with load balancing on several 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 are to be used in a cluster, you need to specify that fact during the time the EJB stubs are created using `appc`, which then results in the creation of special cluster-aware classes that are 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.

- Stateful session bean and entity bean clustering - Oracle Application Server supports clustering of stateful session beans and entity beans. The following 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. By design, OC4J's clustering implementation is optimized to avoid introducing performance penalties.

  - programmatic simplicity - Unlike servlets which have a natural session boundary at which to fail over 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.

See Also: Oracle Application Server High Availability Guide Oracle Application Server Containers for J2EE Configuration and Administration Guide

#### 5.1.1.3 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 is 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 depends on the isolation mode of the bean ("Non- Repeatable-Reads" or "Serializable") and the order in which clients update the rows.

WebLogic Server provides a similar set of features.

### 5.1.2 EJB Migration Considerations

In practice, the process of migrating EJBs from WebLogic Server to Oracle Application Server does not entail any major hurdles. Generally, little or no code modifications are required. If there are modifications, these are often related to JNDI portability issues regarding instantiation of JNDI initial contexts and JNDI lookup names to use for data sources and EJB home and remote interfaces.

Migration then consists of performing implementation-specific adaptation tasks for container class generation and object-relational (O-R) mapping definitions, and customization of deployment properties, if required.

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 the binary level. Another goal is to ensure portability of compiled and uniformly 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 implementation to another. Typically, an EJB component requires low level interfaces with the container in the form of stub and skeleton classes which 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 descriptors that describe generic component properties such as JNDI names and transactional attributes.

- Security attributes.

Implementation-specific elements include:

- Low-level helper implementation classes (stubs and skeletons) that 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.

#### 5.1.2.1 Global JNDI Lookups and Oracle Application Server

When migrating an EJB (or any other object that performs JNDI lookups) from WebLogic Server to OC4J, global JNDI lookup needs to be enabled for OC4J if the EJB performs JNDI lookups to resources in other applications other than its own. JNDI lookups in WebLogic Server have a global context whereas the default configuration of OCJ4 allows lookups within the application scope only. Hence, if an EJB performs a lookup to another application in OC4J with default configuration, a `NameNotFoundException` is thrown.

To enable global JNDI lookups for an OC4J instance, set the `global-jndi-lookup-enabled` attribute to `true` in the `<application-server>` element of `server.xml`. For JNDI names to resolve properly to their bound classes, the target application's classes must be in the classpath of the application attempting the lookup. This can be accomplished in by performing either one of the following tasks:

- Put the target application's JAR archive in the `$ORACLE_HOME/j2ee/home/applib` common classes directory.

- Put the target application's JAR archive in a shared library location. A shared library can be defined in the `<shared-library>` element of `server.xml`. See Oracle Application Server Containers for J2EE Configuration and Administration Guide for more information on this element.

For further information on Oracle Application Server JNDI, see Oracle Containers for J2EE Services Guide.

#### 5.1.2.2 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 to provide their own EJB configuration data, if needed, but it is not necessary for developers to explicitly create this file. Any custom EJB configuration information in the `weblogic-ejb-jar.xml` and `weblogic-cmp-rdbms-jar.xml` files can be migrated to `orion-ejb-jar.xml` using XSLT or the Oracle JDeveloper Migration Assistant. See Section 5.2.3.1.

## 5.2 Migration Approach

The overall migration approach EJBs is outlined in this section. Session EJBs migrate easier than entity EJBs since there are no persistence-level issues to be considered. Standard J2EE components and deployment descriptors (`ejb-jar.xml`) require almost no modifications.

For both session and entity EJBs, implementation-specific dependencies require modification. These include (as mentioned earlier):

- Hard-coded JNDI context access and lookups.

- Data source JNDI names and lookups.

- Implementation-specific adaptations for O-R mapping, container class generation, and customization of deployment properties.

- Modification and regeneration of the EJB archive file (JAR).

### 5.2.1 Migrating Session EJBs

Migration of session beans involves the Ògeneric stepsÓ of EJB migration. These are:

1. Make any appropriate code changes as follows:

   - Remove and replace all proprietary APIs and flags.

   - Remove implementation-specific hard-coded JNDI and JDBC references.

2. Adjust deployment properties as follows:

   - Recreate XML deployment descriptors where needed. See Section 5.2.3.

   - Customize runtime properties for the OC4J environment.

   - Re-map EJB JNDI names if necessary.

3. Save the updated EJB archive files (`.jar` and `.ear`).

4. Deploy the archive file to OC4J.

### 5.2.2 Migrating Entity EJBs

The migration of entity EJBs involves the Ògeneric stepsÓ of session EJB migration (Section 5.2.1) and the following steps specific to entity EJB migration:

1. Remove and replace any implementation-specific JNDI or data source lookups.

2. Rewrite any specific database deployment descriptors:

   - `weblogic-ejb-jar.xml` and `weblogic-cmp-rdbms-jar.xml` (for container-managed persistence) to `orion-ejb-jar.xml`

3. Remove and replace all proprietary APIs and flags for transaction management, locking, and caching.

In addition to the above steps, take into consideration the support for different EJB specification levels from one container to another. Differences in the specifications may require code changes. For example, in EJB 1.1 (supported by WebLogic Server 7.0), the `ejbRemove()` method of local entity EJBs requires `javax.rmi.RemoteException` to be thrown. Whereas for EJB 2.0 (supported by Oracle Application Server), `ejbRemove()` should only throw `javax.ejb.EJBException`. If the local entity EJB is migrated from WebLogic Server 7.0 to Oracle Application Server 10g Release 3 (10.1.3) without changing the exception thrown by `ejbRemove()`, a compilation exception occurs when the EJB is deployed.

#### 5.2.2.1 EJBs with Bean-Managed Persistence (BMP)

The steps for migrating EJBs with BMP are:

1. Check code for specific JNDI references:

   - Re-map each JNDI name as appropriate.

   - Walk-through the code of the entity bean class to check the data access code for any implementation-specific dependencies such as hard-coded JNDI environment properties or implementation-dependent issues such as data source JNDI names. Modify and regenerate the code and EJB archive file as required.

2. Adjust deployment properties as required.

   If using Oracle JDeveloper, import the EJB archive into EJB Configurator. Then:

   - Adjust deployment properties as required.

   - Save the updated EJB archive file.

   - Deploy to OC4J.

   - Re-map the EJB's JNDI name.

3. Generate the low-level container classes for OC4J.

4. Customize deployment-time properties of the EJB(s) if required.

The main single point for concern is JNDI context access and the data source lookup procedure. It is, therefore, necessary and advisable to:

- Ensure that the code that retrieves the JNDI context does not pass any implementation-specific properties to the `InitialContext` class constructor.

- Modify code that uses any hard-coded references to data source JNDI names so that the data source JNDI name is obtained indirectly by looking up a specific environment entry for this EJB. Doing so will later make it straightforward to amend the data source JNDI name in the EJB's deployment descriptor when required.

#### 5.2.2.2 EJBs with Container-Managed Persistence (CMP)

With CMP entity beans, the EJB container is responsible for managing the persistent state of an object using O-R mappings between the attributes of the object that need to be persisted and the corresponding columns of a database table that hold this object's attribute values.

Unfortunately, the EJB specification makes no provisions for a standard way to define O-R mappings. Therefore, it is left to EJB container vendors to store this information in the EJB archive file using a proprietary format.

Consequently, O-R mapping definitions stored in the EJB archive file are not compatible between EJB vendors, and mapping information must be regenerated as part of the migration process.

The overall tasks for migrating EJBs with CMP are:

- Since O-R mapping definitions are vendor dependent, the mapping definitions in `weblogic-ejb-jar.xml` and `weblogic-cmp-rdbms-jar.xml` need to be re-created in `orion-ejb-jar.xml`. Procedures are provided in Section 5.2.3, "Migrating Deployment Descriptors".

- Resolve differences in container-managed relationships (CMR) mapping.

- Configure OC4J data sources for persistence.

- Remove WebLogic Server-specific container stub and skeleton classes, and generate the equivalent OC4J stub & skeleton classes.

### 5.2.3 Migrating 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-1 Directory Structure of a J2EE Application

Description of "Figure 5-1 Directory Structure of a J2EE Application"

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

Standard J2EE descriptors in `ejb-jar.xml` need little changes and should are migrated easily. The implementation-specific J2EE descriptors in the following files need to be modified:

- `weblogic-ejb-jar.xml`

- For CMP EJBs, descriptors in `weblogic-cmp-rdbms-jar.xml` need to be ported to `orion-ejb-jar.xml` (OC4J-specific).

Definitions of OC4J-specific XML descriptors can be found in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide or through online DTD files. These files are at:

    http://xmlns.oracle.com/ias/dtds/orion-application.dtd
    http://xmlns.oracle.com/ias/dtds/orion-application.dtd
    http://xmlns.oracle.com/ias/dtds/orion-ejb-jar.dtd
    http://xmlns.oracle.com/ias/dtds/orion-web.dtd
    http://xmlns.oracle.com/ias/dtds/orion-application.dtd

Migration of deployment descriptors can be accomplished through one of the following ways:

- Manual creation of platform-specific deployment descriptor files using a text editor of your choice.

- Extensible Stylesheet Language Transformation (XSLT) - Oracle provides BEA, JBoss & Borland. Oracle's XSLT transformers are sample code and results will need some modification.

- Use Oracle JDeveloper to assist in the authoring of deployment descriptors. Reverse engineer the application to be migrated into Oracle JDeveloper. Appropriate descriptors will be automatically generated by Oracle JDeveloper.

  Note: For JBuilder, Oracle supplies an add-in which generates OC4J deployment descriptors.

#### 5.2.3.1 Steps for Using Oracle JDeveloper 10g (10.1.3) to Convert `weblogic-ejb-jar.xml` to `orion-ejb-jar.xml`

The following steps convert most of the descriptor elements in `weblogic-ejb-jar.xml` and `weblogic-cmp-rdbms-jar.xml`:

1. In the File menu, select Import and specify the EAR file containing the WebLogic Server EJB's to be migrated.

2. Once the import operation has successfully completed, right-click `weblogic-ejb-jar.xml` and select "Export to OC4J."

3. Right-click the generated `orion-ejb-jar.xml`, and select "Properties."

4. Edit any mappings, if required.

5. Create a connection to an OC4J instance using the Connection Navigator. (Select "Connection Navigator" in the View menu.)

6. Create an EJB deployment profile. In the Application Navigator, right-click `ejb-jar.xml` and select "Create EJB Deployment Profile."

7. Deploy the EJBs to your OC4J instance. Right-click the deployment profile you created in step 6, and select your application server connection.

Note: Use the above same steps to convert `weblogic-cmp-rdbms-jar.xml`. The same `orion-ejb-jar.xml` file is generated for both WebLogic Server descriptor files.

#### 5.2.3.2 Using the Oracle TopLink Migration Tool to Convert `weblogic-cmp-rdbms-jar.xml` to `toplink-ejb-jar.xml`

The OracleAS TopLink migration tool takes the following files as input:

- `weblogic-ejb-jar.xml`

- `weblogic-cmp-rdbms-jar.xml`

It migrates as much WebLogic Server-specific persistence configuration as possible to a new `toplink-ejb-jar.xml` file and outputs the following new files in a target directory you specify:

- `orion-ejb-jar.xml`

- `toplink-ejb-jar.xml`

- OracleAS TopLink Mapping Workbench project file `TLCmpProject.mwp`

The input BEA WebLogic files may be in an EAR, JAR, or just standalone XML files. If you migrate from standalone XML files (rather than an EAR or JAR file), ensure that the domain classes are accessible and included in your classpath.

The OracleAS TopLink migration tool outputs a new `orion-ejb-jar.xml` and `toplink-ejb-jar.xml` file to the target directory you specify in the same format as it reads the original files. For example, if you specify an EAR file as input, then the OracleAS TopLink migration tool stages and creates a new EAR file that contains both the new `orion-ejb-jar.xml` and the new `toplink-ejb-jar.xml` file but is otherwise identical to the original.

The OracleAS TopLink Mapping Workbench project file is always output as a separate file.

Note: Oracle recommends that you make a backup copy of your `weblogic-ejb-jar.xml`, `weblogic-cmp-rdbms-jar.xml`, and `toplink-ejb-jar.xml` files before using the OracleAS TopLink migration tool.

As it operates, the OracleAS TopLink migration tool logs all errors and diagnostic output to a log file named wls_migration.log in the output directory. If you use the OracleAS TopLink migration tool from the OracleAS TopLink Mapping Workbench, also see the OracleAS TopLink Mapping Workbench log file `oracle.toplink.workbench.log` located in your user home directory (for example, in Windows, `C:\Documents and Settings\``<username>`).

The OracleAS TopLink migration tool processes descriptor, mapping, and query information from the input files:

- It builds a OracleAS TopLink descriptor object for each entity bean and migrates native persistence metadata like mapped tables, primary keys, and mappings for CMP and CMR fields.

- It builds a OracleAS TopLink mapping object for every CMP and CMR field of an entity bean and migrates native persistence metadata like foreign key references.

- It builds a OracleAS TopLink query object for each finder or `ejbSelect` of an entity bean and migrates persistence metadata like customized query statements.

See Also: Oracle Application Server TopLink Application Developer's Guide for steps on using the OracleAS TopLink Migration Tool from OracleAS TopLink Mapping Workbench.

### 5.2.4 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.

#### 5.2.4.1 WebLogic Server

In WebLogic Server, you would have used the `appc` 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, `appc` creates special cluster-aware classes that will be used for deployment. You can also use `appc` 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.

#### 5.2.4.2 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 Console 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.

### 5.2.5 Loading EJB Classes in the Server

This section describes how each application server manages the loading of EJB classes.

#### 5.2.5.1 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.

#### 5.2.5.2 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`.

## 5.3 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 (using Oracle JDeveloper is another option). Use the following points as guidelines:

- 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 Server 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 Console.

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

## 5.4 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 Console.

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.

## 5.5 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 `appc` 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.xm`l

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

### 5.5.1 Migrating Finder Methods

The following considerations apply when migrating finder methods:

- Standard finder methods are automatically generated in OC4J; they do not need to be regenerated.

- Finder methods in WebLogic Server 5.1 and 6.0 use WLQL (WebLogic Query Language), a proprietary query language for specifying selection criteria. These need to be rewritten.

- OC4J uses standard SQL `WHERE` clauses for specifying selection criteria or EJB Query Language (EJB-QL).

- Any extensions of EJB-QL made by WebLogic Server need to be rewritten.

The EJB 1.1 specification does not fully address the particulars for custom finder methods, that is, the logic used within an EJB to find elements in a database. While the specification mandates that such methods be declared with names beginning with `find…()` or `findBy…()` in the home interface and bean class, it does not however provide a formal syntax to declare the underlying search logic. In other words, the way in which queries for custom finders are declared is not standardized, and is therefore dependent upon the EJB container. Additionally, custom finder methods may return either a single entity bean or a collection of entity beans, depending on the desired functionality.

Search logic in WebLogic Server is expressed using WLQL, which uses a syntax close to that of LISP; query operators and operands are presented in the form:

(operator operand1 operand2)

Search Logic in WebLogic Server

This language allows the definition of queries featuring multiple selection criteria (the equivalent of the `WHERE` clause in SQL) and optionally specifying a sorting clause (the equivalent of the `ORDER BY` clause in SQL).

Search Logic in Oracle Application Server

In contrast, search logic in Oracle Application Server is expressed using standard SQL `WHERE` clauses allowing multiple selection criteria.

For the `LIKE` operator with input parameters and `ORDER BY` clause, you can use Oracle Application Server 10g Release 3 (10.1.3) with OracleAS TopLink CMP that has support for EJB 2.1. If you do not use OracleAS TopLink, you can use a work around by modifying the SQL in '`query=""`' in `orion-ejb-jar.xml`.

## 5.6 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 and 8.1, their EJB containers are EJB 2.0 compliant and supports EJB-QL. These EJB containers additionally provide 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.

## 5.7 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.