Programming WebLogic Enterprise JavaBeans

Introduction and Roadmap

Document Scope and Audience

Guide to this Document

Samples and Tutorials for the EJB Developer

Avitek Medical Records Application (MedRec) and Tutorials

EJB Examples in the WebLogic Server Distribution

Additional EJB Examples Available for Download

New and Changed EJB Features in This Release

Understanding Enterprise JavaBeans

How Do Applications Use EJBs?

Session EJBs Implement Business Logic

Stateless Session Beans

Stateful Session Beans

Entity EJBs Maintain Persistent Data

Message-Driven Beans Implement Loosely Coupled Business Logic

EJB Anatomy and Environment

EJB Components

The EJB Container

EJB Deployment Descriptors

Key Deployment Element Mappings

EJBs, Clients, and Application Objects

EJB Communications

EJBs and Message Destination References

WebLogic Server Value-Added EJB Features

Performance-Enhancing Features for WebLogic Server EJBs

Pooling Improves EJB Response Time

Caching Improves EJB Performance

Additional Caching Capabilities for CMP Entities

Field Groups for Efficient Queries (CMP Entities)

Configurable Write Behaviors

Operation Ordering and Batching (CMP Entities)

Optimized Database Updates (CMP Entities)

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

CMP Beans Increase Developer Productivity

Automatic Primary Key Generation (CMP Entities)

Automatic Table Creation (CMP Entities)

Dynamic Queries (CMP Entities)

Reliability and Availability Features

Load Balancing Among Clustered EJBs Increases Scalability

Failover for Clustered EJBs Increases Reliability

Securing EJBs

Designing Enterprise Java Beans

Choosing the Right Bean Type

Session Bean Features

Stateful Session Beans

Stateless Session Beans

Stateless Beans Offer Performance and Scalability Advantages

Exposing Stateless Session Beans as Web Services

Entity Bean Features

Key Features of Entity Beans

Read-Write versus Read-Only Entity Beans

Entity Bean Performance and Data Consistency Characteristics

Message-Driven Bean Features

Persistence Management Alternatives

Use Container-Managed Persistence (CMP) for Productivity and Portability

Use Bean-Managed Persistence (BMP) Only When Necessary

Transaction Design and Management Options

Understanding Transaction Demarcation Strategies and Performance

Demarcating Transactions at the Server Level is Most Efficient

Container-Managed Transactions Are Simpler to Develop and Perform Well

Bean-Level Transaction Management

Client-Level Transaction Management is Costly

Transaction Isolation: A Performance vs. Data Consistency Choice

Satisfying Application Requirements with WebLogic Server EJBs

Implementing Enterprise Java Beans

Overview of the EJB Development Process

Create a Source Directory

Create EJB Classes and Interfaces

Using WebLogic Server Generic Bean Templates

Programming Client Access to EJBs

Programming Client to Obtain Initial Context

Programming Client to Look Up a Home Interface

Configuring EJBs to Send Requests to a URL

Specifying an HTTP Resource by URL

Specifying an HTTP Resource by Its JNDI Name

Accessing HTTP Resources from Bean Code

Configuring Network Communications for an EJB

Programming and Configuring Transactions

Programming Container-Managed Transactions

Configuring Automatic Retry of Container-Managed Transactions

Programming Bean-Managed Transactions

Programming Transactions That Are Distributed Across EJBs

Programming the EJB Timer Service

Using Java Programming Interfaces to Program Timer Objects

Timer Deployment Descriptors

Server Failure and Timers

Declare Web Service References

Compile Java Source

Generate Deployment Descriptors

Edit Deployment Descriptors

Security Elements

Resource Mapping Elements

Persistence Elements

Clustering Elements

Data Consistency Elements

Container-Managed Transactions Elements

Performance Elements

Network Communications Elements

Generate EJB Wrapper Classes, and Stub and Skeleton Files

appc and Generated Class Name Collisions

Package

Packaging Considerations for EJBs with Clients in Other Applications

Deploy

Solving Problems During Development

Adding Line Numbers to Class Files

Monitoring Data

Creating Debug Messages

WebLogic Server Tools for Developing EJBs

Administration Console

javac

EJBGen

weblogic.Deployer

appc

DDConverter

Comparison of EJB Tool Features

Session EJBs

Comparing Stateless and Stateful Session Beans

Pooling for Stateless Session EJBs

Caching and Passivating Stateful Session EJBs

Stateful Session EJB Creation

Stateful Session EJB Passivation

