Contents for Programming WebLogic Enterprise JavaBeans
Introduction and Roadmap
Document Scope and Audience
Guide to this Document
Related Documentation
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
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