By Eileen Sauer.

Email: [email protected] EJB Specification v1.1 Matrix Hosted on:

TheServerSide.com
For any corrections / updates / additions. Your J2EE Community

Component Contract Matrix

The following matrix shows you:
!"Interfaces
!"callbacks for those interfaces
!"when they occur, under what conditions
!"related page numbers in the EJB 1.1 spec.

Callback Entity Beans Session Beans

CMP When BMP When Stateful When Stateless When
javax.ejb.EJBHome interface extends java.rmi.Remote
getEJBMetaData() Get EJBMetaData interface get EJBMetaData interface
getHomeHandle() Get handle5 for home object Get handle5 for home object
remove(Handle) Remove EJB object identified by handle Remove EJB object identified by handle
remove(PK) Remove EJB object identified by PK N/A – throws RemoteException
Home interface extends javax.ejb.EJBHome
general Create/find/remote entity object p89 Allowed to have super interfaces p77
create() Zero or more create() methods p89 4 Must have at least one ejbCreate() p75 Must have only one ejbCreate()/no args
Calls newInstance(), setEntityContext(), ejbCreate(), ejbPostCreate() Calls newInstance(), setSessionCtx(), Calls newInstance(), setSessionCtx()
Arguments typically used to initialize state, must return remote interface ejbCreate() ejbCreate()
Entity bean instance life cycle, p102 Must return remote interface (p77), Must return remote interface (p77),
unlike ejbCreate() unlike ejbCreate()
findByPrimary One method One method N/A
Key() Can find object, return remote interface Do SELECT, check if exists
Can find object, return remote interface
findXXX() May have one or more May have one or more N/A
Single/multiple finders p114 Single/multiple finders p114
Return remote interface or Collection Return remote interface or Collection
remove() N/A ejbRemove() - error if client invokes while in transaction
javax.ejb.EJBObject extends java.rmi.Remote
getEJBHome() Get home interface Implementation provided by container p43
Implementation generated by container provider tools at deployment time p98
getHandle() Get handle5 for entity object Implementation provided by container p43
getPrimaryKey() Valid - get identity of entity object N/A N/A - throws RemoteException
isIdentical() Use this or equals(), == not guaranteed (because hashCode() not guaranteed) p93 Valid True if same SB, same home interface
If same home and same PK, considered identical p92
remove() Valid?? p94
Remote interface extends javax.ejb.EJBObject
_______________________________________________________________________________________________________________________________________________________
Last updated 08/03/00 10:09 PM by Eileen Sauer Page 1 of 7
general Client can: invoke business methods, obtain reference to home interface, pass Allowed to have super interfaces p77
reference as parameter/return value, obtain primary key, obtain handle, remove
entity object p92
javax.ejb.EnterpriseBean extends java.io.Serializable
serialVersionUID Inherited from Serializable
javax.ejb.EntityBean extends javax.ejb.EnterpriseBean
general Container provides security, concurrency, transactions, persistence etc p86 N/A
Multiple clients can access concurrently
All EBs are persistent; lifetime not limited to lifetime of VM process p92
Represent independent business objects that have independent entities/lifecycle
fields Must not code explicit data access
Defer to container
Use cmp-field elements of DD to ID
fields container must load/store p130
methods Method calls via home/remote interface may be remote. Call must go through N/A
container/parameters passed by value are copied. Make coarse-grained p99
javax.ejb.SessionBean extends javax.ejb.EnterpriseBean
general N/A Unique ID assigned by container Anonymous to client, hide identity
N/A Instance has no state for a specific
client p67
methods N/A Delegated to bean instance
If instance is passivated, it's reactivated
args/return types N/A Must be valid types for RMI/IIOP
instance fields N/A Can be: non-transient, serializable object, null, remote/home interface ref, etc p51
Bean implementation implements EntityBean or SessionBean
general Pooled state - not associated with identity. Done via ejbPassivate or ejbRemove() Must implement business methods and ejbCreate()
Ready state - assigned identity, via ejbCreate, ejbPostCreate or ejbActivate() p103 Class must be public, not abstract, not final, must have public default constructor,
Class must be public, not abstract, not final, must have public default constructor, no finalize(), may implement remote interface p75
no finalize() p121
newInstance Called by container Unspecified transaction context
setSessionContext N/A Unspecified transaction context
May be passivated
setEntityContext Allows instance to invoke container services/get info about invoker p103 N/A
Use to allocate resources held by instance for lifetime
Executes within unspecified transaction context, ID of EB not available here
unsetEntityContext Remove instance in pool, frees resources allocated by setEntityContext() N/A
Unspecified transaction context
ejbCreate() Match create() home.create() Match create() home.create() Match create() p76
Container does After Do INSERT After Unspecified transaction context
INSERT setEntityContext() Returns PK setEntityContext() Returns void (unlike create()) p77
Returns PK Validate client
Validate client args, has txn ctx
args, has txn ctx
_______________________________________________________________________________________________________________________________________________________
Last updated 08/03/00 10:09 PM by Eileen Sauer Page 2 of 7
ejbPostCreate() Match create() After setContext() Match create() After setContext() N/A
Returns void and ejbCreate() Returns void and ejbCreate()
Entity object ID is Entity object ID is
available available
ejbLoad() Container syncs Depends… p108 Do SELECT N/A
instance with DB After ejbActivate,
before ejbLoad() before method call
Txn ctx of bus. Unreliable when
method p106 NotSupported 113
ejbStore() Container syncs Before passivate, Do UPDATE to N/A
DB with instance after last business sync DB with
Same txn ctx as method instance
previous ejbLoad Unreliable when
or ejbCreate NotSupported 113

