ejb core contracts and requirements - oracledownload.oracle.com/otn-pub/jcp/ejb-3.1-pfd-oth... ·...

EJB 3.1 Expert Group

Specification Lead:

Kenneth Saks, Sun Microsystems

Please send comments to: [email protected]

Propos

ed Fina

l Dr

Sun Microsystems

JSR 318: Enterprise JavaBeansTM,Version 3.1

EJB Core Contracts and Requirements

February 24, 2009Version 3.1, Proposed Final Draft

Enterprise JavaBeans 3.1, Proposed Final Draft Release Sun Microsystems, Inc.

Specification : JSR-000318 Enterprise JavaBeans(tm) Specification ("Specifica-tion")Version: 3.1Status: Proposed Final DraftRelease: 27 February 2009

Copyright 2009 Sun Microsystems, Inc.

4150 Network Circle, Santa Clara, California 95054, U.S.A

All rights reserved.

NOTICE

The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the follow-ing license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Sun Microsystems, Inc. (“Sun”) and its licensors, if any. Any use of the Speci-fication and the information described therein will be governed by the terms and conditions of this Agree-ment.

Subject to the terms and conditions of this license, including your compliance with Paragraphs 1 and 2 below, Sun hereby grants you a fully-paid, non-exclusive, non-transfereable, limited license (without the right to sublicense) under Sun’s intellectual property rights to:

1. Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a signifi-cant portion of the Technology.

2. Distribute implementations of the Specification to third parties for their testing and evaluation, use, provided that any such implementation:

(i) does not modify, subset, superset, or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented;

(ii) is clearly and prominently marked with the word “UNTESTED” or “EARLY ACCESS” or “IN-COMPATIBLE” or “UNSTABLE” or “BETA” in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee’s control; and

(iii) includes the following notice :

“This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP.”

The grant set forth above concerning your distribution of implementations of the specification is contin-gent upon your agreement to terminate development and distribution of your “early draft” implementa-tions as soon as feasible following final completion of the Specification. If you fail to do so, the foregoing grant shall be considered null and void.

No provision of this Agreement shall be understood to restrict your ability to make and distribute to third parties applications written to the Specification.

2 2/24/09


Other than this limited license, you acquire no right, title, or interest in or to the Specification or any other Sun intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In ad-dition, this license will terminate immediately without notice from Sun if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification.

“Licensor Name Space” means the public class or interface declarations whose names begin with “java”, “javax”, “com.sun” or their equivalents in any subsequent naming convention adopted by Sun through the Java Community Process, or any recognized successors or replacements thereof.

TRADEMARKS

No right, title, or interest in or to any trademarks, service marks, or trade names of Sun or Sun’s licensors is granted hereunder. Sun, Sun Microsystems, the Sun logo, Java, JavaBeans and EJB are trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

DISCLAIMER OF WARRANTIES

THE SPECIFICATION IS PROVIDED “AS IS” AND IS EXPERIMENTAL AND MAY CON-TAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY SUN. SUN MAKES NO REPRESENTATIONS OR WARRANTIES EITHER EXPRESS OR IM-PLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CON-TENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This doc-ument does not represent any commitment to release or implement any portion of the Specification in any product.

THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPO-GRAPHICAL ERORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. SUN MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.

LIMITATION OF LIABILITY

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICEN-SORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCI-DENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE HISTORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRAC-TICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You will hold Sun (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license.

RESTRICTED RIGHTS LEGEND

If this Software is being acquired by or on behalf of the U.S. Goverment or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government’s rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201

3 2/24/09


through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).

REPORT

You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification (“Feedback”). To the extent that you provide Sun with any Feed-back, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential ba-sis, and (ii) grant Sun a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without lim-itation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof.

GENERAL TERMS

Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.

The Specification is subject to U.S. export control laws and may be subject to export or import regula-tions in other countries. Licensee agrees to comply strictly with all such laws and regulations and ac-knowledges that it has the responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee.

This agreement is the parties’ entire agreement relating to its subject matter. It supercedes all prior or contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgement, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be binding, unless in writing and signed by an authorized represen-tative of each party.

4 2/24/09

Enterprise JavaBeans 3.1, Proposed Final Draft

Sun Microsystems, Inc.

Table of Contents

Chapter 1 Introduction.................................................................................................................... 271.1 Target Audience............................................................................................... 271.2 What is New in EJB 3.1 .................................................................................. 27

1.2.1 What Was New in EJB 3.0................................................................ 281.3 EJB 3.1 Expert Group...................................................................................... 291.4 Organization of the Specification Documents................................................. 291.5 Document Conventions ................................................................................... 29

Chapter 2 Overview........................................................................................................................ 312.1 Overall Goals................................................................................................... 312.2 EJB Roles ........................................................................................................ 32

2.2.1 Enterprise Bean Provider .................................................................. 332.2.2 Application Assembler...................................................................... 332.2.3 Deployer............................................................................................ 332.2.4 EJB Server Provider.......................................................................... 342.2.5 EJB Container Provider .................................................................... 342.2.6 Persistence Provider.......................................................................... 352.2.7 System Administrator ....................................................................... 35

2.3 Enterprise Beans.............................................................................................. 362.3.1 Characteristics of Enterprise Beans .................................................. 362.3.2 Flexible Model .................................................................................. 36

2.4 Session, Entity, and Message-Driven Objects................................................. 372.4.1 Session Objects ................................................................................. 372.4.2 Message-Driven Objects ................................................................... 382.4.3 Entity Objects.................................................................................... 38

2.5 Standard Mapping to CORBA Protocols ........................................................ 382.6 Mapping to Web Service Protocols ................................................................. 392.7 Pruning the EJB API ....................................................................................... 39

Chapter 3 Client View of a Session Bean....................................................................................... 413.1 Overview ......................................................................................................... 413.2 Local, Remote, and Web Service Client Views............................................... 43

3.2.1 Remote Clients.................................................................................. 433.2.2 Local Clients ..................................................................................... 433.2.3 Choosing Between a Local or Remote Client View ......................... 443.2.4 Web Service Clients .......................................................................... 45

3.3 EJB Container.................................................................................................. 463.4 Client View of Session Beans Written to the EJB 3.x Simplified API ........... 46

3.4.1 Obtaining a Session Bean’s Business Interface ................................ 463.4.2 Obtaining a Reference to the No-interface View .............................. 473.4.3 Session Bean’s Business Interface .................................................... 473.4.4 Session Bean’s No-Interface View.................................................... 48

5 2/24/09



3.4.5 Client View of Session Object’s Life Cycle...................................... 493.4.6 Example of Obtaining and Using a Session Object .......................... 493.4.7 Session Object Identity...................................................................... 51

3.4.7.1 Stateful Session Beans ........................................................ 513.4.7.2 Stateless Session Beans....................................................... 513.4.7.3 Singleton Session Beans ..................................................... 52