Controlling Passivation

Specifying the Persistent Store Directory for Passivated Beans

Configuring Concurrent Access to Stateful Session Beans

Design Decisions for Session Beans

Choosing Between Stateless and Stateful Beans

Choosing the Optimal Free Pool Setting for Stateless Session Beans

Implementing Session Beans

WebLogic-Specific Configurable Behaviors for Session Beans

Entity EJBs

Managing Entity Bean Pooling and Caching

Understanding Entity Pooling

Understanding Entity Caching

Understanding ejbLoad() and ejbStore() Behavior

Controlling the Behavior of ejbLoad() and ejbStore()

Disabling Cache Flushing

Configuring Application-Level Caching

Using Primary Keys

Specifying Primary Keys and Primary Key Classes

Guidelines for Primary Keys

Automatically Generating Primary Keys

Specifying Automatic Key Generation for Oracle

Generating Primary Keys with a Named Sequence Table

Declaring Primary Key Field Type

Support for Oracle SEQUENCE

String-Valued CMP Field Trimming

Benefits of String Trimming

Disabling String Trimming

Configuring Entity EJBs for Database Operations

Configuring Table Mapping

Automatic Table Creation (Development Only)

Delaying Database Inserts

Why Delay Database Inserts?

Configuring Delayed Database Inserts

Limiting Database Reads with cache-between-transactions (Long-Term Caching)

Updating the Database Before Transaction Ends

Dynamic Queries

Enabling Dynamic Queries

Executing Dynamic Queries

Enabling BLOB and CLOB Column Support for Oracle or DB2

Specifying a BLOB Column Using the Deployment Descriptor

Controlling Serialization for cmp-fields of Type byte[] Mapped to an Oracle Blob

Specifying a CLOB Column Using the Deployment Descriptor

Specifying Field Groups

Ordering and Batching Operations

Operation Ordering

Batch Operations Guidelines and Limitations

Using Query Caching (Read-Only Entity Beans)

Using SQL in Entity Beans

Using Container-Managed Relationships (CMRs)

CMR Requirements and Limitations

CMR Cardinality

CMR Direction

Removing CMRs

Defining Container-Managed Relationships (CMRs)

Specifying Relationships in ejb-jar.xml

Specifying Relationships in weblogic-cmp-jar.xml

About CMR Fields and CMR Field Accessor Methods

Using Cascade Delete for Entities in CMRs

Relationship Caching

Enabling Relationship Caching

Choosing a Concurrency Strategy

Exclusive Concurrency

Database Concurrency

Optimistic Concurrency

Preventing Stale Optimistic Bean Data

Explicit Invalidation of Optimistic Beans

Invalidation Options for Optimistic Concurrency in Clusters

Check Data for Validity with Optimistic Concurrency

Optimistic Concurrency and Oracle Databases

Read Only Concurrency

Concurrency Strategy Trade-Offs

Configuring Concurrency Strategy

Preventing Deadlocks for Transactions That Use Exclusive Concurrency and Cascade Deletes

Using the Read-Mostly Pattern

Configuring Entity Beans for Read-Mostly Pattern

Invalidating Read-Only Entity EJBs Implicitly

Invalidating Entity EJBs Explicitly

CMP Entity Bean Descriptors Element by Feature

Container-Managed Relationship Elements

Primary Key Elements

Message-Driven EJBs

Message-Driven EJB Lifecycle and the Free Pool

MDBs and the Free Pool

MDBs and Concurrent Processing

MDBs and Messaging Models

Point-to-Point (Queue) Model: One Message Per Listener

Publish/Subscribe (Topic) Model

Exactly-Once Processing

JCA-Based MDBs

MDB Deployment Options

Destination and MDBs: Collocated vs. Not Collocated

Collocated Destination/MDBs

Non-Collocated Destination/MDBs

JMS Distributed Destinations

Programming and Configuring MDBs: Main Steps

Required JMS Configuration

Create MDB Class and Configure Deployment Elements

Programming and Configuring MDBs: Details

Configuring EJBs to Use Logical Message Destinations

Configuring Logical JMS Message Destinations for Individual MDBs

Configuring Application-Scoped Logical JMS Message Destinations

Configuring Destination Type

Configuring Transaction Management Strategy for an MDB

Configuring Suspension of Message Delivery During JMS Resource Outages

Configuring the Number of Seconds to Suspend a JMS Connection

Manually Suspending and Resuming Message Delivery

Configuring MDBs for Destinations

Whether to Use Wrappers

