Skip Headers
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10
g
Release 3 (10.1.3)
B14428-02
Home
Solution Area
Index
Next
Contents
List of Examples
List of Figures
List of Tables
Title and Copyright Information
Preface
Audience
Documentation Accessibility
Related Documents
Conventions
Part I EJB Overview
1
Understanding Enterprise JavaBeans
What are Enterprise JavaBeans?
What is the Anatomy of an EJB 3.0 EJB?
What is the Anatomy of an EJB 2.1 EJB?
What is the Lifecycle of an EJB?
Callback Methods
What is EJB Context?
How Do Annotations and Resource Injection Work?
What is a Session Bean?
What is a Stateless Session Bean?
What is the Stateless Session Bean Lifecycle?
What is a Stateful Session Bean?
What is the Stateful Session Bean Lifecycle?
What is Session Context?
What is an EJB 3.0 Entity?
What are Container-Managed Persistence Fields?
What are Container-Managed Relationship Fields?
What is the EJB 3.0 Entity Lifecycle?
What is an EJB 3.0 Entity Primary Key?
How Do You Query for an EJB 3.0 Entity?
Understanding EJB Query Syntax
Understanding the EJB 3.0 EntityManager Query API
What is an EJB 2.1 Entity Bean?
What is an EJB 2.1 CMP Entity Bean?
What are Container-Managed Persistence Fields?
What are Container-Managed Relationship Fields?
What is the CMP Entity Bean Lifecycle?
What is a CMP Entity Bean Primary Key?
What is an EJB 2.1 BMP Entity Bean?
What are Bean-Managed Persistence Fields?
What are Bean-Managed Relationship Fields?
What is the BMP Entity Bean Lifecycle?
What is a BMP Entity Bean Primary Key?
What is Entity Context?
How do You Avoid Database Resource Contention?
Transaction Isolation
Concurrency (Locking) Mode
When Does Entity Bean Passivation Occur?
What are Entity Bean Commit Options?
Commit Options and CMP Applications
Commit Options and BMP Applications
How Do You Query for an EJB 2.1 Entity Bean?
Understanding EJB Query Syntax
Understanding Finder Methods
Understanding Select Methods
What is a Message-Driven Bean?
What is the Message-Driven Bean Lifecycle?
What is Message Driven Context?
Which Type of EJB Should You Use?
Which Type of Session Bean Should You Use?
When do you use Bean-Managed versus Container-Managed Persistence?
What is the Difference Between Session and Entity Beans?
2
Understanding EJB Application Development
How Should You Develop EJB Applications?
Understanding the EJB Application Directory Structure
Using EJB Development Tools
Using JDeveloper
Using Eclipse
Using TopLink Workbench
What OC4J Services Can You Use with an EJB?
How do You Package and Deploy an EJB Application?
General Packaging and Deployment Procedure
Understanding EJB Deployment Descriptor Files
Understanding Packaging
Understanding Deployment
How Do Specify Vendor-Specific Configuration in an EJB 3.0 Application?
How Does OC4J Determine What Type of Persistence to Use?
In What Order does OC4J Deploy EJB Modules?
What is the ejb-jar.xml File?
EJB 3.0
EJB 2.1
XML Reference
What is the orion-ejb-jar.xml File?
EJB 3.0
EJB 2.1
XML Reference
What is the toplink-ejb-jar.xml File?
EJB 3.0
EJB 2.1
XML Reference
What is the ejb3-toplink-sessions.xml File?
EJB 3.0
EJB 2.1
XML Reference
What is the persistence.xml File?
Understanding the OC4J Default Persistence Unit
EJB 3.0
EJB 2.1
XML Reference
What is the orm.xml File?
EJB 3.0
EJB 2.1
XML Reference
How Do You Use an EJB in Your Application?
Understanding Client Access
Understanding EJB 3.0 Interceptors
Interceptor Restrictions
Interceptors and Invocation Context
Understanding EJBs and Web Services
Understanding EJB Administration
Understanding EJB JNDI Services
Understanding EJB Data Source Services
What Types of Data Source does OC4J Support?
Managed Data Source
Native Data Source
How Do You Define a Connection URL in OC4J?
What Transaction Types Do Data Sources Support?
Where Do You Configure Data Source Information in OC4J?
What is a Default Data Source?
How Does OC4J Handle Multiple Data Sources?
Understanding EJB Transaction Services
Who Manages a Transaction?
Container-Managed Transaction (CMT)
Bean-Managed Transaction (BMT)
How are Transactions Handled When a Client Invokes a Business Method?
How do I Participate in a Global or Two-Phase Commit Transaction?
Understanding EJB Security Services
Understanding Message Services
What Message Providers Can I use with My MDB?
Oracle Application Server JMS (OracleAS JMS) Provider: File-Based
Oracle JMS (OJMS) Provider: Advanced Queueing (AQ)-Based
J2EE Connector Architecture (J2CA) Adapter Message Provider
Understanding OC4J EJB Application Clustering Services
State Replication
State Replication Trigger
State Replication Scope
State Replication Mode
Load Balancing
Replication-Based Load Balancing
Static Retrieval Load Balancing
DNS Load Balancing
Failover
Transactions
Performance
Understanding EJB Timer Services
Understanding J2EE Timer Services
Understanding OC4J Cron Timer Services
3
Understanding EJB Support in OC4J
EJB 3.0 Support
What JDK is Required?
How do You Define an EJB 3.0 Application?
How does OC4J Manage Persistence in an EJB 3.0 Application?
TopLink Entity Manager
Customizing the TopLink Entity Manager
EJB 2.1 Support
What JDK is Required?
How do You Define an EJB 2.1 Application?
How does OC4J Manage Persistence in an EJB 2.1 Application?
TopLink Persistence Manager
Customizing the TopLink Persistence Manager
Migrating to the TopLink Persistence Manager
Configuration Changes in this Release
New Package Names for RMI and Application Client Initial Context Factories
Unsupported orion-ejb-jar.xml Attributes
Part II EJB 3.0 Session Beans
4
Implementing an EJB 3.0 Session Bean
Implementing an EJB 3.0 Stateless Session Bean
Implementing an EJB 3.0 Stateful Session Bean
5
Using EJB 3.0 Session Bean API
Configuring Passivation
Configuring Passivation Criteria
Configuring Passivation Location
Configuring a Lifecycle Callback Method for an EJB 3.0 Session Bean
Using Annotations
Configuring an Interceptor on an EJB 3.0 Session Bean
Using Annotations
Part III EJB 3.0 Entities
6
Implementing an EJB 3.0 Entity
Implementing an EJB 3.0 Entity
7
Using EJB 3.0 Persistence API
Configuring an EJB 3.0 Entity Primary Key
Configuring an EJB 3.0 Entity Primary Key Field
Using Annotations
Configuring EJB 3.0 Entity Automatic Primary Key Generation
Using Annotations
Configuring Table and Column Information
Configuring the Primary Table
Using Annotations
Configuring a Secondary Table
Using Annotations
Configuring a Column
Using Annotations
Configuring a Join Column
Using Annotations
Configuring an EJB 3.0 Entity Container-Managed Relationship Field
Configuring a Basic Mapping
Using Annotations
Configuring a Large Object Mapping
Using Annotations
Configuring a Serialized Object Mapping
Using Annotations
Configuring a One-to-One Mapping
Using Annotations
Configuring a Many-to-One Mapping
Using Annotations
Configuring a One-to-Many Mapping
Using Annotations
Configuring a Many-to-Many Mapping
Using Annotations
Configuring an Aggregate Mapping
Using Annotations
Configuring Optimistic Lock Version Field
Using Annotations
Configuring Lazy Loading on Finder Methods
Configuring a Lifecycle Callback Method for an EJB 3.0 Entity
Using Annotations
Configuring Inheritance for an EJB 3.0 Entity
Joined Subclass
Single Table for each Class Hierarchy
Using Annotations
Configuring Joined Subclass Inheritance with Annotations
Configuring Single Table Inheritance with Annotations
8
Using EJB 3.0 Query API
Implementing an EJB 3.0 Named Query
Using Annotations
Implementing an EJB 3.0 Dynamic Query
Using Java
Part IV EJB 3.0 Message-Driven Beans
9
Implementing an EJB 3.0 MDB
Implementing an EJB 3.0 MDB
10
Using EJB 3.0 MDB API
Configuring an EJB 3.0 MDB to Use a Non-J2CA Message Service Provider
Using Annotations
Using Deployment XML
Configuring an EJB 3.0 MDB to Use a J2CA Message Service Provider
Using Annotations
Using Deployment XML
Configuring Listener Threads
Configuring Maximum Delivery Count
Configuring Dequeue Retry Count and Interval
Configuring an Interceptor on an EJB 3.0 MDB Message Listener Method
Using Annotations
Configuring a Lifecycle Callback Method for an EJB 3.0 MDB
Using Annotations
Part V EJB 2.1 Session Beans
11
Implementing an EJB 2.1 Session Bean
Implementing an EJB 2.1 Stateless Session Bean
Using Java
Using Deployment XML
Implementing an EJB 2.1 Stateful Session Bean
Using Java
Using Deployment XML
Implementing the Home Interfaces
Implementing the Remote Home Interface
Implementing the Local Home Interface
Implementing the Component Interfaces
Implementing the Remote Component Interface
Implementing the Local Component Interface
Implementing the setSessionContext Method
12
Using EJB 2.1 Session Bean API
Configuring Passivation
Using Deployment XML
Configuring Passivation Criteria
Using Deployment XML
Configuring Passivation Location
Using Deployment XML
Configuring a Lifecycle Callback Method for an EJB 2.1 Session Bean
Using Java
Part VI EJB 2.1 Entity Beans
13
Implementing an EJB 2.1 Entity Bean
Implementing an EJB 2.1 CMP Entity Bean
Using Java
Using Deployment XML
Implementing an EJB 2.1 BMP Entity Bean
Using Java
Using Deployment XML
Implementing an EJB 2.1 BMP ejbCreate Method
Implementing the EJB 2.1 Home Interfaces
Implementing the Remote Home Interface
Implementing the Local Home Interface
Implementing the EJB 2.1 Component Interfaces
Implementing the Remote Component Interface
Implementing the Local Component Interface
Implementing the setEntityContext and unsetEntityContext Methods
14
Using EJB 2.1 CMP Entity Bean API
Configuring an EJB 2.1 CMP Entity Bean Primary Key
Configuring an EJB 2.1 CMP Entity Bean Primary Key Field
Using Deployment XML
Configuring an EJB 2.1 CMP Entity Bean Composite Primary Key Class
Using Java
Using Deployment XML
Configuring EJB 2.1 CMP Entity Bean Automatic Primary Key Generation
Using Deployment XML
Configuring Automatic Database Table Creation
Using Deployment XML
Configuring an EJB 2.1 CMP Entity Bean Container-Managed Persistence Field
Using Java
Using Deployment XML
Configuring an EJB 2.1 CMP Entity Bean Container-Managed Relationship Field
Using Java
Using Deployment XML
Configuring Default Mappings
Using Deployment XML
Configuring Lazy Loading on Finder Methods
Using Deployment XML
15
Using EJB 2.1 BMP Entity Bean API
Configuring a Read-Only BMP Entity Bean
Using Deployment XML
Configuring BMP Commit Options
Using Deployment XML
Configuring an EJB 2.1 BMP Entity Bean Query
Implementing an EJB 2.1 BMP the ejbFindByPrimaryKey Method
Implementing Other EJB 2.1 BMP Finder Methods
Configuring a Lifecycle Callback Method for an EJB 2.1 BMP Entity Bean
Implementing an EJB 2.1 BMP ejbStore Method
Implementing an EJB 2.1 BMP ejbLoad Method
Implementing an EJB 2.1 BMP ejbPassivate Method
Implementing an EJB 2.1 BMP ejbActivate Method
Implementing an EJB 2.1 BMP ejbRemove Method
16
Using EJB 2.1 Query API
Implementing an EJB 2.1 EJB QL Finder Method
Using Java
Using Deployment XML
Using TopLink Workbench
Implementing an EJB 2.1 EJB QL Select Method
Using Java
Using Deployment XML
Using TopLink Workbench
OC4J EJB 2.1 EJB QL Extensions
Part VII EJB 2.1 Message-Driven Beans
17
Implementing an EJB 2.1 MDB
Implementing an EJB 2.1 MDB
Using Java
Using Deployment XML
Implementing the setMessageDrivenContext Method
18
Using EJB 2.1 MDB API
Configuring an EJB 2.1 MDB to Use a Non-J2CA Message Service Provider
Using Deployment XML
Configuring an EJB 2.1 MDB to Use a J2CA Message Service Provider
Using Deployment XML
Configuring an MDB for Fast Undeploy on Windows
Using System Properties
Configuring an MDB for Oracle RAC Failover
Using Deployment XML
Using Java
Configuring Listener Threads
Using Deployment XML
Configuring Maximum Delivery Count
Using Deployment XML
Configuring Dequeue Retry Count and Interval
Using Deployment XML
Part VIII OC4J EJB Services
19
Configuring JNDI Services
Configuring Environment References
EJB Environment References
Resource Manager Connection Factory Environment References
Environment Variable Environment References
Web Service Environment References
Persistence Context References
Where Do You Configure an EJB Environment Reference?
Should You Use Logical Names?
Configuring an Environment Reference to an EJB
Configuring an Environment Reference to a Remote EJB
Configuring an Environment Reference to a Local EJB
Configuring an Environment Reference to a JDBC Data Source Resource Manager Connection Factory
Configuring an Environment Reference to a JMS Destination Resource Manager Connection Factory (JMS 1.1)
Configuring an Environment Reference to a JMS Destination or Connection Resource Manager Connection Factory (JMS 1.0)
Configuring an Environment Reference to a Java Mail Resource Manager Connection Factory
Configuring an Environment Reference to a URL Resource Manager Connection Factory
Configuring an Environment Reference to an Environment Variable
Configuring an Environment Reference to a Web Service
Configuring an Environment Reference to a Persistence Context
Configuring the Initial Context Factory
Configuring the Default Initial Context Factory
Configuring an Oracle Initial Context Factory
Configuring the Naming Provider URL for OC4J and Oracle Application Server
Configuring the Naming Provider URL for OC4J Standalone
Setting JNDI Properties in an EJB
Setting JNDI Properties with the JNDI Properties File
Setting JNDI Properties with System Properties
Setting JNDI Properties in the Initial Context
Looking up an EJB 3.0 EJB
Using Annotations
Using Initial Context
Looking Up the Remote Interface of an EJB 3.0 EJB Using ejb-ref
Looking Up the Remote Interface of an EJB 3.0 EJB Using location
Looking up the Local Interface of an EJB 3.0 EJB Using local-ref
Looking up the Local Interface of an EJB 3.0 EJB Using local-location
Looking Up an EJB 3.0 Resource Manager Connection Factory
Using Annotations
Using Initial Context
Looking Up an EJB 3.0 Environment Variable
Using Resource Injection
Using Initial Context
Looking Up an EJB 2.1 EJB
Using Initial Context
Looking Up the Remote Interface of an EJB 2.1 EJB Using ejb-ref
Looking Up the Remote Interface of an EJB 2.1 EJB Using location
Looking up the Local Interface of an EJB 2.1 EJB Using local-ref
Looking up the Local Interface of an EJB 2.1 EJB Using local-location
Looking Up an EJB 2.1 Resource Manager Connection Factory
Using Initial Context
Looking Up an EJB 2.1 Enviornment Variable
Using Initial Context
20
Configuring Data Sources
Configuring a Data Source for an Oracle Database
Using Application Server Control Console
Using Deployment XML
Configuring a Data Source for a Third-Party Database
Using Application Server Control Console
Using Deployment XML
Configuring a Default Data Source for an EJB 3.0 Application
Using Deployment XML
Configuring a Default Data Source for an EJB 2.1 Application
Using Deployment XML
21
Configuring Transaction Services
Configuring Transaction Timeouts
Configuring a Global Transaction Timeout
Using Application Server Control Console
Using Deployment XML
Configuring a Transaction Timeout for a Session Bean
Using Deployment XML
Configuring a Transaction Timeout for a Message-Driven Bean
Using Deployment XML
Transaction Best Practices
Using Container Managed Transactions with Datasource Connections
Using a Rollback Strategy
22
Configuring Security Services
Granting Permissions in Browser
Defining Users, Groups, and Roles in an EJB Application
Specifying Users and Groups
Specifying Logical Roles in the EJB Deployment Descriptor
Specifying a Role for an EJB Method
Using Annotations
Using Deployment XML
Specifying Unchecked Security for EJB Methods
Using Annotations
Using Deployment XML
Specifying the runAs Security Identity
Using Annotations
Using Deployment XML
Mapping Logical Roles to Users and Groups
Specifying a Default Role Mapping for Undefined Methods
Specifying Users and Groups by the Client
Specifying Credentials in EJB Clients
Specifying Credentials in JNDI Properties
Specifying Credentials in the Initial Context
Specifying EJB Client Security Properties in the ejb_sec.properties File
Using EJB 3.0 Security Annotations
Using Annotations
Retrieving Credentials from an EJB Using the JAAS API
Defining a Custom JAAS Login Module for an EJB Application
23
Configuring Message Services
Configuring an OracleAS JMS Message Service Provider
OracleAS JMS Destination and Connection Factory Names
Configuring jms.xml
Configuring an OJMS Message Service Provider
OJMS Destination and Connection Factory Names
Installing and Configuring the OJMS Provider
Configuring data-sources.xml
Configuring application.xml or orion-application.xml
Configuring a Message Service Provider Using J2CA
J2CA Message Service Provider Connection Factory Names
Installing and Configuring a J2CA Adapter
Configuring OC4J Deployment XML Files
24
Configuring OC4J EJB Application Clustering Services
Configuring EJB 3.0 and EJB 2.1 Stateful Session Bean Replication Policy
Using Deployment XML
Configuring Global Replication Policy in the application.xml File for Web and EJB Components
Configuring Application-Level Replication Policy in the orion-application.xml File for Web and EJB Components
Overriding Application-Level Replication Policy in the orion-ejb-jar.xml File for EJB Components
Configuring Replication-Based Load Balancing
Using System Properties
Configuring Static Retrieval Load Balancing
Using JNDI Properties
Configuring DNS Load Balancing
Using JNDI Properties
25
Configuring Timer Services
Configuring an EJB 3.0 EJB with a J2EE Timer
Using Annotations
Using Initial Context
Configuring an EJB 2.1 EJB with a J2EE Timer
Configuring an EJB with an OC4J Cron Timer
Troubleshooting Timers
How to Retrieve Information About the Timer
How to Retrieve a Persisted Timer
Executing the Timer Within the Scope of a Transaction
What Does a NoSuchObjectLocalException Mean with Timers?
Part IX Packaging and Deploying an EJB Application
26
Configuring Deployment Descriptor Files
Configuring the ejb-jar.xml File
Creating ejb-jar.xml During Migration
Creating the ejb-jar.xml File at Deployment Time
Creating ejb-jar.xml with JDeveloper
Configuring the toplink-ejb-jar.xml File
Creating toplink-ejb-jar.xml During Migration
Creating toplink-ejb-jar.xml with TopLink Workbench
Configuring the orion-ejb-jar.xml File
Configuring the ejb3-toplink-sessions.xml File
Creating ejb3-toplink-sessions.xml with TopLink Workbench
Configuring the persistence.xml File
Configuring a Named Persistence Unit in the persistence.xml File
What Persistent Managed Classes Does this Persistence Unit Include?
Configuring the persistence.xml File for the OC4J Default Persistence Unit
27
Packaging an EJB Application
Packaging an Application with Both EJB 3.0 and EJB 2.1 EJBs
Sharing Classes Between EJB Applications
Handling Out of Memory Exceptions at Runtime
Handling Class Cast Exceptions at Runtime
28
Deploying an EJB Application to OC4J
Deploying a Large EJB Application
Tuning the VM to Avoid Out Of Memory Errors During Deployment
Disabling Batch Compilation to Avoid Out Of Memory Errors During Deployment
Deploying Incrementally
Troubleshooting Application Deployment
Part X Using an EJB in Your Application
29
Accessing an EJB from a Client
What Type of Client Do You Have?
EJB Client
Standalone Java Client
Servlet or JSP Client
Configuring the Client
Configuring the Client Classpath for OC4J
Selecting an Initial Context Factory Class
Specifying Security Credentials
Selecting an EJB Reference
Accessing an EJB 3.0 EJB
Accessing an EJB 3.0 EJB in Another Application
Accessing an EJB 3.0 Entity Using an EntityManager
Acquiring an EntityManager
Acquiring the OC4J Default Entity Manager in an EJB 3.0 Stateful Session Bean Client
Acquiring a Named Entity Manager in an EJB 3.0 Stateful Session Bean Client
Acquiring an Entity Manager in Other EJB 3.0 Bean Clients
Acquiring an Entity Manager in a Helper Class or Web Client
Creating a New Entity Instance
Querying for an EJB 3.0 Entity Using the EntityManager
Finding an Entity by Primary Key with the Entity Manager
Creating a Named Query with the EntityManager
Creating a Dynamic EJB QL Query with the Entity Manager
Creating a Dynamic TopLink Expression Query with the EntityManager
Creating a Dynamic Native SQL Query with the EntityManager
Configuring Query Hints
Executing a Query
Modifying an Entity Instance
Using an Updating Query
Using the Entity's Public API
Refreshing from the Database
Removing an Entity
Using Flush
Detaching and Merging an Entity Bean Instance
Accessing an EJB 3.0 EJBContext
Using Resource Injection
Accessing an EJB 2.1 EJB
Accessing an EJB 2.1 EJB Remotely
Accessing an EJB 2.1 EJB Locally
Accessing an EJB 2.1 EJB Using RMI from a Standalone Java Client
Accessing an EJB 2.1 EJB in Another Application
Accessing an EJB 2.1 MDB
Sending a Message to a JMS Destination Using EJB 2.1
Sending a Message to a J2CA Destination Using EJB 2.1
Accessing an EJB 2.1 EJBContext
Handling Parameters
Passing Parameters Into an EJB
Handling Parameters Returned by an EJB
Handling Exceptions
Recovering From a NamingException While Accessing a Remote EJB
Recovering From a NullPointerException While Accessing a Remote EJB
Recovering From Deadlock Conditions
30
Using EJBs and Web Services
Exposing a Stateless Session Bean as a Web Service
Using Annotations
Accessing a Web Service from an EJB
Using Annotations
Using Initial Context
31
Administrating an EJB Application
OC4J EJB JMX Support
Using Oracle Enterprise Manager 10
g
Application Server Control
Configuring EJB Logging
Logging Namespaces
Logging Levels
Configuring Logging with Application Server Control Logging MBean
Configuring Logging Using the j2ee-logging.xml File
Configuring Logging Using System Properties
Managing the Bean Instance Pool
Configuring Bean Instance Pool Size
Using Deployment XML
Configuring Bean Instance Pool Timeouts for Session Beans
Using Deployment XML
Configuring Bean Instance Pool Timeouts for Entity Beans
Using Deployment XML
Starting and Stopping an EJB Application
Troubleshooting an EJB Application
Validating XML Files
Debugging the ejb-jar.xml File
Debugging Generated Code
Preserving Generated Code in the Default Directory
Preserving Generated Code in a Directory You Specify
Disabling Generated Code Preservation
A
XML Reference for orion-ejb-jar.xml Elements
OC4J and the orion-ejb-jar.xml File
TopLink Persistence Support
OC4J-Specific Deployment Descriptor for EJBs
Enterprise Beans Section
Persistence Manager Section (persistence-manager)
Session Bean Section (session-deployment)
Entity Bean Section (entity-deployment)
Message Driven Bean Section (message-driven-deployment)
EJB 1.1 CMP Field Mapping Section (cmp-field-mapping)
Method Definition
Assembly Descriptor Section
Element Description
Glossary
Index