3.4.8 Asynchronous Invocations ................................................................ 523.4.8.1 Return Values...................................................................... 53

3.5 The Web Service Client View of a Session Bean ............................................ 543.5.1 JAX-WS Web Service Clients........................................................... 553.5.2 JAX-RPC Web Service Clients ......................................................... 56

3.6 Remote and Local Client View of Session Beans Written to the EJB 2.1 Client View API57

3.6.1 Locating a Session Bean’s Home Interface....................................... 573.6.2 Session Bean’s Remote Home Interface ........................................... 58

3.6.2.1 Creating a Session Object ................................................... 583.6.2.2 Removing a Session Object ................................................ 59

3.6.3 Session Bean’s Local Home Interface............................................... 593.6.3.1 Creating a Session Object ................................................... 603.6.3.2 Removing a Session Object ................................................ 60

3.6.4 EJBObject and EJBLocalObject ....................................................... 603.6.5 Object Identity................................................................................... 613.6.6 Client view of Session Object’s Life Cycle ...................................... 62

3.6.6.1 References to Session Object Remote Interfaces ............... 623.6.6.2 References to Session Object Local Interfaces................... 63

3.6.7 Creating and Using a Session Object ................................................ 633.6.8 Object Identity................................................................................... 65

3.6.8.1 Stateful Session Beans ........................................................ 653.6.8.2 Stateless Session Beans....................................................... 653.6.8.3 getPrimaryKey() ................................................................. 66

3.6.9 Type Narrowing................................................................................. 66

Chapter 4 Session Bean Component Contract................................................................................ 674.1 Overview ......................................................................................................... 674.2 Conversational State of a Stateful Session Bean ............................................. 68

4.2.1 Instance Passivation and Conversational State ................................. 694.2.2 The Effect of Transaction Rollback on Conversational State ........... 71

4.3 Protocol Between a Session Bean Instance and its Container......................... 724.3.1 Required Session Bean Metadata...................................................... 724.3.2 Dependency Injection........................................................................ 724.3.3 The SessionContext Interface............................................................ 724.3.4 Session Bean Lifecycle Callback Interceptor Methods..................... 744.3.5 The Optional SessionBean Interface ................................................. 754.3.6 Use of the MessageContext Interface by Session Beans................... 764.3.7 The Optional Session Synchronization Notifications for Stateful Session

Beans764.3.8 Timeout Callbacks for Stateless and Singleton Session Beans ......... 774.3.9 Business Method Delegation............................................................. 77

2/24/09 6



4.3.10 Session Bean Creation ...................................................................... 774.3.10.1 Stateful Session Beans........................................................ 784.3.10.2 Stateless Session Beans ...................................................... 78

4.3.11 Stateful Session Bean Removal ........................................................ 784.3.12 Stateful Session Bean Timeout ......................................................... 794.3.13 Business Method Interceptor Methods for Session Beans................ 794.3.14 Serializing Session Bean Methods.................................................... 79

4.3.14.1 Stateful Session Bean Concurrent Access Timeouts .......... 804.3.15 Transaction Context of Session Bean Methods ................................ 81

4.4 Global JNDI Access ........................................................................................ 814.4.1 Syntax................................................................................................ 814.4.2 Examples........................................................................................... 82

4.4.2.1 Session bean exposing a single local business interface .... 824.4.2.2 Session bean exposing multiple client views ..................... 84

4.5 Asynchronous Methods ................................................................................... 844.5.1 Metadata............................................................................................ 844.5.2 Method Requirements ....................................................................... 85

4.5.2.1 Business Interfaces ............................................................. 854.5.2.2 Bean Classes ....................................................................... 85

4.5.3 Transactions ...................................................................................... 864.5.4 Security ............................................................................................. 864.5.5 Client Exception Behavior ................................................................ 86

4.6 Stateful Session Bean State Diagram .............................................................. 874.6.1 Operations Allowed in the Methods of a Stateful Session Bean Class914.6.2 Dealing with Exceptions ................................................................... 954.6.3 Missed PreDestroy Calls ................................................................... 964.6.4 Restrictions for Transactions............................................................. 96

4.7 Stateless Session Beans ................................................................................... 974.7.1 Stateless Session Bean State Diagram .............................................. 984.7.2 Operations Allowed in the Methods of a Stateless Session Bean Class1004.7.3 Dealing with Exceptions ................................................................... 104

4.8 Singleton Session Beans.................................................................................. 1054.8.1 Singleton Initialization...................................................................... 1064.8.2 Singleton Destruction........................................................................ 1084.8.3 Transaction Semantics of Initialization and Destruction .................. 1084.8.4 Singleton Error Handling .................................................................. 1084.8.5 Singleton Concurrency...................................................................... 108

4.8.5.1 Container Managed Concurrency....................................... 1094.8.5.2 Bean Managed Concurrency .............................................. 1104.8.5.3 Specification of a Concurrency Management Type............ 1104.8.5.4 Specification of the Container Managed Concurrency Metadata for

a Bean’s Methods1114.8.5.5 Specification of Concurrency Locking Attributes with Metadata

Annotations1124.8.6 Operations Allowed in the Methods of a Singleton Session Bean ... 114

4.9 The Responsibilities of the Bean Provider ...................................................... 1184.9.1 Classes and Interfaces ....................................................................... 1194.9.2 Session Bean Class............................................................................ 119

4.9.2.1 Session Bean Superclasses ................................................. 120

7 2/24/09



4.9.3 Lifecycle Callback Interceptor Methods ........................................... 1214.9.4 Session Synchronization Methods .................................................... 1214.9.5 ejbCreate Methods....................................................... 1224.9.6 Business Methods.............................................................................. 1224.9.7 Session Bean’s Business Interface .................................................... 1234.9.8 Session Bean’s No-Interface View.................................................... 1244.9.9 Session Bean’s Remote Interface ...................................................... 125

4.9.10 Session Bean’s Remote Home Interface ........................................... 1254.9.11 Session Bean’s Local Interface ......................................................... 1264.9.12 Session Bean’s Local Home Interface............................................... 1264.9.13 Session Bean’s Web Service Endpoint Interface............................... 127

4.10 The Responsibilities of the Container Provider............................................... 1284.10.1 Generation of Implementation Classes ............................................. 1284.10.2 Generation of WSDL ........................................................................ 1294.10.3 Session Business Interface Implementation Class ............................ 1294.10.4 No-Interface View Reference Class .................................................. 1294.10.5 Session EJBHome Class.................................................................... 1304.10.6 Session EJBObject Class................................................................... 1304.10.7 Session EJBLocalHome Class .......................................................... 1304.10.8 Session EJBLocalObject Class.......................................................... 1304.10.9 Web Service Endpoint Implementation Class ................................... 131

