Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic Enterprise JavaBeans

# Understanding Enterprise JavaBeans

These sections briefly review the different Enterprise JavaBean (EJB) types and the functions they can serve in an application, and describe how they work with other application objects and WebLogic Server.

It is assumed the reader is familiar with Java programming and EJB 2.0 concepts and features.

- How Do Applications Use EJBs?
- EJB Anatomy and Environment
- EJBs, Clients, and Application Objects
- Securing EJBs
- WebLogic Server Value-Added EJB Features

# How Do Applications Use EJBs?

These sections describe the purpose and capabilities of each bean type.

## Session EJBs Implement Business Logic

Session beans implement business logic. A session bean instance serves one client at a time. There are two types of session beans: stateful and stateless.

### Stateless Session Beans

A stateless session bean does not store session or client state information between invocations—the only state it might contain is not specific to a client, for instance, a cached database connection or a reference to another EJB. At most, a stateless session bean may store state for the duration of a method invocation. When a method completes, state information is not retained. Any instance of a stateless session bean can serve any client—any instance is equivalent. Stateless session beans can provide better performance than stateful session beans, because each stateless session bean instance can support multiple clients, albeit one at a time.

Example: An Internet application that allows visitors to click a "Contact Us" link and send an email could use a stateless session bean to generate the email, based on the to and from information gathered from the user by a JSP.

### Stateful Session Beans

Stateful session beans maintain state information that reflects the interaction between the bean and a particular client across methods and transactions. A stateful session bean can manage interactions between a client and other enterprise beans, or manage a workflow.

Example: A company Web site that allows employees to view and update personal profile information could use a stateful session bean to call a variety of other beans to provide the services required by a user, after the user clicks "View my Data" on a page:

- Accept the login data from a JSP, and call another EJB whose job it is to validate the login data.
- Send confirmation of authorization to the JSP.
- Call a bean that accesses profile information for the authorized user.

## Entity EJBs Maintain Persistent Data

An entity bean represents a set of persistent data, usually rows in a database, and provides methods for maintaining or reading that data. An entity bean is uniquely identified by a primary key, and can provide services to multiple clients simultaneously. Entity beans can participate in relationships with other entity beans. The relationships between entity beans are a function of the real-world entities that the entity beans model. An entity bean's fields and its relationships to other entity beans are defined in an object schema, which is specified in the bean's `ejb-jar.xml` deployment descriptor.

An entity bean can have other bean types, such as message-driven or session beans, as clients, or be directly accessed by Web components. The client uses the entity bean to access data in a persistent store. An entity bean encapsulates the mechanics of database access, isolating that complexity from its clients and de-coupling physical database details from business logic.

Example: The stateful session bean in the previous example, which orchestrates services for an employee accessing personal profile information on a company intranet, could use an entity bean for getting and updating the employee's profile.

## Message-Driven Beans Implement Loosely Coupled Business Logic

A message-driven bean implements loosely coupled or asynchronous business logic in which the response to a request need not be immediate. A message-driven bean receives messages from a JMS Queue or Topic, and performs business logic based on the message contents. It is an asynchronous interface between EJBs and JMS.

Throughout its lifecycle, an MDB instance can process messages from multiple clients, although not simultaneously. It does not retain state for a specific client. All instances of a message-driven bean are equivalent—the EJB container can assign a message to any MDB instance. The container can pool these instances to allow streams of messages to be processed concurrently. It is acceptable or beneficial for customer orders to "stack up" before the associated supplier orders are issued.

The EJB container interacts directly with a message-driven bean—creating bean instances and passing JMS messages to those instances as necessary. The container creates bean instances at deployment time, adding and removing instances during operation based on message traffic.

Example: In an on-line shopping application, where the process of taking an order from a customer results in a process that issues a purchase order to a supplier, the supplier ordering process could be implemented by a message-driven bean. While taking the customer order always results in placing a supplier order, the steps are loosely coupled because it is not necessary to generate the supplier order before confirming the customer order.

# EJB Anatomy and Environment

These sections briefly describe classes required for each bean type, the EJB run-time environment, and the deployment descriptor files that govern a bean's run-time behavior.

- EJB Components
- The EJB Container
- EJB Deployment Descriptors

## EJB Components

The composition of a bean varies by bean type. Table 2-1 defines the classes that make up each type of EJB, and defines the purpose of the class type.

Table 2-1 Components of an EJB