How to Set provider-url

How to Set initial-context-factory

How to Set destination-jndi-name

How to Set connection-factory-jndi-name

Common Destination Scenarios: Illustrations and Key Element Settings

Configuring Durable Topic Subscriptions

Configuring a Durable Topic Subscription for a Non-Clustered Server

Configuring a Durable Topic Subscription for a Cluster

Configuring Automatic Deletion of Durable Topic Subscriptions

Configuring Message Handling Behaviors

Ensuring Message Receipt Order

Preventing and Handling Duplicate Messages

Redelivery and Exception Handling

Using the Message-Driven Bean Context

Deferring Message Processing Until Completion of Boot Up

Configuring a Security Identity for a Message-Driven Bean

Migration and Recovery for Clustered MDBs

Nutshell Summary: Deployment Elements for MDBs

Deployment Guidelines for Enterprise Java Beans

Before You Deploy an EJB

Understanding and Performing Deployment Tasks

Deployment Guidelines for EJBs

Deploy EJBs as Part of an Enterprise Application

Deploy EJBs That Call Each Other in the Same Application

Deploy Homogeneously to a Cluster

Deploying Pinned EJBs to a Cluster

Redeploying an EJB

Redeploying an Individual EJB Implementation Class

Understanding Warning Messages

Disabling EJB Deployment Warning Messages

Deployment Descriptor Schema and Document Type Definitions Reference

XML Schema Definitions and Namespace Declarations

weblogic-ejb-jar.xml Namespace Declaration and Schema Location

weblogic-cmp-jar.xml Namespace Declaration and Schema Location

ejb-jar.xml Namespace Declaration and Schema Location

Document Type Definitions and DOCTYPE Header Information

weblogic-ejb-jar.xml Deployment Descriptor Reference

2.1 weblogic-ejb-jar.xml File Structure

Changes to weblogic-ejb-jar.xml in WebLogic Server 9.0

2.1 weblogic-ejb-jar.xml Elements

weblogic-cmp-jar.xml Deployment Descriptor Reference

2.1 weblogic-cmp-jar.xml Deployment Descriptor File Structure

Changes to weblogic-cmp-jar.xml in WebLogic Server 9.0

2.1 weblogic-cmp-jar.xml Deployment Descriptor Elements

Setting up Oracle for Cascade Delete

Function

Mapping a Bean on Foreign Key Side of a Relationship to Multiple Tables

Mapping a Bean on Primary Key Side of a Relationship to Multiple Tables

appc Reference

appc

Advantages of Using appc

appc Syntax

Designating Alternative Deployment Descriptors

appc Options

appc and EJBs

EJBGen Reference

Running EJBGen

EJBGen Distribution and Examples

Invoking EJBGen

EJBGen Command Options

Using Key EJBGen Features

Controlling the Files EJBGen Generates

Using Property Files with EJBGen

Using User Variables

Using Predefined Variables

Surround Attributes that Contain Spaces With Double Quotes

EJBGen Supports Tag Inheritance

Examples of EJBGen Tag Usage

Mapping an Entity Bean to Several Tables with EJBGen

Specifying Relationship Caching with EJBGen Tags

Specifying Relationships with EJBGen Tags

Upgrading Relationships to Use Local Interfaces

Enum Attribute Constant Values

Constants.Bool

Constants.TransactionAttribute

Constants.IsolationLevel

Constants.RefType

Constants.HomeLoadAlgorithm

Constants.Interface

Constants.ConcurrencyStrategy

EJBGen Annotation Reference

EJB Container Annotations

weblogic.ejbgen.ActivationConfigProperties

weblogic.ejbgen.ActivationConfigProperty

Attributes

weblogic.ejbgen.AutomaticKeyGeneration

Attributes

weblogic.ejbgen.CmpField

Attributes

weblogic.ejbgen.CmrField

Attributes

weblogic.ejbgen.Compatibility

Attributes

weblogic.ejbgen.CreateDefaultDbmsTables

weblogic.ejbgen.CreateDefaultRdbmsTables

weblogic.ejbgen.DBSpecificSQL

Attributes

weblogic.ejbgen.EjbClientJar

weblogic.ejbgen.EjbInterface

Attributes

weblogic.ejbgen.EjbLocalRef

Attributes

weblogic.ejbgen.EjbLocalRefs

weblogic.ejbgen.EjbRef

Attributes

weblogic.ejbgen.EjbRefs

weblogic.ejbgen.Entity

Attributes