4.10.10 Asynchronous Client Future Return Value Implementation Class1314.10.11 Handle Classes .................................................................................. 1314.10.12 EJBMetaData Class........................................................................... 1314.10.13 Non-reentrant Instances..................................................................... 1314.10.14 Transaction Scoping, Security, Exceptions ....................................... 1314.10.15 JAX-WS and JAX-RPC Message Handlers for Web Service Endpoints1314.10.16 SessionContext .................................................................................. 132

Chapter 5 Message-Driven Bean Component Contract.................................................................. 1335.1 Overview ......................................................................................................... 1335.2 Goals ................................................................................................................ 1345.3 Client View of a Message-Driven Bean .......................................................... 1345.4 Protocol Between a Message-Driven Bean Instance and its Container........... 136

5.4.1 Required MessageDrivenBean Metadata .......................................... 1365.4.2 The Required Message Listener Interface......................................... 1365.4.3 Dependency Injection........................................................................ 1375.4.4 The MessageDrivenContext Interface............................................... 1375.4.5 Message-Driven Bean Lifecycle Callback Interceptor Methods ...... 1385.4.6 The Optional MessageDrivenBean Interface .................................... 1385.4.7 Timeout Callbacks............................................................................. 1395.4.8 Message-Driven Bean Creation ........................................................ 1395.4.9 Message Listener Interceptor Methods for Message-Driven Beans . 139

5.4.10 Serializing Message-Driven Bean Methods...................................... 1405.4.11 Concurrency of Message Processing................................................. 1405.4.12 Transaction Context of Message-Driven Bean Methods .................. 1405.4.13 Security Context of Message-Driven Bean Methods........................ 1405.4.14 Activation Configuration Properties ................................................. 141

2/24/09 8



5.4.15 Message Acknowledgment for JMS Message-Driven Beans ........... 1415.4.16 Message Selectors for JMS Message-Driven Beans......................... 1415.4.17 Association of a Message-Driven Bean with a Destination or Endpoint142

5.4.17.1 JMS Message-Driven Beans............................................... 1425.4.18 Dealing with Exceptions ................................................................... 1435.4.19 Missed PreDestroy Callbacks ........................................................... 1435.4.20 Replying to a JMS Message.............................................................. 144

5.5 Message-Driven Bean State Diagram ............................................................. 1445.5.1 Operations Allowed in the Methods of a Message-Driven Bean Class146

5.6 The Responsibilities of the Bean Provider ...................................................... 1485.6.1 Classes and Interfaces ....................................................................... 1485.6.2 Message-Driven Bean Class ............................................................. 1485.6.3 Message-Driven Bean Superclasses.................................................. 1495.6.4 Message Listener Method ................................................................. 1495.6.5 Lifecycle Callback Interceptor Methods........................................... 150

5.7 The Responsibilities of the Container Provider............................................... 1505.7.1 Generation of Implementation Classes ............................................. 1505.7.2 Deployment of JMS Message-Driven Beans .................................... 1505.7.3 Request/Response Messaging Types ................................................ 1515.7.4 Non-reentrant Instances .................................................................... 1515.7.5 Transaction Scoping, Security, Exceptions ....................................... 151

Chapter 6 Persistence ..................................................................................................................... 153

Chapter 7 Client View of an EJB 2.1 Entity Bean ......................................................................... 1557.1 Overview ......................................................................................................... 1557.2 Remote Clients ................................................................................................ 1567.3 Local Clients.................................................................................................... 1577.4 EJB Container.................................................................................................. 157

7.4.1 Locating an Entity Bean’s Home Interface ....................................... 1587.4.2 What a Container Provides ............................................................... 158

7.5 Entity Bean’s Remote Home Interface ............................................................ 1597.5.1 Create Methods ................................................................................. 1607.5.2 Finder Methods ................................................................................. 1617.5.3 Remove Methods .............................................................................. 1627.5.4 Home Methods.................................................................................. 162

7.6 Entity Bean’s Local Home Interface ............................................................... 1637.6.1 Create Methods ................................................................................. 1637.6.2 Finder Methods ................................................................................. 1647.6.3 Remove Methods .............................................................................. 1647.6.4 Home Methods.................................................................................. 165

7.7 Entity Object’s Life Cycle ............................................................................... 1657.7.1 References to Entity Object Remote Interfaces ................................ 1677.7.2 References to Entity Object Local Interfaces ................................... 167

7.8 Primary Key and Object Identity..................................................................... 1687.9 Entity Bean’s Remote Interface....................................................................... 169

9 2/24/09



7.10 Entity Bean’s Local Interface .......................................................................... 1707.11 Entity Bean’s Handle ....................................................................................... 1717.12 Entity Home Handles....................................................................................... 1727.13 Type Narrowing of Object References ............................................................ 172

Chapter 8 EJB 2.1 Entity Bean Component Contract for Container-Managed Persistence ........... 1738.1 Overview ......................................................................................................... 1748.2 Container-Managed Entity Persistence and Data Independence ..................... 1748.3 The Entity Bean Provider’s View of Container-Managed Persistence............ 176

8.3.1 The Entity Bean Provider’s Programming Contract ......................... 1778.3.2 The Entity Bean Provider’s View of Persistent Relationships .......... 1798.3.3 Dependent Value Classes .................................................................. 1798.3.4 Remove Protocols ............................................................................. 180

8.3.4.1 Remove Methods ................................................................ 1808.3.4.2 Cascade-delete .................................................................... 181

8.3.5 Identity of Entity Objects .................................................................. 1818.3.6 Semantics of Assignment for Relationships...................................... 182

8.3.6.1 Use of the java.util.Collection API to Update Relationships1828.3.6.2 Use of Set Accessor Methods to Update Relationships...... 184

8.3.7 Assignment Rules for Relationships ................................................. 1858.3.7.1 One-to-one Bidirectional Relationships.............................. 1868.3.7.2 One-to-one Unidirectional Relationships ........................... 1878.3.7.3 One-to-many Bidirectional Relationships .......................... 1888.3.7.4 One-to-many Unidirectional Relationships ........................ 1928.3.7.5 Many-to-one Unidirectional Relationships......................... 1958.3.7.6 Many-to-many Bidirectional Relationships........................ 1978.3.7.7 Many-to-many Unidirectional Relationships...................... 201

8.3.8 Collections Managed by the Container ............................................. 2048.3.9 Non-persistent State .......................................................................... 204

8.3.10 The Relationship Between the Internal View and the Client View... 2058.3.10.1 Restrictions on Remote Interfaces ...................................... 205

8.3.11 Mapping Data to a Persistent Store ................................................... 2058.3.12 Example............................................................................................. 2068.3.13 The Bean Provider’s View of the Deployment Descriptor................ 209

8.4 The Entity Bean Component Contract............................................................. 2138.4.1 Runtime Execution Model of Entity Beans....................................... 2138.4.2 Container Responsibilities................................................................. 215