EJB Component | Description | Stateless Session | Stateful Session | Entity | MDB
--- | --- | --- | --- | --- | ---
Remote interface | The remote interface exposes business logic to remote clients—clients running in a separate application from the EJB. It defines the business methods a remote client can call. | Yes | Yes | Yes | No
Local interface | The local interface exposes business logic to local clients—those running in the same application as the EJB. It defines the business methods a local client can call. Note: Not available for 1.1 EJBs. | Yes | Yes | Yes | No
Local home interface | The local home interface, also referred to as an EJB factory or life-cycle interface, provides methods that local clients—those running in the same application as the EJB—can use to create, remove, and in the case of an entity bean, find instances of the bean. The local home interface also has "home methods"—business logic that is not specific to a particular bean instance. | Yes | Yes | Yes | No
Remote home interface | The remote home interface, also referred to as an EJB factory, or life-cycle interface, provides methods that remote clients—those running in a separate application from the EJB—can use to create, remove, and find instances of the bean. | Yes | Yes | Yes | No
Bean class | The bean class implements business logic. | Yes | Yes | Yes | Yes
Primary key class | Only entity beans have a primary key class. The primary key class maps to one or more fields in a database—identifying the persistent data to which the entity bean corresponds. | No | No | Yes | No

## The EJB Container

An EJB container is a run-time container for beans that are deployed to an application server. The container is automatically created when the application server starts up, and serves as an interface between a bean and run-time services such as:

- Life-cycle management
- Code generation
- Persistence management
- Security
- Transaction management
- Locking and concurrency control

## EJB Deployment Descriptors

The structure of a bean and its run-time behavior are defined in one or more XML deployment descriptor files. Programmers create deployment descriptors during the EJB packaging process, and the descriptors become a part of the EJB deployment when the bean is compiled.

WebLogic Server EJBs have three deployment descriptors:

- `ejb-jar.xml`—The standard J2EE deployment descriptor. All beans must be specified in an `ejb-jar.xml`. An `ejb-jar.xml` can specify multiple beans that will be deployed together.
- `weblogic-ejb-jar.xml`—WebLogic Server-specific deployment descriptor that contains elements related to WebLogic Server features such as clustering, caching, and transactions. This file is required if your beans take advantage of WebLogic Server-specific features. Like `ejb-jar.xml`, `weblogic-ejb-jar.xml` can specify multiple beans that will be deployed together. For details, see weblogic-ejb-jar.xml Deployment Descriptor Reference.
- `weblogic-cmp-jar.xml`—WebLogic Server-specific deployment descriptor that contains elements related to container-managed persistence for entity beans. Entity beans that use container-managed persistence must be specified in a `weblogic-cmp-jar.xml` file. For details, see weblogic-cmp-jar.xml Deployment Descriptor Reference.

### Key Deployment Element Mappings

As described in EJB Deployment Descriptors, a WebLogic Server EJB's runtime behavior can be controlled by elements in three different descriptor files: `ejb-jar.xml`, `weblogic-ejb-jar.xml`, and `weblogic-cmp-jar.xml.`

Table 2-2 lists the elements whose values should match in each descriptor file. The elements listed in the table are defined in Bean and Resource References and Security Roles.

Table 2-2 Element Mapping Among Descriptor Files

Map this element | in this stanza of ejb-jar.xml | to the same element in this stanza of weblogic-ejb-jar.xml | and to this stanza in weblogic-cmp- jar.xml
--- | --- | --- | ---
`role-name` | `security- role` | `security-role- assignment` | N/A
`ejb-name` | `message- driven, entity`, or `session` | `weblogic-enterprise-bean` | `weblogic-rdbms- bean`
`ejb-ref name` | `assembly- descriptor` | `ejb-reference-description` if the referenced bean runs in a different container than the current bean. or `ejb-local-reference- description` if the referenced bean runs in the same container as the current bean. | N/A
`res-ref- name` | `resource-ref` | `resource-description` | N/A

#### Bean and Resource References

Each descriptor file contains elements that identify a bean, and the runtime factory resources it uses:

- `ejb-name`—the name used to identifier a bean in each deployment descriptor file, independent of name that application code uses to refer to the bean.
- `ejb-ref-name`—the name by which a bean in another JAR is referred to in the referencing bean's code.
- `res-ref-name`—the name by which a resource factory is referred to in the referencing bean's code