weblogic.ejbgen.EntityCacheRef

Attributes

weblogic.ejbgen.EnvEntries

weblogic.ejbgen.EnvEntry

Attributes

weblogic.ejbgen.FileGeneration

Attributes

weblogic.ejbgen.Finder

Attributes

weblogic.ejbgen.Finders

weblogic.ejbgen.ForeignJmsProvider

Attributes

weblogic.ejbgen.JarSettings

Attributes

weblogic.ejbgen.JndiName

Attributes

weblogic.ejbgen.LocalHomeMethod

Attributes

weblogic.ejbgen.LocalMethod

Attributes

weblogic.ejbgen.MessageDestination

Attributes

weblogic.ejbgen.MessageDestinationRef

Attributes

weblogic.ejbgen.MessageDestinationRefs

weblogic.ejbgen.MessageDestinations

weblogic.ejbgen.MessageDriven

Attributes

weblogic.ejbgen.MethodIsolationLevelPattern

Attributes

weblogic.ejbgen.MethodIsolationLevelPatterns

weblogic.ejbgen.MethodPermissionPattern

Attributes

weblogic.ejbgen.MethodPermissionPatterns

weblogic.ejbgen.PrimKeyField

weblogic.ejbgen.Relation

Attributes

weblogic.ejbgen.Relations

weblogic.ejbgen.RelationshipCachingElement

Attributes

weblogic.ejbgen.RelationshipCachingElements

weblogic.ejbgen.RemoteHomeMethod

Attributes

weblogic.ejbgen.RemoteMethod

Attributes

weblogic.ejbgen.ResourceEnvRef

Attributes

weblogic.ejbgen.ResourceEnvRefs

weblogic.ejbgen.ResourceRef

Attributes

weblogic.ejbgen.ResourceRefs

weblogic.ejbgen.RoleMapping

Attributes

weblogic.ejbgen.RoleMappings

weblogic.ejbgen.SecurityRoleRef

Attributes

weblogic.ejbgen.SecurityRoleRefs

weblogic.ejbgen.Select

Attributes

weblogic.ejbgen.ServiceEndpointMethod

Attributes

weblogic.ejbgen.ServiceRef

Attributes

weblogic.ejbgen.ServiceRefs

weblogic.ejbgen.Session

Attributes

weblogic.ejbgen.SqlFinder

Attributes

weblogic.ejbgen.SqlFinders

weblogic.ejbgen.SqlShape

Attributes

weblogic.ejbgen.SqlShapeTable

Attributes

weblogic.ejbgen.SqlShapes

weblogic.ejbgen.ValueObject

Attributes

weblogic.ejbgen.ValueObjectField

Attributes

EJB Query Language (EJB-QL) and WebLogic Server

EJB QL Requirement for EJB 2.x Beans

Using the EJB 2.x WebLogic QL Extension for EJB QL

upper and lower Functions

upper

lower

Using ORDER BY

Using Subqueries

Subquery Return Types

Subqueries as Comparison Operands

Correlated and Uncorrelated Subqueries

Using Arithmetic Functions

Using Aggregate Functions

Using Queries that Return ResultSets

Using Oracle SELECT HINTS

"get" and "set" Method Restrictions

Properties-Based Methods of the Query Interface

Migrating from WLQL to EJB QL

Known Issue with Implied Cross Products

EJB QL Error-Reporting

Visual Indicator of Error in Query

Multiple Errors Reported after a Single Compilation

Important Information for EJB 1.1 Users

Writing for RDBMS Persistence for EJB 1.1 CMP

Finder Signature

finder-list Element

finder-query Element

Using WebLogic Query Language (WLQL) for EJB 1.1 CMP

WLQL Syntax

WLQL Operators

WLQL Operands

Examples of WLQL Expressions

Using SQL for CMP 1.1 Finder Queries

Tuned EJB 1.1 CMP Updates in WebLogic Server

Using is-modified-method-name to Limit Calls to ejbStore()

5.1 weblogic-ejb-jar.xml Deployment Descriptor File Structure

5.1 weblogic-ejb-jar.xml Deployment Descriptor Elements

caching-descriptor

persistence-descriptor

clustering-descriptor

transaction-descriptor

reference-descriptor

transaction-isolation

security-role-assignment

1.1 weblogic-cmp-jar.xml Deployment Descriptor File Structure

1.1 weblogic-cmp-jar.xml Deployment Descriptor Elements

RDBMS Definition Elements

EJB Field-Mapping Elements

Finder Elements