8.4.2.1 Container-Managed Fields.................................................. 2158.4.2.2 Container-Managed Relationships...................................... 215

8.5 Instance Life Cycle Contract Between the Bean and the Container................ 2168.5.1 Instance Life Cycle............................................................................ 2178.5.2 Bean Provider’s Entity Bean Instance’s View................................... 2198.5.3 Container’s View............................................................................... 2238.5.4 Read-only Entity Beans..................................................................... 2278.5.5 The EntityContext Interface .............................................................. 2288.5.6 Operations Allowed in the Methods of the Entity Bean Class.......... 2298.5.7 Finder Methods ................................................................................. 231

2/24/09 10



8.5.7.1 Single-Object Finder Methods............................................ 2328.5.7.2 Multi-Object Finder Methods ............................................. 232

8.5.8 Select Methods.................................................................................. 2338.5.8.1 Single-Object Select Methods ............................................ 2348.5.8.2 Multi-Object Select Methods.............................................. 234

8.5.9 Timer Notifications ........................................................................... 2358.5.10 Standard Application Exceptions for Entities ................................... 235

8.5.10.1 CreateException.................................................................. 2358.5.10.2 DuplicateKeyException...................................................... 2368.5.10.3 FinderException.................................................................. 2368.5.10.4 ObjectNotFoundException ................................................. 2368.5.10.5 RemoveException............................................................... 237

8.5.11 Commit Options................................................................................ 2378.5.12 Concurrent Access from Multiple Transactions ............................... 2398.5.13 Non-reentrant and Re-entrant Instances............................................ 240

8.6 Responsibilities of the Enterprise Bean Provider............................................ 2418.6.1 Classes and Interfaces ....................................................................... 2418.6.2 Enterprise Bean Class ....................................................................... 2418.6.3 Dependent Value Classes .................................................................. 2428.6.4 ejbCreate Methods....................................................... 2428.6.5 ejbPostCreate Methods................................................ 2438.6.6 ejbHome Methods ....................................................... 2448.6.7 ejbSelect Methods ....................................................... 2448.6.8 Business Methods ............................................................................. 2448.6.9 Entity Bean’s Remote Interface ........................................................ 245

8.6.10 Entity Bean’s Remote Home Interface.............................................. 2458.6.11 Entity Bean’s Local Interface............................................................ 2468.6.12 Entity Bean’s Local Home Interface................................................. 2478.6.13 Entity Bean’s Primary Key Class...................................................... 2488.6.14 Entity Bean’s Deployment Descriptor .............................................. 248

8.7 The Responsibilities of the Container Provider............................................... 2488.7.1 Generation of Implementation Classes ............................................. 2498.7.2 Enterprise Bean Class ....................................................................... 2498.7.3 ejbFind Methods.......................................................... 2508.7.4 ejbSelect Methods ....................................................... 2508.7.5 Entity EJBHome Class...................................................................... 2518.7.6 Entity EJBObject Class ..................................................................... 2518.7.7 Entity EJBLocalHome Class............................................................. 2518.7.8 Entity EJBLocalObject Class............................................................ 2528.7.9 Handle Class ..................................................................................... 252

8.7.10 Home Handle Class........................................................................... 2528.7.11 Metadata Class .................................................................................. 2538.7.12 Instance’s Re-entrance ...................................................................... 2538.7.13 Transaction Scoping, Security, Exceptions ....................................... 2538.7.14 Implementation of Object References............................................... 2538.7.15 EntityContext .................................................................................... 253

8.8 Primary Keys ................................................................................................... 2548.8.1 Primary Key That Maps to a Single Field in the Entity Bean Class. 2548.8.2 Primary Key That Maps to Multiple Fields in the Entity Bean Class254

11 2/24/09



8.8.3 Special Case: Unknown Primary Key Class ..................................... 254

Chapter 9 EJB QL: EJB 2.1 Query Language for Container-Managed Persistence Query Methods2579.1 Overview ......................................................................................................... 2589.2 EJB QL Definition........................................................................................... 258

9.2.1 Abstract Schema Types and Query Domains .................................... 2599.2.2 Query Methods.................................................................................. 2609.2.3 Naming .............................................................................................. 2609.2.4 Examples ........................................................................................... 2619.2.5 The FROM Clause and Navigational Declarations........................... 262

9.2.5.1 Identifiers ............................................................................ 2639.2.5.2 Identification Variables ....................................................... 2639.2.5.3 Range Variable Declarations............................................... 2649.2.5.4 Collection Member Declarations ........................................ 2659.2.5.5 Example .............................................................................. 2659.2.5.6 Path Expressions ................................................................. 265

9.2.6 WHERE Clause and Conditional Expressions.................................. 2669.2.6.1 Literals ................................................................................ 2679.2.6.2 Identification Variables ....................................................... 2679.2.6.3 Path Expressions ................................................................. 2679.2.6.4 Input Parameters ................................................................. 2689.2.6.5 Conditional Expression Composition ................................. 2689.2.6.6 Operators and Operator Precedence ................................... 2689.2.6.7 Between Expressions .......................................................... 2699.2.6.8 In Expressions..................................................................... 2699.2.6.9 Like Expressions ................................................................. 270

9.2.6.10 Null Comparison Expressions ............................................ 2709.2.6.11 Empty Collection Comparison Expressions ....................... 2719.2.6.12 Collection Member Expressions......................................... 2719.2.6.13 Functional Expressions ....................................................... 272

9.2.7 SELECT Clause ................................................................................ 2739.2.7.1 Null Values in the Query Result ......................................... 2739.2.7.2 Aggregate Functions in the SELECT Clause ..................... 2749.2.7.3 Examples............................................................................. 274

9.2.8 ORDER BY Clause........................................................................... 2759.2.9 Return Value Types ........................................................................... 276

9.2.10 Null Values ........................................................................................ 2789.2.11 Equality and Comparison Semantics................................................. 2799.2.12 Restrictions........................................................................................ 279

9.3 Examples ......................................................................................................... 2799.3.1 Simple Queries .................................................................................. 2809.3.2 Queries with Relationships................................................................ 2809.3.3 Queries Using Input Parameters........................................................ 2819.3.4 Queries for Select Methods ............................................................... 2819.3.5 EJB QL and SQL............................................................................... 282

9.4 EJB QL BNF ................................................................................................... 283

2/24/09 12



Chapter 10 EJB 2.1 Entity Bean Component Contract for Bean-Managed Persistence .................. 28710.1 Overview of Bean-Managed Entity Persistence.............................................. 288

10.1.1 Entity Bean Provider’s View of Persistence ..................................... 28810.1.2 Runtime Execution Model ................................................................ 28910.1.3 Instance Life Cycle ........................................................................... 29110.1.4 The Entity Bean Component Contract .............................................. 293

10.1.4.1 Entity Bean Instance’s View............................................... 29310.1.4.2 Container’s View ................................................................ 297