ejbActivate() EB can acquire Transition from EB can acquire Transition from Optionally obtain When client Never called because container creates
additional pooled to ready additional pooled to ready state invokes
resources needed state resources needed state Not allowed
in ready state in ready state during a txn 1
Unspec'd txn ctx Unspecified txn
Container assigns context
ID
ejbPassivate() Container Within a txn p103 Removes bean ID Within a txn p103 Optionally store !"
Not in txn Never called because container
removes bean ID After ejbStore() Unspecified txn After ejbStore() state !"
Timed out or destroys
Container doesn’t Transition from ctx Transition from Release resources !"
LRU
serialize instance 1 ready to pooled ready to pooled (e.g. JDBC !"
App server runs
Unspec'd txn ctx connections) out of free beans1
May serialize
instance1
Unspecified txn
context
ejbRemove() Container Remote interface Do DELETE Clean up state Upon: Not upon:
removes bean ID 1 remove() or EB Release resources !"Bean timeout !"Container crash
Remove entity home.remove() Unspecified txn !"Server failure !"System exceptn
object because Transition from context Not upon: !"Client timeout
pooled to ready
client called !"Container crash while bean
remove() !"System exceptn passivated
Transaction ctx of !"Client timeout May need clean
remove() method while bean up: section 6.6.3
p106 passivated
May need clean
up: section 6.6.3

_______________________________________________________________________________________________________________________________________________________
Last updated 08/03/00 10:09 PM by Eileen Sauer Page 3 of 7
ejbFindByPrimaryK One or more home.findByPrim One or more methods N/A - anonymous to client
ey() Match findByPK aryKey() Match findByPK
Return remote int Do SELECT, if exists, return PK
or Collection Return remote interface or Collection
Txn ctx of find Txn ctx of find method
method
ejbFindXXX() Match findXXX() Match findXXX() N/A
Return remote interface or Collection Do SELECT, if exists, return PK
Txn ctx of find method p133 Return remote interface or Collection
Txn ctx of find method
SessionSynchronization interface
Container-managed transactions
afterBegin() N/A After new txn begun, same txn context N/A - must not implement this
as beforeComp() and business methods interface
beforeCompletion() N/A Before commit; if setRollbackOnly true, not N/A - must not implement this
run else you can cache updated data. Same interface
txn context as afterBegin() and bus methods
afterCompletion() N/A After commit/rollback; clean up state if N/A - must not implement this
rollback causes inconsistency. Status of txn: interface
committed (true) or rolled back (false)
EJBMetaData interface
Allow dynamic invocation of beans
getPrimaryKeyClass N/A - anonymous to client
javax.ejb.Handle interface
general Lifetime/scope implementation specific. At minimum: can store/retrieve across
JVMs p95. Not required to store/retrieve across containers.
serialVersionUID Inherited from java.io.Serializable
getEJBObject() SB exists, get a reference
HomeHandle interface extends java.io.Serializable
general Handle for the home interface
serialVersionUID Inherited from java.io.Serializable N/A
getEJBHome()3 N/A
getHandle() N/A
PK class
general Can be any class that is legal value type in RMI-IIOP, some restrictions 9.2.9 N/A
May be specific to an EB, but multiple EBs can use the same PK p93
implementation primkey-field of DD p134 Must be specified N/A
Can be unspecified p134
equals() Recommended: implement this N/A
hashCode() Recommended: implement this N/A
javax.rmi.PortableRemoteObject
narrow() Must use to convert result of getEJBObject() method invoked on handle to EB's Use for interoperability with EJB containers.
remote or home interface type p94, 96 Cast likely to fail if container implementation uses RMI/IIOP p47
_______________________________________________________________________________________________________________________________________________________
Last updated 08/03/00 10:09 PM by Eileen Sauer Page 4 of 7
Transaction Matrix
Callback Entity Beans Session Beans
Container-managed transactions Container-managed transactions Bean-managed transactions
General
No nested transactions. Container not required to support JTS, only required to support JTA UserTransaction p155. Application exceptions don't automatically cause
rollback p168. Don’t retain state between transactions1 Can provide caching and updates to multiple data sources. Isolation levels p160
EJBContext interface
getCallerPrincipal May be different in each business method (if moved from pooled to ready) p104 Return java.security.Principal - identity of invoker
Container must have client security context Container must have client security context
getEJBHome Return home interface
setRollbackOnly Should only be used if EB methods have transaction context p112 Instance can mark current transaction N/A
for rollback. Container must have
meaningful transaction context p71
getRollbackOnly Should only be used if EB methods have transaction context p112 Instance can check if current N/A
transaction is marked for rollback
Container must have meaningful
transaction context p71
getUserTransaction N/A Return UT interface so bean can:
!"Demarcate transactions
!"Obtain transaction status
isCallerInRole(strin May be different in each business method (if moved from pooled to ready) p104 Does caller have a particular role?
g roleName) Container must have client security context Container must have client security context
EntityContext interface extends EJBContext
getEJBObject Instance can obtain identity of entity object Return remote interface
Identity remains associated until passivated/removed p105
Disallowed in EB methods where there is no ID p112
getPrimaryKey Obtain primary key of entity object N/A
Might be different each time instance is moved from pooled to ready p104
SessionContext interface extends EJBContext
getEJBObject Return remote interface
Transaction Attributes
Client has transaction context Client has NO transaction context
NotSupported Container suspends txn Runs ← Same
May have unspecified txn context May have unspecified txn context
ejbStore(), ejbLoad() unreliable ejbStore(), ejbLoad() unreliable
Required Runs Container creates txn ← Same
Supports set/getRollbackOnly() Supports set/getRollbackOnly()
Supports Runs (code should be txn-insensitive) Runs (code should be txn-insensitive) ← Same
May have unspecified txn context May have unspecified txn context

_______________________________________________________________________________________________________________________________________________________
Last updated 08/03/00 10:09 PM by Eileen Sauer Page 5 of 7
RequiresNew Start one Suspend txn and start new txn ← Same
Supports set/getRollbackOnly() Supports set/getRollbackOnly()
Mandatory Run Throw exception ← Same
Supports set/getRollbackOnly() Supports set/getRollbackOnly()
Never Throw exception Run ← Same
May have unspecified txn context May have unspecified txn context
javax.transaction.UserTransaction (JTA)
general Must not use sql.Connection interface: commit(), setAutoCommit(), rollback(). Must not use UserTransaction p161 Enables programmatic transaction
demarcation. Don't use sql.Connection
begin() N/A Must refresh copy of possibly stale data
commit() N/A Stateless SBs must commit before method
returns p161. Not guaranteed to get same
UserTxn across method calls
Stateful guaranteed to get same UserTxn
until txn terminates 2
getStatus() N/A Use in place of getRollbackOnly()
rollback() N/A Use in place of setRollbackOnly()

1
This information comes from a newsgroup/mailing list – caveat emptor!
2
Danger of long-running transactions if your transaction spans method calls. Not normally done.
3
Source: EJB API.
4
This is because with legacy data, entity objects may exist before the container and entity beans deploy. Also, entity objects may be created by inserting rows into the database, not by
create(). The rows are still accessible via finder methods. p92
5
A handle is an object that identifies an object on network

To join EJB-INTEREST, send email to [email protected] and put in the body of the message: subscribe EJB-INTEREST.

There are quirks with:

!"keywords transient, abstract, final, static and finalize() method
!"re-entrancy (no loopbacks) p120
!"distributed diamonds (local diamonds are supported by the container)
At best – use caution. At worst – disallowed (maybe it’s the other way around)

Questions:
!"
FS: What if, in a method, you spawn off 10 threads and join them back up before the end of the method? Legal? p79
!"
How to handle EJBContext?? EJB-INTEREST Transaction context vs session context (application context). Recommendation: use stateful to maintain your application state, short burst
transactions to your underlying persistence. Question about serialization/storing of EJBContext. Same as SessionContext? EntityContext?? Only during stateful beans, activation and
passivation don't apply to stateless.
!"
Stateless session beans good for maintaining open connection to COBOL, legacy system: life of bean instance, not limited to client life cycle, activate/passivate don't affect
!"
Handling large transactions: start, pause, suspend, abort. JMS, can’t multithread. EJB no “oneway” semantics. Need event model?
!"
Spec doesn’t address optimistic concurrency control. Will be part of spec 2.0
!"
Remote debugging API??

_______________________________________________________________________________________________________________________________________________________
Last updated 08/03/00 10:09 PM by Eileen Sauer Page 6 of 7
Recommended Design

Workflow

Intelligent Apps
use case 1 use case 2
Session Bean Session Bean You write – coarse-
grained use cases

You write for maximum flexibility:

Entity Bean Entity Bean Entity Bean !"determine how coarsely grained
!"handle impedance mismatch (e.g.
return 3 rows for one EB)

Domain Model: Cocobase-generated

Java objects Hard part: Optimal componentization of
your Java objects. In general: domain
object + all of its dependent objects)
Exception: isolate intensive processing.
Lazy instantiate to avoid cascade loads

ORM (Cocobase, Toplink)

Oracle/Sybase/DB2
Gemstone, eXcelon

_______________________________________________________________________________________________________________________________________________________
Last updated 08/03/00 10:09 PM by Eileen Sauer Page 7 of 7