-
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft Release Sun
Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft Release Sun
Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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
-
Enterprise JavaBeans 3.1, Proposed Final Draft
Sun Microsystems, Inc.
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..............................