10.1.5 Read-only Entity Beans .................................................................... 30010.1.6 The EntityContext Interface.............................................................. 30010.1.7 Operations Allowed in the Methods of the Entity Bean Class ......... 30110.1.8 Caching of Entity State and the ejbLoad and ejbStore Methods ...... 304

10.1.8.1 ejbLoad and ejbStore with the NotSupported Transaction Attribute305

10.1.9 Finder Method Return Type .............................................................. 30610.1.9.1 Single-Object Finder........................................................... 30610.1.9.2 Multi-Object Finders .......................................................... 306

10.1.10 Timer Notifications ........................................................................... 30810.1.11 Standard Application Exceptions for Entities ................................... 308

10.1.11.1 CreateException.................................................................. 30810.1.11.2 DuplicateKeyException...................................................... 30910.1.11.3 FinderException.................................................................. 30910.1.11.4 ObjectNotFoundException ................................................. 30910.1.11.5 RemoveException............................................................... 310

10.1.12 Commit Options................................................................................ 31010.1.13 Concurrent Access from Multiple Transactions ............................... 31110.1.14 Non-reentrant and Re-entrant Instances............................................ 313

10.2 Responsibilities of the Enterprise Bean Provider............................................ 31410.2.1 Classes and Interfaces ....................................................................... 31410.2.2 Enterprise Bean Class ....................................................................... 31410.2.3 ejbCreate Methods....................................................... 31510.2.4 ejbPostCreate Methods................................................ 31610.2.5 ejbFind Methods ............................................................................... 31610.2.6 ejbHome Methods ....................................................... 31710.2.7 Business Methods ............................................................................. 31710.2.8 Entity Bean’s Remote Interface ........................................................ 31810.2.9 Entity Bean’s Remote Home Interface.............................................. 319

10.2.10 Entity Bean’s Local Interface............................................................ 32010.2.11 Entity Bean’s Local Home Interface................................................. 32010.2.12 Entity Bean’s Primary Key Class...................................................... 321

10.3 The Responsibilities of the Container Provider............................................... 32210.3.1 Generation of Implementation Classes ............................................. 32210.3.2 Entity EJBHome Class...................................................................... 32310.3.3 Entity EJBObject Class ..................................................................... 32310.3.4 Entity EJBLocalHome Class............................................................. 32310.3.5 Entity EJBLocalObject Class............................................................ 32410.3.6 Handle Class ..................................................................................... 32410.3.7 Home Handle Class........................................................................... 32410.3.8 Metadata Class .................................................................................. 325

13 2/24/09



10.3.9 Instance’s Re-entrance....................................................................... 32510.3.10 Transaction Scoping, Security, Exceptions ....................................... 32510.3.11 Implementation of Object References............................................... 32510.3.12 EntityContext .................................................................................... 325

Chapter 11 EJB 1.1 Entity Bean Component Contract for Container-Managed Persistence ........... 32711.1 EJB 1.1 Entity Beans with Container-Managed Persistence ........................... 327

11.1.1 Container-Managed Fields ................................................................ 32811.1.2 ejbCreate, ejbPostCreate ................................................................... 32911.1.3 ejbRemove......................................................................................... 33011.1.4 ejbLoad.............................................................................................. 33011.1.5 ejbStore.............................................................................................. 33011.1.6 Finder Hethods .................................................................................. 33111.1.7 Home Methods .................................................................................. 33111.1.8 Create Methods ................................................................................. 33111.1.9 Primary Key Type ............................................................................. 331

11.1.9.1 Primary Key that Maps to a Single Field in the Entity Bean Class331

11.1.9.2 Primary Key that Maps to Multiple Fields in the Entity Bean Class332

11.1.9.3 Special Case: Unknown Primary Key Class....................... 332

Chapter 12 Interceptors..................................................................................................................... 33312.1 Overview ......................................................................................................... 33312.2 Interceptor Life Cycle...................................................................................... 33412.3 Business Method Interceptors ......................................................................... 334

12.3.1 Exceptions ......................................................................................... 33412.4 Timer Timeout Method Interceptors................................................................ 335

12.4.1 Exceptions ......................................................................................... 33512.5 Interceptors for LifeCycle Event Callbacks .................................................... 335

12.5.1 Exceptions ......................................................................................... 33512.6 InvocationContext ........................................................................................... 33612.7 Specification of Interceptors in the Deployment Descriptor ........................... 336

Chapter 13 Support for Transactions ................................................................................................ 33713.1 Overview ......................................................................................................... 337

13.1.1 Transactions....................................................................................... 33713.1.2 Transaction Model............................................................................. 33813.1.3 Relationship to JTA and JTS............................................................. 339

13.2 Sample Scenarios............................................................................................. 33913.2.1 Update of Multiple Databases ........................................................... 33913.2.2 Messages Sent or Received Over JMS Sessions and Update of Multiple

Databases34013.2.3 Update of Databases via Multiple EJB Servers ................................ 34213.2.4 Client-Managed Demarcation ........................................................... 34313.2.5 Container-Managed Demarcation ..................................................... 344

2/24/09 14



13.3 Bean Provider’s Responsibilities..................................................................... 34513.3.1 Bean-Managed Versus Container-Managed Transaction Demarcation345

13.3.1.1 Non-Transactional Execution ............................................. 34513.3.2 Isolation Levels ................................................................................. 34613.3.3 Enterprise Beans Using Bean-Managed Transaction Demarcation .. 346

13.3.3.1 getRollbackOnly and setRollbackOnly Methods ............... 35113.3.4 Enterprise Beans Using Container-Managed Transaction Demarcation352

13.3.4.1 javax.ejb.SessionSynchronization Interface ....................... 35313.3.4.2 javax.ejb.EJBContext.setRollbackOnly Method ................ 35413.3.4.3 javax.ejb.EJBContext.getRollbackOnly method ................ 354

13.3.5 Use of JMS APIs in Transactions ..................................................... 35413.3.6 Specification of a Bean’s Transaction Management Type ................ 35413.3.7 Specification of the Transaction Attributes for a Bean’s Methods ... 355

13.3.7.1 Specification of Transaction Attributes with Metadata Annotations358

13.3.7.2 Specification of Transaction Attributes in the Deployment Descrip-tor359

13.4 Application Assembler’s Responsibilities....................................................... 36213.5 Deployer’s Responsibilities............................................................................. 36213.6 Container Provider Responsibilities ................................................................ 362

13.6.1 Bean-Managed Transaction Demarcation......................................... 36313.6.2 Container-Managed Transaction Demarcation for Session and Entity Beans

36613.6.2.1 NOT_SUPPORTED ........................................................... 36613.6.2.2 REQUIRED ........................................................................ 36613.6.2.3 SUPPORTS......................................................................... 36713.6.2.4 REQUIRES_NEW.............................................................. 36713.6.2.5 MANDATORY................................................................... 36713.6.2.6 NEVER............................................................................... 36813.6.2.7 Transaction Attribute Summary ......................................... 36813.6.2.8 Handling of setRollbackOnly Method................................ 36913.6.2.9 Handling of getRollbackOnly Method ............................... 369