A given bean or resource factory is identified by the same value in each descriptor file that contains it. Table 2-2 lists the bean and resource references elements, and their location in each descriptor file.

For instance, for a container-managed persistence entity bean named `LineItem`, this line:

`<ejb-name>LineItem</ejb-name>`

would appear in the:

- `assembly-descriptor` stanza of `ejb-jar.xml`
- `enterprise-bean` stanza of `weblogic-ejb-jar.xml`
- `weblogic-rdbms-bean` stanza of `weblogic-cmp-jar.xml`

#### Security Roles

Security roles are defined in the `role-name` element `ejb-jar.xml` and `weblogic-ejb-jar.xml.`

For information on:

- Programming security features for an EJB, see Securing Enterprise JavaBeans (EJBs) in Programming WebLogic Security.
- Creating or generating deployment descriptor files, see Generate Deployment Descriptors.
- Editing deployment descriptor files, see Edit Deployment Descriptors.
- Elements in `ejb-jar.xml`, see http://www.java.sun.com/dtd/ejb-jar_2_0.dtd.
- Elements in `weblogic-ejb-jar.xml`, see weblogic-ejb-jar.xml Deployment Descriptor Reference.
- Elements in `weblogic-cmp-jar.xml`, see weblogic-cmp-jar.xml Deployment Descriptor Reference.

# EJBs, Clients, and Application Objects

Figure 2-1 illustrates how EJBs typically relate to other components of a WebLogic Server application and to clients.

Figure 2-1 EJBs and Other Application Components

An EJB can be accessed by server-side or client-side objects such as servlets, Java client applications, other EJBs, applets, and non-Java clients.

Any client of an EJB, whether in the same or a different application, accesses it in a similar fashion. WebLogic Server automatically creates implementations of an EJB's home and business interfaces that can function remotely, unless the bean has only a local interface.

All EJBs must specify their environment properties using the Java Naming and Directory Interface (JNDI). You can configure the JNDI namespaces of EJB clients to include the home interfaces for EJBs that reside anywhere on the network—on multiple machines, application servers, or containers.

Most beans do not require a global JNDI name—specified in the `jndi-name` and `local-jndi-name` elements of `weblogic-ejb-jar.xml`. Most beans reference to each other using `ejb-link`s, as described in Using EJB Links.

Because of network overhead, it is more efficient to access beans from a client on the same machine than from a remote client, and even more efficient if the client is in the same application.

See Programming Client Access to EJBs for information on programming client access to an EJB.

## EJB Communications

WebLogic Server EJBs use:

- T3—To communicate with local objects. T3 is a WebLogic-proprietary remote network protocol that implements the Remote Method Invocation (RMI) protocol.
- RMI—To communicate with remote objects. RMI enables an application to obtain a reference to an object located elsewhere in the network, and to invoke methods on that object as though it were co-located with the client on the same JVM locally in the client's virtual machine.

An EJB with a remote interface is an RMI object. An EJB's remote interface extends `java.rmi.remote`. For more information on WebLogic RMI, see Programming WebLogic RMI

- HTTP—An EJB can obtain an HTTP connection to a Web server external to the WebLogic Server environment by using the `java.net.URL` resource connection factory. For more information, see Configuring EJBs to Send Requests to a URL.

# WebLogic Server Value-Added EJB Features

This section describes key WebLogic Server features that ease the process of EJB development, and enhance the performance, reliability, and availability of EJB applications.

## Performance-Enhancing Features for WebLogic Server EJBs

WebLogic Server supports pooling, caching, and other features that improve the response time and performance of EJBs. In a production environment, these features can reduce the time it takes for a client to obtain an EJB instance and access and maintain persistent data.

### Pooling Improves EJB Response Time

Weblogic Server maintains a free pool of ready-to-use EJB instances for stateless session beans, message-driven beans and entity beans. The EJB container creates a configurable number of bean instances at startup, so that a new instance does not have to be created for every request. When a client is done with an EJB instance, the container returns it to the pool for reuse. For more information see:

- Understanding Entity Pooling
- Message-Driven EJB Lifecycle and the Free Pool
- Pooling for Stateless Session EJBs

### Caching Improves EJB Performance

Weblogic Server supports caching for stateful session beans and entity beans.

An inactive cached bean instance can be passivated—removed from the cache and written to disk—and restored to memory later as necessary. Passivating bean instances optimizes use of system resources.

