Sun Microsystem Inc
Changes since EJB 1.1 Public Draft 2 |
Enterprise JavaBeans v1.1, Final Release |
Revision History |
Specified that application exceptions must not be defined as a subclass of |
RuntimeException or |
RemoteException. |
|
Clarified that the container-managed persistence fields must not be defined as |
transient. |
Clarified in Subsection 9.2.3 that the entity object created by the ejbCreate(...) method must have a unique primary key.
Clarified in Section 6.8 how the Container delegates requests to instances of a stateless Session bean.
Added to Section 18.1.2 the restriction that an enterprise bean must not pass this as a method argument or result.
In Section 6.4.1 specified that the Container must be able to preserve to an object reference of the UserTransaction interface across passivation. Same for the object references of enterprise beans’ home interfaces.
Noted in Chapter 11 that the transaction attributes may be specified either by the Bean Provider or the Application Assembler. The previous text suggested that only the Application Assembler was allowed to specify the transaction attributes.
Made the terminology more consistent throughout the specification. Used the terms session bean, session object, session bean instance, home interface, remote interface, session EJBObject, and session EJBHome consistently. Used similar terminology for the entity bean related terms. Note that we turned off the change bars while making this editorial clean up.
Disallowed the use of the setRollbackOnly and getRollbackOnly method, the use of the UserTransaction interface, resource manager access, and enterprise bean access in the ejbCreate and ejbRemove methods of the stateless session bean (see Table 3 on page 70). The Container does not have a transaction context and client security context during the execution of these two operations of a stateless session bean.
Added support for referencing the deployment descriptor elements through XML IDs. The main reason for this is to make it easier for tools that want to pass additional non-standard deployment information for the enterprise beans. The tools should put the non-standard information into a separate file, and optionally make use the ID mechanism to reference the information in the standard EJB deployment descriptor. Tools are not allowed to extend the format of the EJB deployment descriptor.
Made a minor change to the language in Subsection 15.3.2 for the case that a method is not assigned to any security role.
Added a paragraph stating that the Container should implement the object references of the home and remote interfaces of Entity objects such that a client can use the references over a long period of time (Subsection 9.3.9).
C.9 Changes since EJB 1.1 Public Draft 2
We changed the JTA requirements to refer to version JTA 1.0.1.
301 |
11/24/99 |
Sun Microsystems Inc.
Revision History |
Enterprise JavaBeans v1.1, Final Release |
Changes since EJB 1.1 Public Draft 3 |
Added clarifications to subsections 9.1.5.1, 9.1.5.2, and 9.4.3 stating that the container must ensure that the instance’s state is synchronized before it invokes ejbRemove.
Renamed the primkey-class element to prim-key-class to be consistent with the rest of the element names.
Clarified in Subsection 12.1.1 that a Bean Provider is allowed to define subclasses of the standard EJB application exceptions.
Added the requirement (in Subsection 9.4.2) for the Container to reset the container-manager fields to the default Java language values prior to invoking ejbCreate.
Clarified the reason for allowing the primary key type for CMP entities to be specified at deployment time (Subsection 9.4.7.3).
C.10 Changes since EJB 1.1 Public Draft 3
Made clear in Section 11.2.3 that not all EJB client environments are required to support the UserTransaction interface.
Specified the name and URI to be used in the DOCTYPE PUBLIC ID in the EJB XML deployment descriptors.
Corrected Section 5.3.2 to state that a javax.ejb.RemoveException be thrown instead of java.rmi.RemoteException.
Fixed a few errors in Tables 2, 3, and 4.
Changed the format of the Style 3 method element of the EJB deployment descriptor. See Section 16.5. This change was necessary to disambiguate a Style 3 element for a method with no arguments from a Style 2 element.
C.11 Changes since EJB 1.1 Public Release
Fixed an error in Subsection 15.2.5. The getCallerPrincipal and isCallerInRole functions, when called in an inappropriate context, must throw the java.lang.IllegalStateException, not the javax.ejb.EJBException.
Fixed the omission of a requirement in Subsection 9.4.1. The container-managed fields must be declared as public fields in the enterprise bean class. This requirement was present in the EJB 1.0 specification, and it was inadvertently left out when the sections on container-managed persistence were reorganized during the EJB 1.1 specification process.
11/24/99 |
302 |
Sun Microsystem Inc
Changes since EJB 1.1 Public Release |
Enterprise JavaBeans v1.1, Final Release |
Revision History |
Made it clear in 6.4.1 that an instance is allowed to retain across passivation references to enterprise beans’ remote and home interfaces, references to the SessionContext object, references to the java:comp/env JNDI API context and its subcontexts, and references to the UserTransaction anywhere in the instances conversational state (i.e. not only directly in the fields of the session bean class). For example, it is possible to retain a Collection of remote interfaces in the conversational state.
Changed the version numbers in the DOCTYPE specification in the deployment descriptor from 1.2 to 1.1. The correct DOCTYPE specification is:
<!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd">
Clarified in Sections 5.5 and 8.7 that handles are not capabilities in the security sense.
Replaced the term resource factory reference with the term resource manager connection factory reference. This change makes the terminology consistent with other J2EE specs.
Added a missing entry to Table 11 for checkLink.
Clarified in 16.5 that the DTD XML elements’ content is case sensitive.
Fixed a few typos in the text.
C.12 Changes since EJB 1.1 Public Release
Clarified in 17.3 that the enterprise bean’s dependent files could be in other jar files if the jar files are specified in the ejb-jar file’s Class-Path.
Clarified in 16.5 that the method-intf can be used with all Style elements, specifically with method-name being *.
Clarified in 9.1.9.4 that multi-object finders should return an empty collection if no object is found.
Allowed enterprise beans to read system properties.
303 |
11/24/99 |
Sun Microsystems Inc.
Revision History |
Enterprise JavaBeans v1.1, Final Release |
Changes since EJB 1.1 Public Release |
11/24/99 |
304 |
Index
A
activation, 50, 65 All, 46
APIs
runtime, 272, 275 Application Assembler, 22
responsibilities, 282 transaction attributes, 171 transaction role, 169
application assembly, 243–244 application exception, 187 application exception See exception
B
Bean Provider, 22 responsibilities, 281 responsibility, 74–77
BeanReference
Interface in package java.beans.enterprise, 285
Interface in package java.ejb, 285
C
cmp-fields element, 242 commit, 118
Container
Interface in package java.ejb, 285 Container Provider, 23
transaction demarcation bean managed, 173
container managed, 175–178 container-transaction element, 171
conversational state, 51 passivation, 51 rollback, 53
CORBA mapping, 35 CreateException, 116 CurrentTransaction
Interface in package java.jts, 293
D
Deployer, 22 responsibilities, 282
deployment descriptor application assembly, 240 bean structure, 240, 240–242 DTD, 244–259
EJB reference, 208 ejb-link element, 210 ejb-ref element, 208
enterprise-beans element, 240 env-entry element, 204 environment entry, 204 res-auth element, 213 resource-ref element, 213 role, 240
transaction attributes, 171 XML DTD, 244–259
distributed objects, 199 DuplicateKeyException, 116
E
EJB Container Provider, 23 requirements, 78–79
305
306
responsibilities, 282 EJB reference, 207
Deployer role, 211 ejb-link element, 210
in deployment descriptor, 208 locate home interface, 208
EJB Role
Application Assembler, 22 Bean Provider, 22 Container Provider, 23 Deployer, 22
EJB Server Provider, 23
System Administrator, 24 EJB Server Provider, 23 ejb-class element, 241 ejb-client JAR file, 268 EJBContext
Interface in package javax.ejb, 284, 285 EJBHome, 41, 128
Interface in package javax.ejb, 285 remove method, 42
ejb-jar file, 33, 242, 267 class files, 268
deployment descriptor, 268 ejb-client JAR file, 268 JAR Manifest, 269
ejb-link element, 210 EJBMetaData, 129 ejb-name element, 240 EJBObject, 39, 43, 128
remove method, 42 ejb-ref element, 208 ejbRemove, 61
enterprise bean component characteristics of, 30
enterprise bean component model, 30 enterprise bean contract
client view, 31
CORBA mapping, 35 home interface, 31 metadata interface, 32 object identity, 32 remote interface, 32
component contract requirements, 32
ejb-jar file, 33
INDEX
enterprise bean environment JNDI interface, 202
InitialContext, 203 Enterprise Bean Provider, 22 entity bean
allowed method operations, 111 bean provider-implemented methods,
104–107 business methods, 125 class requirements, 121 client view of, 85–86 commit, 118 constructor, 104
create method, 89, 122 CreateException, 116 DuplicateKeyException, 116 EJB container, 86 ejbActivate, 105
ejbCreate, 105, 122 ejbFind methods, 124 ejbLoad, 106, 112 ejbPassivate, 106 ejbPostCreate, 105, 124 ejbRemove, 106 ejbStore, 106, 112 exceptions, 116–117
find methods, 90, 107, 124 return type, 114–115
findByPrimaryKey, 90 FinderException, 117 generated classes, 127 getHandle method, 94 getPrimaryKey method, 93 handle, 94, 128
home interface function of, 89 requirements, 126
home interface handle, 95, 128 isIdentical method, 93
life cycle, 91–92, 102–104 locate home interface, 87 methods
container view of, 107–109 modeling business objects, 99 ObjectNotFoundException, 117 persistence, 99, 100, 101
INDEX
container managed, 129–134 primary key, 93, 127 reentrancy, 120
remote interface, 93, 125 remove method, 90 RemoveException, 117 setEntityContext, 104 state, 102
state caching, 112 transaction demarcation, 160
container managed, 167 transaction synchronization, 119 unsetEntityContext, 105
entity element, 241 env-entry element, 204 environment entry, 204
Application Assembler role, 207 Deployer role, 207
environment naming context, 203 exception
application, 187
client handling of, 195 data integrity, 188 defined, 188
subclass of, 189 client view, 195
container handling of, 191 container-invoked callbacks, 193
containter-managed transaction, 194 NoSuchObjectException, 197 RemoteException, 194, 196
client handling, 196 system
handling of, 189–190 System Administrator, 197 transaction commit, 194 transaction start, 194
TransactionRequiredException, 197 TransactionRolledbackException, 197
F
findByPrimaryKey, 90 FinderException, 117
G
getCallerIdentity, 222
307
getCallerPrincipal, 223, 236 getEnvironment method, 216 getHandle method, 94 getPrimaryKey method, 47, 93
H
home element, 241
home interface, 31, 40, 67 client functionality, 89 create method, 89
EJB reference to, 207 entity bean, 126
find methods, 90 findByPrimaryKey, 90 handle, 95
locating, 87 remove method, 90
I
Interfaces java.beans.enterprise.BeanReference, 285 java.ejb.BeanReference, 285 java.ejb.Container, 285 java.jts.CurrentTransaction, 293 javax.ejb.EJBContext, 284, 285 javax.ejb.EJBHome, 285 javax.ejb.SessionSynchronization, 168 javax.jts.UserTransaction, 293
isCallerInRole, 222 isCallerinRole, 224 isIdentical method, 46, 93 isolation level
managing in transaction, 160
J
JAR Manifest file, 269
Java RMI, 279
JDBC, 277
JDK 1.1, 277–279
JNDI, 276
JNDI interface, 202
InitialContext, 203
JTA, 277
M
Mandatory, 170, 177
308
metadata interface, 32 method-permission element, 229
N
narrow method, 47 Never, 170, 177
NoSuchObjectException, 197 NotSupported, 170, 175
O
object identity, 32 ObjectNotFoundException, 117
P
passivation, 50, 65 conversational state, 51 SessionContext interface, 52 UserTransaction interface, 52
persistence, 99
bean managed, 100
entity state caching, 112 container managed, 101, 129–134
persistence-type element, 241 portability
programming restrictions, 272–274 primary key, 93, 127
prim-key-class element, 241 principal, 220, 221
delegation, 233
R
remote element, 241 remote interface, 32, 39, 43
entity bean, 93, 125 RemoteException, 194, 196 client handling, 196
RemoveException, 117 Required, 170, 175 RequiresNew, 170, 176 res-auth element, 213 resource
obtaining connection to, 212 res-auth element, 213
resource factory, 211
resource factory reference, 211 resource-ref element, 213
INDEX
resource-ref element, 213 RMI, 199
role-link element, 232 role-name element, 227 runtime
APIs, 272, 275
S security
audit, 238 bean provider
programming recommendations, 221 client responsibility, 234
current caller, 223
deployment descriptor processing, 234 deployment tools, 235
EJBContext, 222, 236 getCallerPrincipal, 222, 223, 236 isCallerInRole, 222, 224 mechanism, 235
principal, 220, 221 delegation, 233 passing, 236
principal realm, 233, 235 role-link element, 232 runtime enforcement, 237 security-role-ref element, 225
security domain, 233, 235 security role, 220, 226, 227
assigning, 233 linking, 232
method permission, 220, 226, 229 role-name element, 227
security view, 226 security-role element, 227, 233 security-role-ref element, 225 session bean
access to, 39
business method requirements, 76 class requirements, 75
client operations on, 44 client view of, 39 create, 42
ejbCreate requirements, 76 ejbRemove call, 61 exceptions, 61
INDEX
getPrimaryKey method, 47 home interface, 40, 41
home interface requirements, 77 identity, 43
provider responsibility, 74–77 remote interface, 39, 43
remote interface requirements, 77 remove, 42, 66
requirements, 74–77 SessionBean interface, 53 SessionContext interface, 54
SessionSynchronization interface, 54 stateful
conversational state, 51 identity of, 46 isIdentical method, 46 lifecycle, 57 operations in, 59
stateless, 67–74 exceptions, 71 home interface, 67 identity of, 46
isIdentical method, 46 lifecycle, 68 operations, 70
transaction demarcation, 161 use of, 67
transaction context, 56 transaction demarcation, 160, 161
bean managed, 161 container managed, 167
transaction scope, 62 session bean instance
activation, 50, 65 characteristics, 49 creating, 55
diagram of, 63 passivation, 50, 65 serialization of calls, 56
session element, 241 SessionBean interface, 53 SessionContext interface, 54
passivation, 52 SessionSynchronization interface, 54, 168
callbacks, 179 session-type element, 241
309
stateful session bean conversational state, 51 lifecycle, 57 operations in, 59
stateless session bean. See session bean Supports, 170, 176
System Administrator, 24 responsibilities, 282
T transaction
attributes, 154 definition, 169
deployment descriptor, 171 Mandatory, 177
Never, 177 NotSupported, 175 Required, 175 RequiresNew, 176 Supports, 176 values, 170
bean managed, 154, 159–169 container responsibilities, 173
committing, 64
container managed, 154, 159–169 container responsibilities, 175–178 getRollbackOnly method, 169, 178 getUserTransaction method, 179 SessionSynchronization callbacks,
179
setRollbackOnly method, 168, 178 isolation level, 160
JTA, 155
JTS, 155
multiple client access, 180–185 nested, 154
SessionSynchronization interface, 168 starting, 63
synchronizing, 119
unspecified transaction context, 179 UserTransaction interface, 154
transaction context session bean, 56
transaction scope session bean, 62
TransactionRequiredException, 197
310 |
INDEX |
TransactionRolledbackException, 197 transaction-type element, 241 trans-attribute element, 171
type narrowing, 47, 96
U
UserTransaction
Interface in package javax.jts, 293 UserTransaction interface, 154, 161, 217
passivation, 52