13.6.2.10 Handling of getUserTransaction Method ........................... 37013.6.2.11 Session Synchronization Callbacks .................................... 37013.6.2.12 Timing of Return Value Marshalling w.r.t. Transaction Boundaries

37013.6.3 Container-Managed Transaction Demarcation for Message-Driven Beans

37013.6.3.1 NOT_SUPPORTED ........................................................... 37113.6.3.2 REQUIRED ........................................................................ 37113.6.3.3 Handling of setRollbackOnly Method................................ 37113.6.3.4 Handling of getRollbackOnly Method ............................... 37213.6.3.5 Handling of getUserTransaction Method ........................... 372

13.6.4 Local Transaction Optimization........................................................ 37213.6.5 Handling of Methods that Run with “an unspecified transaction context”372

13.7 Access from Multiple Clients in the Same Transaction Context..................... 37313.7.1 Transaction “Diamond” Scenario with an Entity Object .................. 37413.7.2 Container Provider’s Responsibilities............................................... 37513.7.3 Bean Provider’s Responsibilities ...................................................... 37513.7.4 Application Assembler and Deployer’s Responsibilities.................. 375

15 2/24/09



13.7.5 Transaction Diamonds involving Session Objects............................ 375

Chapter 14 Exception Handling........................................................................................................ 37714.1 Overview and Concepts................................................................................... 377

14.1.1 Application Exceptions ..................................................................... 37714.1.2 Goals for Exception Handling........................................................... 378

14.2 Bean Provider’s Responsibilities ..................................................................... 37814.2.1 Application Exceptions ..................................................................... 37814.2.2 System Exceptions ............................................................................ 380

14.2.2.1 javax.ejb.NoSuchEntityException ...................................... 38114.3 Container Provider Responsibilities ................................................................ 382

14.3.1 Exceptions from a Session Bean’s Business Interface Methods and No-Inter-face View Methods382

14.3.2 Exceptions from Method Invoked via Session or Entity Bean’s 2.1 Client View or through Web Service Client View385

14.3.3 Exceptions from PostConstruct and PreDestroy Methods of a Session Bean389

14.3.4 Exceptions from Message-Driven Bean Message Listener Methods 38914.3.5 Exceptions from PostConstruct and PreDestroy Methods of a Mes-

sage-Driven Bean39114.3.6 Exceptions from an Enterprise Bean’s Timeout Callback Method ... 39114.3.7 Exceptions from Other Container-invoked Callbacks ...................... 39214.3.8 javax.ejb.NoSuchEntityException .................................................... 39314.3.9 Non-existing Stateful Session or Entity Object................................. 394

14.3.10 Exceptions from the Management of Container-Managed Transactions39414.3.11 Release of Resources......................................................................... 39414.3.12 Support for Deprecated Use of java.rmi.RemoteException.............. 395

14.4 Client’s View of Exceptions ............................................................................ 39514.4.1 Application Exception....................................................................... 396

14.4.1.1 Local and Remote Clients................................................... 39614.4.1.2 Web Service Clients ............................................................ 396

14.4.2 java.rmi.RemoteException and javax.ejb.EJBException.................. 39614.4.2.1 javax.ejb.EJBTransactionRolledbackException, javax.ejb.Transac-

tionRolledbackLocalException, and javax.transaction.Transaction-RolledbackException397

14.4.2.2 javax.ejb.EJBTransactionRequiredException, javax.ejb.Transac-tionRequiredLocalException, and javax.transaction.TransactionRe-quiredException398

14.4.2.3 javax.ejb.NoSuchEJBException, javax.ejb.NoSuchObjectLocalEx-ception, and java.rmi.NoSuchObjectException398

14.5 System Administrator’s Responsibilities......................................................... 398

Chapter 15 Support for Distributed Interoperability ........................................................................ 39915.1 Support for Distribution................................................................................... 399

15.1.1 Client-Side Objects in a Distributed Environment............................ 40015.2 Interoperability Overview................................................................................ 400

15.2.1 Interoperability Goals........................................................................ 40115.3 Interoperability Scenarios................................................................................ 402

2/24/09 16



15.3.1 Interactions Between Web Containers and EJB Containers for E-Commerce Applications402

15.3.2 Interactions Between Application Client Containers and EJB Containers Within an Enterprise’s Intranet403

15.3.3 Interactions Between Two EJB Containers in an Enterprise’s Intranet40415.3.4 Intranet Application Interactions Between Web Containers and EJB Contain-

ers40515.4 Overview of Interoperability Requirements.................................................... 40515.5 Remote Invocation Interoperability................................................................. 406

15.5.1 Mapping Java Remote Interfaces to IDL .......................................... 40715.5.2 Mapping Value Objects to IDL ......................................................... 40715.5.3 Mapping of System Exceptions ........................................................ 40715.5.4 Obtaining Stub and Client View Classes .......................................... 40815.5.5 System Value Classes........................................................................ 408

15.5.5.1 HandleDelegate SPI............................................................ 40915.6 Transaction Interoperability ............................................................................ 410

15.6.1 Transaction Interoperability Requirements....................................... 41015.6.1.1 Transaction Context Wire Format ...................................... 41015.6.1.2 Two-Phase Commit Protocol.............................................. 41015.6.1.3 Transactional Policies of Enterprise Bean References ....... 41215.6.1.4 Exception Handling Behavior ............................................ 412

15.6.2 Interoperating with Containers that do not Implement Transaction Interoper-ability412

15.6.2.1 Client Container Requirements .......................................... 41315.6.2.2 EJB container requirements................................................ 413

15.7 Naming Interoperability .................................................................................. 41515.8 Security Interoperability.................................................................................. 416

15.8.1 Introduction....................................................................................... 41615.8.1.1 Trust Relationships Between Containers, Principal Propagation41715.8.1.2 Application Client Authentication...................................... 418

15.8.2 Securing EJB Invocations ................................................................. 41815.8.2.1 Secure Transport Protocol .................................................. 41915.8.2.2 Security Information in IORs ............................................. 42015.8.2.3 Propagating Principals and Authentication Data in IIOP Messages

42015.8.2.4 Security Configuration for Containers ............................... 42215.8.2.5 Runtime Behavior............................................................... 422

Chapter 16 Enterprise Bean Environment ........................................................................................ 42516.1 Overview ......................................................................................................... 42516.2 Enterprise Bean’s Environment as a JNDI Naming Context........................... 427

16.2.1 Sharing of Environment Entries........................................................ 42716.2.2 Annotations for Environment Entries ............................................... 42816.2.3 Annotations and Deployment Descriptors ........................................ 430