You can configure the size of the cache, and related behaviors such as rules for removing beans from the cache. Caching is supported for entity EJBs, whether they use container-managed or bean-managed persistence.

For more information, see:

- Understanding Entity Caching
- Caching and Passivating Stateful Session EJBs

Additional caching features are available for EJBs that use container-managed persistence, as described in the following section.

### Additional Caching Capabilities for CMP Entities

WebLogic Server provides these caching capabilities for entity beans that use container managed persistence:

- Relationship caching—Relationship caching improves the performance of entity beans by loading related beans into the cache and avoiding multiple queries by issuing a join query for the related bean. For more information, see Relationship Caching.
- Application-level caching—Application-level caching, also known as "combined caching," allows multiple entity beans that are part of the same J2EE application to share a single runtime cache. For more information, see Configuring Application-Level Caching.
- Caching between transactions—Use caching between transactions or long term caching to enable the EJB container to cache an entity bean's persistent data between transactions. For more information, see Limiting Database Reads with cache-between-transactions (Long-Term Caching).

### Field Groups for Efficient Queries (CMP Entities)

A group specifies a set of persistent attributes of an entity bean. A field-group represents a subset of the container-managed persistence (CMP) and container-managed relation (CMR) fields of a bean. You can put related fields in a bean into groups that are faulted into memory together as a unit. You can associate a group with a query or relationship, so that when a bean is loaded as the result of executing a query or following a relationship, only the fields mentioned in the group are loaded. For more information, see Specifying Field Groups.

### Configurable Write Behaviors

You can configure the behavior of the `ejbLoad()` and `ejbStore()` methods to enhance performance, by avoiding unnecessary calls to `ejbStore()`. As appropriate, you can ensure that WebLogic Server calls `ejbStore()` after each method call, rather than at the conclusion of the transaction. For more information, see Understanding ejbLoad() and ejbStore() Behavior.

### Operation Ordering and Batching (CMP Entities)

WebLogic Server allows you to batch and order multiple database operations so that they can be completed in a single database "round-trip". This allows you to avoid the bottlenecks that might otherwise occur when multiple entity instances are affected by a single transaction. For more information, see Ordering and Batching Operations.

### Optimized Database Updates (CMP Entities)

In WebLogic Server 8.1 SP01 and later, for CMP 2.0 entity beans, the `setXXX()` method does not write the values of unchanged primitive and immutable fields to the database. This optimization improves performance, especially in applications with a high volume of database updates.

### Read-Only Pattern and Read-Only Invalidation (CMP Entities)

For EJB data that is only occasionally updated, you can create a "read-mostly pattern" by implementing a combination of read-only and read-write EJBs. If you use the read-mostly pattern, you can use multicast invalidation to maintain data consistency—an efficient mechanism for invalidating read-only cached data after updates. Use of the `invalidate()` method after the transaction update has completed invalidates the local cache and results in a multicast message is sent to the other servers in the cluster to invalidate their cached copies. For more information, see Using the Read-Mostly Pattern.

## CMP Beans Increase Developer Productivity

WebLogic Server provides a variety of value-added database access features for entity beans that use container-managed persistence:

### Automatic Primary Key Generation (CMP Entities)

WebLogic Server supports multiple methods to automatically generate simple primary key for CMP entity EJBs, including use of an Oracle `SEQUENCE` (which can be automatically generated by WebLogic Server.) For more information, see Automatically Generating Primary Keys.

### Automatic Table Creation (CMP Entities)

You can configure the EJB container to automatically change the underlying table schema as entity beans change, ensuring that tables always reflect the most recent object-relationship mapping. For more information, see Automatic Table Creation (Development Only).

### Dynamic Queries (CMP Entities)

WebLogic Server allow you to construct and execute EJB-QL queries programmatically in your application code. This allows you to create and execute new queries without having to update and deploy an EJB. It also reduces the size and complexity of the EJB deployment descriptors. For more information, see Choosing a Concurrency Strategy.

## Reliability and Availability Features

WebLogic Server EJBs can be deployed to a cluster, allowing support for load balancing, and failover for remote clients of an EJB. EJBs must be deployed to all clustered servers.

A WebLogic Server cluster consists of multiple WebLogic Server server instances running simultaneously and working together to provide increased scalability and reliability. A cluster appears to clients as a single WebLogic Server instance. The server instances that constitute a cluster can run on the same machine, or be located on different machines.