16.3 Responsibilities by EJB Role .......................................................................... 43016.3.1 Bean Provider’s Responsibilities ...................................................... 43116.3.2 Application Assembler’s Responsibility........................................... 43116.3.3 Deployer’s Responsibility................................................................. 431

17 2/24/09



16.3.4 Container Provider Responsibility .................................................... 43116.4 Simple Environment Entries............................................................................ 432

16.4.1 Bean Provider’s Responsibilities ...................................................... 43216.4.1.1 Injection of Simple Environment Entries Using Annotations43216.4.1.2 Programming Interfaces for Accessing Simple Environment Entries

43316.4.1.3 Declaration of Simple Environment Entries in the Deployment

Descriptor43416.4.2 Application Assembler’s Responsibility ........................................... 43816.4.3 Deployer’s Responsibility ................................................................. 43816.4.4 Container Provider Responsibility .................................................... 438

16.5 EJB References................................................................................................ 43916.5.1 Bean Provider’s Responsibilities ...................................................... 439

16.5.1.1 Injection of EJB References ............................................... 43916.5.1.2 EJB Reference Programming Interfaces............................. 44016.5.1.3 Declaration of EJB References in Deployment Descriptor 441

16.5.2 Application Assembler’s Responsibilities ........................................ 44316.5.2.1 Overriding Rules................................................................. 446

16.5.3 Deployer’s Responsibility ................................................................. 44616.5.4 Container Provider’s Responsibility ................................................. 447

16.6 Web Service References .................................................................................. 44716.7 Resource Manager Connection Factory References........................................ 448

16.7.1 Bean Provider’s Responsibilities ...................................................... 44816.7.1.1 Injection of Resource Manager Connection Factory References44816.7.1.2 Programming Interfaces for Resource Manager Connection Factory

References44916.7.1.3 Declaration of Resource Manager Connection Factory References

in Deployment Descriptor45016.7.1.4 Standard Resource Manager Connection Factory Types .... 452

16.7.2 Deployer’s Responsibility ................................................................. 45316.7.3 Container Provider Responsibility .................................................... 45316.7.4 System Administrator’s Responsibility............................................. 455

16.8 Resource Environment References.................................................................. 45516.8.1 Bean Provider’s Responsibilities ...................................................... 455

16.8.1.1 Injection of Resource Environment References ................. 45516.8.1.2 Resource Environment Reference Programming Interfaces45516.8.1.3 Declaration of Resource Environment References in Deployment

Descriptor45616.8.2 Deployer’s Responsibility ................................................................. 45616.8.3 Container Provider’s Responsibility ................................................. 456

16.9 Message Destination References ..................................................................... 45716.9.1 Bean Provider’s Responsibilities ...................................................... 457

16.9.1.1 Injection of Message Destination References..................... 45716.9.1.2 Message Destination Reference Programming Interfaces .. 45716.9.1.3 Declaration of Message Destination References in Deployment

Descriptor45916.9.2 Application Assembler’s Responsibilities ........................................ 46016.9.3 Deployer’s Responsibility ................................................................. 46216.9.4 Container Provider’s Responsibility ................................................. 462

16.10 Persistence Unit References ............................................................................ 463

2/24/09 18



16.10.1 Bean Provider’s Responsibilities ...................................................... 46316.10.1.1 Injection of Persistence Unit References............................ 46316.10.1.2 Programming Interfaces for Persistence Unit References .. 46316.10.1.3 Declaration of Persistence Unit References in Deployment Descrip-

tor46416.10.2 Application Assembler’s Responsibilities ........................................ 466

16.10.2.1 Overriding Rules................................................................. 46616.10.3 Deployer’s Responsibility................................................................. 46716.10.4 Container Provider Responsibility .................................................... 46716.10.5 System Administrator’s Responsibility ............................................ 467

16.11 Persistence Context References....................................................................... 46816.11.1 Bean Provider’s Responsibilities ...................................................... 468

16.11.1.1 Injection of Persistence Context References ...................... 46816.11.1.2 Programming Interfaces for Persistence Context References46816.11.1.3 Declaration of Persistence Context References in Deployment

Descriptor46916.11.2 Application Assembler’s Responsibilities ........................................ 471

16.11.2.1 Overriding Rules................................................................. 47116.11.3 Deployer’s Responsibility................................................................. 47216.11.4 Container Provider Responsibility .................................................... 47216.11.5 System Administrator’s Responsibility ............................................ 472

16.12 UserTransaction Interface................................................................................ 47316.12.1 Bean Provider’s Responsibility......................................................... 47416.12.2 Container Provider’s Responsibility ................................................. 474

16.13 ORB References .............................................................................................. 47416.13.1 Bean Provider’s Responsibility......................................................... 47516.13.2 Container Provider’s Responsibility ................................................. 475

16.14 TimerService References................................................................................. 47516.14.1 Bean Provider’s Responsibility......................................................... 47616.14.2 Container Provider’s Responsibility ................................................. 476

16.15 EJBContext References ................................................................................... 47616.15.1 Bean Provider’s Responsibility......................................................... 47616.15.2 Container Provider’s Responsibility ................................................. 476

16.16 Deprecated EJBContext.getEnvironment Method .......................................... 477

Chapter 17 Security Management .................................................................................................... 47917.1 Overview ......................................................................................................... 47917.2 Bean Provider’s Responsibilities..................................................................... 481

17.2.1 Invocation of Other Enterprise Beans............................................... 48117.2.2 Resource Access ............................................................................... 48117.2.3 Access of Underlying OS Resources ................................................ 48217.2.4 Programming Style Recommendations............................................. 48217.2.5 Programmatic Access to Caller’s Security Context .......................... 482

17.2.5.1 Use of getCallerPrincipal.................................................... 48317.2.5.2 Use of isCallerInRole ......................................................... 48517.2.5.3 Declaration of Security Roles Referenced from the Bean’s Code

48517.3 Responsibilities of the Bean Provider and/or Application Assembler ............ 487

19 2/24/09



17.3.1 Security Roles ................................................................................... 48817.3.2 Method Permissions .......................................................................... 490

17.3.2.1 Specification of Method Permissions with Metadata Annotations490

17.3.2.2 Specification of Method Permissions in the Deployment Descriptor491

17.3.2.3 Unspecified Method Permissions ....................................... 49517.3.3 Linking Security Role References to Security Roles ........................ 49517.3.4 Specification of Security Identities in the Deployment Descriptor... 496

17.3.4.1 Run-as ................................................................................. 49617.4 Deployer’s Responsibilities ............................................................................. 497

17.4.1 Security Domain and Principal Realm Assignment.......................... 49717.4.2 Assignment of Security Roles ........................................................... 49817.4.3 Principal Delegation.......................................................................... 49817.4.4 Security Management of Resource Access ....................................... 49817.4.5 General Notes on Deployment Descriptor Processing...................... 499

17.5 EJB Client Responsibilities ............................................................................. 49917.6 EJB Container Provider’s Responsibilities...................................................... 499

17.6.1 Deployment Tools ............................................................................. 49917.6.2 Security Domain(s) ........................................................................... 50017.6.3 Security Mechanisms ........................................................................ 50017.6.4 Passing Principals on EJB Calls........................................................ 50017.6.5 Security Methods in javax.ejb.EJBContext....................................... 50117.6.6 Secure Access to Resource Managers............................................... 50117.6.7 Principal Mapping ............................................................................. 50117.6.8 System Principal................................................................................ 50117.6.9 Runtime Security Enforcement ......................................................... 502

17.6.10 Audit Trail ......................................................................................... 50317.7 System Administrator’s Responsibilities......................................................... 503

17.7.1 Security Domain Administration ...................................................... 50317.7.2 Principal Mapping ............................................................................. 50317.7.3 Audit Trail Review............................................................................ 503

Chapter 18 Timer Service ................................................................................................................. 50518.1 Overview ......................................................................................................... 50518.2 Bean Provider’s View of the Timer Service .................................................... 506

18.2.1 Calendar-Based Time Expressions.................................................... 50718.2.1.1 Attribute Syntax.................................................................. 50818.2.1.2 Expression Rules................................................................. 51018.2.1.3 Examples............................................................................. 510

18.2.2 Automatic Timer Creation................................................................. 51118.2.3 Non-persistent Timers ....................................................................... 51218.2.4 The Timer Service Interface.............................................................. 514

18.2.4.1 Example .............................................................................. 51518.2.5 Timeout Callbacks............................................................................. 515

18.2.5.1 Timeout Callbacks for Programmatic Timers..................... 51618.2.5.2 Timeout Callbacks for Automatically Created Timers ....... 51618.2.5.3 Timeout Callback Method Requirements ........................... 516

2/24/09 20



18.2.6 The Timer and TimerHandle Interfaces ............................................ 51718.2.7 Timer Identity.................................................................................... 51818.2.8 Transactions ...................................................................................... 518

18.3 Bean Provider’s Responsibilities..................................................................... 51918.3.1 Enterprise Bean Class ....................................................................... 51918.3.2 TimerHandle ..................................................................................... 519

18.4 Container’s Responsibilities ............................................................................ 51918.4.1 TimerService, Timer, and TimerHandle Interfaces........................... 51918.4.2 Automatic Timers.............................................................................. 51918.4.3 Timer Expiration and Timeout Callback Method ............................. 52018.4.4 Timer Cancellation............................................................................ 52018.4.5 Entity Bean Removal ........................................................................ 521

Chapter 19 Deployment Descriptor.................................................................................................. 52319.1 Overview ......................................................................................................... 52319.2 Bean Provider’s Responsibilities..................................................................... 52419.3 Application Assembler’s Responsibility ......................................................... 52719.4 Container Provider’s Responsibilities ............................................................. 53019.5 Deployment Descriptor XML Schema............................................................ 530

Chapter 20 Packaging....................................................................................................................... 58120.1 Overview ......................................................................................................... 58120.2 Deployment Descriptor ................................................................................... 58220.3 Packaging Requirements ................................................................................. 58220.4 Enterprise Beans Packaged in a .war............................................................... 583

20.4.1 Class Loading.................................................................................... 58320.4.2 Component Environment .................................................................. 58320.4.3 Visibility of the Local Client View ................................................... 58420.4.4 Ejb-names.......................................................................................... 58420.4.5 EJB 2.1/1.1 Entity Bean Restriction ................................................. 58420.4.6 Example ............................................................................................ 584

20.5 Deployment Descriptor and Annotation Processing ....................................... 58520.5.1 Ejb-jar Deployment Descriptor and Annotation Processing............. 58520.5.2 .war Deployment Descriptor and Annotation Processing................. 585

20.6 The Client View and the ejb-client JAR File................................................... 58620.7 Requirements for Clients................................................................................. 58720.8 Example........................................................................................................... 587

Chapter 21 Runtime Environment.................................................................................................... 58921.1 EJB 3.1 Lite ..................................................................................................... 59021.2 Bean Provider’s Responsibilities..................................................................... 591

21.2.1 APIs Provided by Container ............................................................. 59221.2.2 Programming Restrictions................................................................. 592

21.3 Container Provider’s Responsibility................................................................ 594

21 2/24/09



21.3.1 EJB 3.1 Requirements ....................................................................... 59521.3.2 JNDI Requirements ........................................................................... 59521.3.3 JTA 1.1 Requirements ....................................................................... 59621.3.4 JDBC™ 3.0 Extension Requirements ............................................... 59621.3.5 JMS 1.1 Requirements ...................................................................... 59721.3.6 Argument Passing Semantics ............................................................ 59721.3.7 Other Requirements........................................................................... 598

21.4 Compatibility and Migration ........................................................................... 59821.4.1 Support for Existing Applications..................................................... 59821.4.2 Default Stateful Session Bean Concurrency Behavior...................... 59821.4.3 Default Application Exception Subclassing Behavior ...................... 59821.4.4 Interoperability of EJB 3.1 and Earlier Components ........................ 598

21.4.4.1 Clients written to the EJB 2.x APIs .................................... 59821.4.4.2 Clients written to the EJB 3.x API...................................... 59921.4.4.3 Combined use of EJB 2.x and EJB 3.x persistence APIs ... 599

21.4.5 Adapting EJB 3.x Session Beans to Earlier Client Views................. 59921.4.5.1 Stateless Session Beans....................................................... 60021.4.5.2 Stateful Session Beans ........................................................ 600

Chapter 22 Embeddable Usage......................................................................................................... 60122.1 Overview ......................................................................................................... 60122.2 Bootstrapping API ........................................................................................... 602

22.2.1 EJBContainer .................................................................................... 60222.2.2 Standard Initialization Properties ...................................................... 603

22.2.2.1 javax.ejb.embeddable.initial ............................................... 60322.2.2.2 javax.ejb.embeddable.modules ........................................... 60322.2.2.3 javax.ejb.embeddable.appName ......................................... 604

22.2.3 Looking Up Session Bean References .............................................. 60422.2.4 Embeddable Container Shutdown..................................................... 604

22.3 Container Provider’s Responsibilities ............................................................. 60522.3.1 Runtime Environment ....................................................................... 60522.3.2 Naming Lookups ............................................................................... 60522.3.3 Embeddable Container Bootstrapping .............................................. 60522.3.4 Concrete javax.ejb.EJBContainer Implementation Class ................. 606

Chapter 23 Responsibilities of EJB Roles ........................................................................................ 60723.1 Bean Provider’s Responsibilities ..................................................................... 607

23.1.1 API Requirements ............................................................................. 60723.1.2 Packaging Requirements ................................................................... 607

23.2 Application Assembler’s Responsibilities ....................................................... 60823.3 EJB Container Provider’s Responsibilities..............................