Failover and load balancing for EJBs are handled by replica-aware stubs, which can locate instances of the object throughout the cluster. Replica-aware stubs are created for EJBs as a result of the object compilation process. EJBs can have two different replica-aware stubs: one for the `EJBHome` interface and one for the `EJBObject` interface. This allows some bean types to take advantage of load balancing and failover features at the home level when a client looks up an EJB object using the `EJBHome` stub and at the method level when a client makes method calls against the EJB using the EJBObject stub. Table 2-3 summarizes the load balancing and failover support (method level and home level) for each EJB type.

### Load Balancing Among Clustered EJBs Increases Scalability

The bean stub contains the load balancing algorithm (or the call routing class) used to load balance method calls to the object. On each call, the stub can employ its load algorithm to choose which replica to call.

WebLogic Server clusters support multiple algorithms for load balancing clustered EJBs; the default is the round-robin method. For more information, see Load Balancing in a Cluster in Using WebLogic Server Clusters.

All bean types support load balancing at the home level. All bean types, except read-write entity beans, support load balancing at the method level.

Note: WebLogic Server does not always load-balance an object's method calls. In most cases, it is more efficient to use a replica that is collocated with the stub itself, rather than using a replica that resides on a remote server.

### Failover for Clustered EJBs Increases Reliability

Failover for EJBs is accomplished using the `EJBHome` stub or, when supported, the `EJBObject` stub. When a client makes a call through a stub to a service that fails, the stub detects the failure and retries the call on another replica.

EJB failover requires that bean methods must be idempotent, and configured as such in `weblogic-ejb-jar.xml`. For more information see Replication and Failover for EJBs and RMIs in Using WebLogic Server Clusters.

Table 2-3 summarizes failover and load balancing features for clustered EJBs.

Table 2-3 Failover and Load Balancing for Clustered EJBs

EJB Type | Home Level Failover | Method Level Failover | Notes
--- | --- | --- | ---
Stateless Session | Supported | Supported | The `EJBObject` stub maintains the location of the EJB's primary and secondary states. Secondary server instances are selected using the same rules defined in Using Replication Groups in Using WebLogic Clusters. Stateless session EJB clustering behaviors are configured in `weblogic-ejb-jar.xml`. See WebLogic-Specific Configurable Behaviors for Stateless Session EJBs.
Stateful session | Supported | Supported | Stateful session EJB clustering behaviors are configured in `weblogic-ejb-jar.xml`. See WebLogic-Specific Configurable Behaviors for Session Beans.
Read-Write Entity | Supported | Not supported | `EJBHome` stubs do not fail over in the event of a recoverable call failure. Failover is not supported during method execution, only after method completion, or if the method fails to connect to a server instance. A read-write bean's home obtains a local instance of the bean and returns a stub pinned to the local server instance. Entity clustering behaviors are configured in `weblogic-ejb-jar.xml`. See Clustering Elements.
Read-Only Entity | Supported | Supported | `EJBHome` stubs do not failover in the event of a recoverable call failure. Entity clustering behaviors are configured in `weblogic-ejb-jar.xml`. See`` Clustering Elements.
Message- Driven | WebLogic Java Messaging Service (JMS) supports clustering of JMS servers. To understand For more information, see JMS and Clustering in Using WebLogic Server Clusters.

For more information, see Replication and Failover for EJBs and RMIs and Load Balancing for EJBs and RMI Objects Using WebLogic Server Clusters.

# Securing EJBs

Using WebLogic Server security features, you control both access to your EJBs (authorization) and verification of an EJB's identity when it interacts with other application components and other EJBs (authentication).

WebLogic Server enables application developers to build security into their EJB applications using J2EE and WebLogic Server deployment descriptors, or allows system administrators to control security on EJB applications from the WebLogic Server Administration Console. The latter option frees developers from having to code security, and provides administrators with a centralized tool for defining security policies on: entire enterprise applications (EARs); an EJB JAR containing multiple EJBs; a particular EJB within that JAR; or a single method within that EJB.

For more information about security and EJBs:

- Security Fundamentals in Introduction to WebLogic Securityauthentication, authorization and other security topics.
- Securing Enterprise JavaBeans (EJBs) in Programming WebLogic Securityinstructions for configuring authentication and authorization for EJBs.
- Securing WebLogic Resourcescontains instructions for on configuring authentication and authorization for your EJBs using the Administration Console.