Reminder By Marco Tedone

scbcd for ejb 2.0 document edited by marco tedone jemos group (www.jemos.co.uk) for comments and suggestions please email: [email protected] -------------------------------------------------

/****************************************************************** * i n t e r f a c e s * ******************************************************************/ 1) ejbhome interface a) b) c) d)

ejbmetadata getejbmetadata(); homehandle gethomehandle(); void remove(handle h); void remove(object key);

2) ejblocalhome interface a) void remove(object key); 3) ejbobject interface a) b) c) d) e)

object getprimarykey(); ejbhome getejbhome(); handle gethandle(); void remove(); boolean isidentical();

4) ejblocalobject interface a) b) c) d)

object getprimarykey(); ejblocalhome getejblocalhome(); void remove(); boolean isidentical();

5) sessioncontext interface a) b) c) d) e) f) g) h) i)

ejbhome getejbhome(); ejblocalhome getejblocalhome(); ejbobject getejbobject(); ejblocalobject getejblocalobject(); boolean getrollbackonly(); void setrollbackonly(boolean b); usertransaction getusertransaction(); boolean iscallerinrole(string s); principal getcallerprincipal();

--> from ejbcontext --> from ejbcontext --> --> --> --> -->

from from from from from

ejbcontext ejbcontext ejbcontext ejbcontext ejbcontext

6) entitycontext interface a) b) c) d) e) f)

ejbhome getejbhome(); ejblocalhome getejblocalhome(); ejbobject getejbobject(); ejblocalobject getejblocalobject(); boolean getrollbackonly(); void setrollbackonly(boolean b);

--> from ejbcontext --> from ejbcontext --> from ejbcontext --> from ejbcontext

g) boolean iscallerinrole(string s); h) principal getcallerprincipal(); i) object getprimarykey();

--> from ejbcontext --> from ejbcontext

7) messagedrivencontext interface a) ejbhome getejbhome(); b) ejblocalhome getejblocalhome();

--> from ejbcontext (not used) --> from ejbcontext (not used)

e) f) g) h) i)

--> --> --> --> -->

boolean getrollbackonly(); void setrollbackonly(boolean b); usertransaction getusertransaction(); boolean iscallerinrole(string s); principal getcallerprincipal();

from from from from from

ejbcontext ejbcontext ejbcontext ejbcontext (not used) ejbcontext (not used)

8) sessionbean interface a) b) c) d)

void void void void

ejbactivate(); ejbpassivate(); ejbremove(); setsessioncontext(sessioncontext ctx);

9) entitybean interface a) b) c) d) e) f) g)

void void void void void void void

ejbactivate(); ejbpassivate(); ejbremove(); setentitycontext(entitycontext ctx); unsetentitycontext(); ejbload(); ejbstore();

10) messagedrivenbean interface a) void ejbremove(); b) void setmessagedrivecontext(messagedrivencontext ctx); 11) messagelistener interface a) onmessage(message m); 12) usertransaction interface a) b) c) d) e) f)

void begin() void commit() int getstatus() void rollback() setrollbackonly() settransactiontimeout()

13) sessionsynchronization interface a) void afterbegin() b) void beforecompletion() c) aftercompletion(boolean committed)

/****************************************************************** * b e a n t h i n g s i n l i f e c y c l e * ******************************************************************/ 9) bean things that can be done in the various lifecycle moments for: a) stateful session beans a1) setsessioncontext() 1) get a reference to the bean's home interface 2) access the special jndi environment a2) ejbcreate(), ejbremove(), ejbactivate(), ejbpassivate() 1) get a reference to the bean's home interface 2) get a reference to the bean's component interface 3) query the container about client's security info 4) get a usertransaction object onto which invoking methods (for bmt transactions only) 5) access the special jndi environment 6) access other bean's methods 7) access other resource managers a3) business method can do all bean things b) stateless session beans b1) setsessioncontext() 1) get a reference to the bean's home interface 2) access the special jndi environment b2) ejbcreate(), ejbremove() 1) get a reference to the bean's home interface 2) get a reference to the bean's component interface 3) access the special jndi environment b3) business method can do all bean things c) entity beans c1) setentitycontext() 1) get a reference to the bean's home interface 2) access the special jndi environment c2) ejbcreate() 1) get a reference to the bean's home interface

2) 3) 4) marked for 5) 6) 7)

query the container about client's security info set a cmt transaction for roll-back query the container to check if a cmt transaction has already been roll-back access the jndi special environment access other bean's methods access other resource managers

c3) ejbpostcreate(), ejbremove() 1) 2) 3) 4) 5) 6) marked for 7) 8) 9)

get a reference to the bean's home interface get a reference to the bean's component interface get the primary key query the container about client's security info set a cmt transaction for roll-back query the container to check if a cmt transaction has already been roll-back access the jndi special environment access other bean's methods access other resource managers

c4) home business method 1) 2) 3) 4) marked for 5) 6) 7)

get a reference to the bean's home interface query the container about client's security info set a cmt transaction for roll-back query the container to check if a cmt transaction has already been roll-back access the jndi special environment access other bean's methods access other resource managers

c5) ejbactivate(), ejbpassivate() 1) 2) 3) 4)

get a reference get a reference get the primary access the jndi

to the bean's home interface to the bean's component interface key special environment

c6) ejbload(), ejbstore() 1) 2) 3) 4) 5) 6) marked for 7) 8) 9)

get a reference to the bean's home interface get a reference to the bean's component interface get the primary key query the container about client's security info set a cmt transaction for roll-back query the container to check if a cmt transaction has already been roll-back access the jndi special environment access other bean's methods access other resource managers

d) from the sessionsynchronization callback methods: d1) from afterbegin() and beforecompletion() context

--> transaction safe

d1a) d1b) d1c) d1d)

get a reference to the home and component interfaces query the container about client's security info rollback a transaction query the container to check whether a transaction has been marked for rollback d1e) access the jndi special environment d1f) access other bean's method d1g) access other resource managers d2) from aftercompletion() anymore. not safe

--> not in a transaction

d2a) get a reference to the home and component interfaces d2b) query the container about client's security info d2c) access the jndi special environment /****************************************************************** * t r a n s a c t i o n a t t r i b u t e s * * * * d e m a r c a t i o n f o r c m t b e a n s * ******************************************************************/ s e s s i o n b e a n s : ---------------------------1) all the business methods defined in the bean's component interface e n t i t y b e a n s : ---------------------------1) all the business methods defined in the bean's component interface 2) all the remove() methods defined in the ejb[local]object and ejb[local]home interfaces 3) all the home business methods written by the bean's developer in the bean's home interface

/****************************************************************** * u n s p e c i f i e d t r a n s a c t i o n * * * * c o n t e x t f o r c m t b e a n s * ******************************************************************/ what does it mean, when a method runs in an unspecified transaction context? the container decides what to do, and we have simply to deal with it.

1) all methods which have been marked with one of the following transaction attributes:

a) notsupported b) never c) supports 2) for session beans: a) ejbcreate() b) ejbremove() c) ejbactivate() d) ejbpassivate() 3) for message-driven beans a) ejbcreate b) ejbremove

/****************************************************************** * e x c e p t i o n s * ******************************************************************/ 1) what happens when a bean (or the container) throws an application exception? 1a) the exception is passed back to the client as it is 2a) the transaction is not rolled-back. if things go bad, the bean can always invoke the setrollbackonly method (both in usertransaction and ejbcontext interfaces) 3a) the container spares the bean's life 2) what happens when a bean (or the container) throws a system exception? 1a) the container throws to the client an ejbexception (if the client is local) or a remoteexception (if the client is remote) 2a) the transaction is rolled-back 3a) the bean instance is killed by the container 4a) the exception is logged by the container examples of application exceptions: ----------------------------------a) createexception

b) c) d) e)

removeexception finderexception objectnotfoundexception duplicatekeyexception

examples of system exceptions: ----------------------------------a) remoteexception (even if it's checked it's considered the same as a runtimeexception) b) ejbexception c) illegalstateexception d) transactionrequiredexception e) runtimeexception f) nullpointerexception g) nosuchobjectexception

+---------------------------------------+ + + + e x c e p t i o n p a c k a g e s + + + + a n d m o s t c o m m o n + + + + u s e s + +---------------------------------------+ /********************************************************************************* ******** * e x c e p t i o n s r e s p o n s i b i l i t i e s * ********************************************************************************** ********/

+-------------------------------------+ + + + b e a n d e v e l o p e r + + + +-------------------------------------+

1) if the bean's method (or a method it interacts with) catches or creates a checked exception, this should be passed to the container as it is. the container will then pass the exception to the client as it is. this can be accomplished in two ways: a) by simply declaring the application exception in the method signature, letting it being automatically propagated to the container;

b) if the bean's method catches the application exception, this should be declared in the method signature and re-thrown by the catch block. remember: the way the bean developer has to let the application propagating to the container is by declaring it in the method signature 2) when a bean's method catches an application exception, if the bean's developer realizes that the transaction cannot continue, he/she should invoke the setrollbackonly method (both in the usertransaction and in the ejbcontext interfaces), before re-throwing the exception; 3) if a bean's method (or a method in a class the bean interacts with), checks an application exception that the client didn't expect (i.e. the bean couldn't get a jdbc connection to the database), the bean developer should wrap the application exception in an ejbexception (unchecked), passing the checked exception as argument. the reason is that the client most probably doesn't want to know the problems related to the internal bean state, and if it does, can always invoke the getcause() method on the received exception. remember: the container will pass ejbexception as it is to a local client, while it will wrap the ejbexception in a remoteexception for a remote client 4) never use the following technique: try { int a = 5 / 0 catch(exception e) {} bottom line: catching 'exception' means that runtimeexception (s) will not be propagated to the container. as a client, would you be happy if your business logic would have continued in the above situation? i wouldn't! catching 'exception' is usually a shortcut for lazy programmers. there is nothing wrong in a programmer being lazy, but

the business logic should be preserved, otherwise there will be only lazy unemployed!

5) if a bean's method throws an application exception, this should be declared either in the bean's method signature and in the client's interface 6) if the bean developer creates his/her application exceptions, this should be subclasses of exception but not of runtimeexception.

+-------------------------------------+ + + + c o n t a i n e r + + + +-------------------------------------+

************************************************** * cmt entity/session beans business methods * ************************************************** business methods for entity and session beans are all the methods defined in the bean's component and home interfaces (and all superinterfaces), plus the following methods: ejbcreate<method>, ejbpostcreate<method>, ejbremove(), ejbhome(), ejbfind() ********************************************************************************* ********** * 1st scenario (cmt): invoked method runs in the same transaction context as the invoker; * ********************************************************************************* ********** this may happen if the cmt bean has got one of the following values: a) required b) mandatory c) supports case a) the bean's method throws an application exception. ---------------------------------------------------------+-------------------+ +--------------+ + container + + +-------------------+ +--------------+ 1) throws the exception precisely the exception exactly as it is as it is

+ client

1) receives

case b) the bean's method throws a non application exception. ------------------------------------------------------------+-------------------+ +--------------+ + container + + +-------------------+ +--------------+ 1) logs the exception javax.transaction.transactionrolledbackexception if remote

+ client

1) receives

2) marks the transaction for rollback javax.ejb.transactionrolledbacklocalexception if local 3) discards the bean instance 4) throws a javax.transaction.transactionrolledbackexception if the client is remote 5) throws a javax.ejb.transactionrolledbacklocalexception if the client is local

2) receives

please note the package difference between the remote and local exception: remote: javax.transaction.transactionrolledbackexception ----------local: javax.ejb.transactionrolledbacklocalexception ------********************************************************************************** ********* * 2nd scenario (cmt): invoked method runs in a transaction context started by the * * container immediately before invoking the method * ********************************************************************************** ********* this may happen if the cmt bean has got one of the following values: a) required b) requiresnew case a) the bean's method invokes setrollbackonly() and throws an application exception. --------------------------------------------------------------------------------------+-------------------+ +--------------+ + container + + +-------------------+ +--------------+ 1) rolls back the transaction application exception 2) re-throw the application exception to the client

+ client

1) receives

case b) the bean's method throws an application exception. --------------------------------------------------------------------------------------+-------------------+ +--------------+ + container + +

+ client

+-------------------+ +--------------+ 1) attempts to commit the transaction application exception 2) re-throw the application exception to the client

1) receives

case c) the bean's method throws a non-application exception --------------------------------------------------------------------------------------+-------------------+ +--------------+ + container + + +-------------------+ +--------------+

+ client

1) logs the exception remoteexception if remote 2) rolls-back the container started transaction ejbexception if local 3) discard instance 4) throws a remoteexception to remote clients 5) throws an ejbexception to local clients

1) receives 2) receives

bottom line: -----------for

if the container didn't start the transaction, it can only mark the transaction

rollback, and throw a javax.transaction.transactionrolledbackexception to remote clients of a javax.ejb.transactionrolledbacklocalexception to local clients. if the container did start the transaction, it can rollback it and will throw remoteexception to remote clients, ejbexception to local clients. the transaction attributes: a) required b) mandatory c) supports may leed to a bean's method running in the same transaction context of its caller. in this scenario, because the container didn't start a transaction, in case of a nonapplication exception, the container will only be capable of 'indicating' to the client a rolling back situation. on the other site, the transaction attributes: a) required b) requiresnew

may leed to the container starting (and therefore being the owner) the transaction, therefore in the eventuality of a non-application exception, the container will be entitled to roll-back the transaction, and to throw the equivalent of a runtime exception to the bean's client. this will be a remoteexception for remote clients, and an ejbexception for local clients.

********************************************************************************** ********* * 3rd scenario (cmt): bean's method run in an unspecified transaction context * ********************************************************************************** ********* this may happen if the cmt bean has got one of the following values: a) notsupported b) never c) supports and in the following circumstances: a) for session beans: a1) ejbcreate(), ejbremove(), ejbactivate(), ejbpassivate() b) for message-driver beans: a1) ejbcreate(), ejbremove() case a) the bean's method throws an application exception: --------------------------------------------------------------------------------------+-------------------+ +--------------+ + container + + +-------------------+ +--------------+ 1) re-throw the exception as it is to the client exception as it is

+ client

1) receives the

case b) the bean's method throws a non-application exception: ---------------------------------------------------------------------------------------

+-------------------+ +--------------+ + container + + +-------------------+ +--------------+

+ client

1) logs the exception remoteexception if remote 2) discard the bean instance ejbexception if local 3) throws a remoteexception to remote clients 4) throws an ejbexception to local clients

1) receives 2) receives

************************************************** *

bmt entity/session beans business methods * **************************************************

********************************************************************************** ********* * 1st scenario (bmt): session beans * ********************************************************************************** ********* case a) the bean's method throws an application exception: --------------------------------------------------------------------------------------+-------------------+ +--------------+ + container + + +-------------------+ +--------------+ 1) re-throws the application exception the application exception

+ client

1) receives

case b) the bean's method throws a non-application exception: --------------------------------------------------------------------------------------+-------------------+ +--------------+ + container + + +-------------------+ +--------------+

+ client

1) logs the exception remoteexception if remote 2) discards the bean instance ejbexception if local 3) marks the transaction for rollback 4) throws a remoteexception to remote clients 5) throws an ejbexception to local clients

1) receives 2) receives

why the container here marks 'only' the transaction for rollback? because with bmt, is the bean instance which is supposed to start and end the transaction (with usertransaction.begin() and usertransaction.commit() or rollback() ). the container can't substitute itself to the bean's developer (thus, it can't rollback the transaction), but it can mark it for rollback so to be a good 'transaction citizen'. additionally, it will throw the equivalent of a runtime exception to the bean clients, which therefore will know that something 'unexpected' happened on the server.

********************************* * cmt message-driven beans * ********************************* ********************************************************************************** ********* * 1st scenario (mdb): the bean's method runs in a transaction context started by the * * container * ********************************************************************************** *********

case a) the bean's method throws a non-application exception: (message driven beans shouldn't throw application exception. who would catch them?) -----------------------------------------------------------------------------------------+-------------------+ + container + +-------------------+ 1) logs the exception 2) rolls back the transaction that it started 3) discard the bean instance

********************************************************************************** ********* * 2nd scenario (mdb): the bean's method runs in an unspecified transaction context * ********************************************************************************** ********* case a) the bean's method throws a non-application exception from an unspecified tx context: (message driven beans shouldn't throw application exception. who would catch them?) -----------------------------------------------------------------------------------------this may happen if the onmessage() bean method runs with the notsupported transaction attribute and for ejbcreate() and ejbremove() +-------------------+ + container + +-------------------+ 1) logs the exception 2) discard the bean instance

********************************* * bmt message-driven beans * ********************************* case a) the bean's method throws a non-application exception: (message driven beans shouldn't throw application exception. who would catch them?) -----------------------------------------------------------------------------------------+-------------------+ + container + +-------------------+ 1) logs the exception 2) marks the bean for rollback 3) discard the bean instance

********************************* * container callbacks methods * *********************************

these are: 1) entity beans: setentitycontext(),

ejbactivate(), ejbpassivate(), ejbload(), ejbstore(), unsetentitycontext()

2) session beans: ejbactivate(), ejbpassivate(), setsessioncontext() 3) stateful session beans: afterbegin(), beforecompletion(), aftercompletion of the sessionsynchronization interface 4) message-driven beans: setmessagedrivencontext()

the container must handle all the exceptions (application and nonapplication) as follows: 1) 2) 3) 4) instance is to remote

log the application exception if the instance is in a transaction, mark the instance for rollback discard the instance if the exception occurred during a client's method invocation, and the not running in the client's transaction context, throw remoteexception

clients, and ejbexception to local clients 5) if the exception occurred during a client's method invocation and the instance was running in the client's transaction context, throw the javax.transaction.transactionrolledbackexception to remote clients, and javax.ejb.transactionrolledbacklocalexception to local clients

****************************************** * javax.ejb.nosuchentityexception * *

*

javax.ejb.ejbexception

*

java.rmi.nosuchobjectexception

*

* javax.ejb.nosuchobjectlocalexception * ****************************************** the javax.ejb.nosuchentityexception is throws by an entity bean when trying to access an underlying entity that was removed. in this case, the container should apply the same rules as ejbexception, because nosuchentityexception is a subclass of ejbexception. however...the container should throw: a) java.rmi.nosuchobjectexception b) javax.ejb.nosuchlocalobjectexception

to remote clients to local clients

the reason is that those exceptions give more information about what happened that not the nosuchentityexception. the above two exceptions should also be thrown by the container if a client tries to invoke a business method on an object which has been removed.

therefore we could assume that, any time a client (which could be also another bean), tries to 'use' an object which is not there (most probably because it was removed), the following exceptions will be thrown: a) java.rmi.nosuchobjectexception b) javax.ejb.nosuchlocalobjectexception

to remote clients to local clients

************************************ * container and cmt transactions * ************************************ if the container (we are talking about internal container behaviours here), fails to start or commit (or rollback) a transaction, for session and entity beans it should throw a remoteexception to remote clients, and an ejbexception to local clients. in case of message-driven beans, and in the above situation, the container should throw a javax.ejb.ejbexception

/********************************************************************************* ******** * r o l e s r e s p o n s i b i l i t i e s * ********************************************************************************** ********/

generally speaking, the bean developer is responsible to define the <enterprisebeans> section of the deployment descriptor, the application assembler is responsible to group one or more beans in a larger application, and to link some of the references used by the bean developer so that these have a meaning in the deployment descriptor; finally the bean deployer has got the responsibility to assign a security domain and

a security realm to the application and to resolve all the external dependencies so that the ejb application can work in the operation environment. each bean is given a special jndi environment, which it can access during its lifecycle. the special jndi environment is guaranteed as key features for each ejb 2.0 compliant container and is identified by the 'java:comp/env' jndi subcontext, root from which every enterprise bean will start looking for resources. thanks to the jndi special environment, a bean can lookup: 1) environment entries 2) resource manager connection factories 3) other enterprise javabeans 4) resource environment references the bean developer, additionally, may want to use programmatic security from within the bean; for this purpose, she will tipically use the ejbcontext.iscallerinrole(string s) method to change bean's behaviour depending on a specific role. this approach can be necessary when ejb security must be granted as an 'instance' level, rather than at a 'class' level. the problem here is that with declarative security (security roles, method permissions, responsibilities of the application assembler) all the instances of a certain bean will face the same security policy. if the business logic needs to customize the bean's behaviour depending on a certain role or the matching of a principal name against some bean instance variables, the bean developer needs to 'hard code' some names into the bean class. the same happens for all the four above mentioned activities: the bean provider needs to hard code n a m e s into the bean class. if you're thinking as a bean developer, and you're hard coding names within your bean class, you will come first or later to face a problem: because the bean developer doesn't know (following the specs, and not the real case, where most of the time will be the opposite) the target environment where the bean will run, and on the other side he has to make its application working, to ensure the component model offered by ejbs, the bean developer needs a way to communicate to the people who will take responsibility of the ejb application at assembly and deployment time which names she used from within the bean class in order to:

1) 2) 3) 4) 5) 6)

query the container about a principal's identity query the container about a principal's permission lookup for environment entries lookup for resource manager connection factories lookup for other enterprise javabeans lookup for resource environment entries

because the engineers at sun are cleverer than one would've thought, they thought of the deployment descriptor as a means of communication between: 1) the bean developer and the application assembler 2) the bean developer and the bean deployer 3) the application assembler and the bean deployer the thing works like this: 1) the bean developer thinks: 'ok, i had to use some fake names from within my bean, otherwise i could never deliver to you my bean. i will tell you which names i've used in the deployment descriptor. 2) the application assembler and the bean deployer think: 'all right. i see you've used some fake names: i will simply map those names to something that really exists in the application so that the bean will be ready for the operational environment therefore: b e a n d e v e l o p e r s e m b l e r

---->

xml dd

<----

a p p l i c a t i o n b e a n

a s

d e p l o y e r

here follows a brief explanation of the dd elements related to the six points mentioned above and the responsibilities for bean developer, application assembler, bean deployer. for brevity, these are the 'codes' to identify each role: bd aa dpy dd

----> ----> ----> ---->

bean developer application assembler bean deployer deployment descriptor

+---------------------------------------------------------------------------+ + p r o g r a m m a t i c s e c u r i t y + +---------------------------------------------------------------------------+

roles involved: bd and aa --------------------------

the business requirement: ------------------------the bd needs to tailor the bean's security behaviour depending on:

a) the principal identity or b) the caller's role the software solution: ---------------------while for case a), the bd could compare the principal name to some instance variable containing some hard coded value, for case b the bd could write something as follows: if (ctx.iscallerinrole("agenericadmin")) { //raise all wages by 10% } the bd would write the following element in the deployment descriptor: <security-role-ref> <description>i've used 'agenericadmin' as security role reference as the only authorized person to make changes to the payroll agenericadmin the aa, would look at the <security-role-ref> element of the dd and would think: 'ok, the bean developer used 'agenericadmin' as a security role, but for the business domain in which the application will run, i chose to use only a 'superadmin' role for activities of this kind. no worries: i'll link 'agenericadmin' to 'superadmin', which i've defined in the section of the dd, in the <securityrole> element. <ejb-jar>

<enterprise-beans> <session> .. .. <security-role-ref> <description>i've used 'agenericadmin' as security role reference as the only authorized person to make changes to the payroll agenericadmin superadmin ---> the aa links 'agenericadmin' with 'superadmin' <security-role> <description>the superadmin role is the only role who can make changes to monetary values. superadmin +---------------------------------------------------------------------------+ + u s i n g e n v i r o n m e n t e n t r i e s + +---------------------------------------------------------------------------+ roles involved: bd and (aa or dpy) ----------------------------------the business requirement: ------------------------bd wants to use a parameter as agents bonus percentage. because bd doesn't know the bonus percentage applied by the company running the target environment to its agents, it will use a made-up one. bd will then inform aa or dpy about the environment name she used from within the bean class the software solution: ---------------------bd will write the following in the bean class: integer bonusrate = (integer)ctx.lookup("java:comp/env/bonusrate"); //do something with bonus percentage

bd will write the following element in the deployment descriptor:

<ejb-jar> <enterprise-beans> <session> .. .. <env-entry> <description>i used 'bonusrate' as bonus percentage that the company will calcuate for its agents, when they will reach the selling target.

pssst! aa, dpy! the value of 1.5 is ridicously low, so please

assign

to this entry a meaningful value for the operational environment <env-entry-name>bonusrate <env-entry-type>java.lang.integer <env-entry-value>1.5 aa (or dpy) will think: 'ah, look at bd! he used a parameter called 'bonusrate' to inform the bean about our bonus percentage to the agents. let me change the <env-entry-value> to at least...let me see....5 percent. should our agents see the dd now, i would risk big troubles.'

(they change the environment entry value)

+---------------------------------------------------------------------------+ + u s i n g r e s o u r c e m a n a g e r c o n n e c t i o n + + + + f a c t o r i e s r e f e r e n c e s + +---------------------------------------------------------------------------+ roles involved: bd and dpy ----------------------------------the business requirement: ------------------------the bd needs to get a reference to a resource manager connection factory from

within the bean class. a resource connection factory can be one of the following types: 1) 2) 3) 4) 5)

javax.jms.queueconnectionfactory javax.jms.topicconnectionfactory javax.sql.datasource javax.mail.session java.net.url

the software solution: ---------------------the bd performs a lookup of the required resource on the jndi special environment assigned to each bean. as usual, the bd doesn't know anything about the target (operational) environment, but still has to guarantee the functionality from within the bean. so she uses a made-up name in the lookup and informs the dpy about the name she used. from within the bean class, the bd writes something similar to the following: try { connection conn = (datasource)ctx.lookup("java:comp/env/jdbc/myconnectionds").getconnection(); } catch (...) //this is a checked exception. btw...do you remember what the bd responsibility is //if such exception is caught? (hint...the client doesn't need to know that some //internal operational details went wrong, although this is a checked exception... //you will quite almost certainly find a question related to the above situation //in your exam. in the deployment descriptor: <ejb-jar> <enterprise-beans> <session> .. .. <description>optional jdbc/myconnectionds javax.sql.datasource

container shareable //this is optional unshareable //this is optional the dpy, reads the above dd declaration, and using vendor specific tools, ensures that the connection factory is bound to an existing (and working) connection factory on the operational environment (for instance she ensures that'jdbc/myconnectionds' is deployed as a javax.sql.datasource in the application server. +---------------------------------------------------------------------------+ + r e f e r e n c i n g o t h e r b e a n s + +---------------------------------------------------------------------------+ roles involved: bd, aa and dpy ----------------------------------the business requirement: ------------------------very often in your design, especially if you will use entirely an ejb based approach, will occur that the ejb you're designing will need to get a reference to another bean. a bean can lookup for another bean from the jndi special environment assigned to each bean. here as well, the bd uses a made-up name because he doesn't know how the aa and/or the dpy have called the bean in the operation environment. so he will inform the aa about the name he used from within the bean class through the dd and the aa will bind the made-up name used by the bd to an <ejb-name> element in the <enterprise-beans> section of the dd. the software solution: ---------------------from within the bean class the bd will use something like the following:

try { myorderhome mch = (myorderhome)ctx.lookup("java:comp/env/ejb/orderhome"); myorder mo = mch.create(); //use myorder ejbobject } catch (...) //checked exception in the deployment descriptor: <ejb-jar> <enterprise-beans> <session> .. .. <ejb-ref> <ejb-ref-name>ejb/orderhome <ejb-ref-type>session foo.bar.orderhome foo.bar.orderhome <ejb-local-ref> <ejb-ref-name>ejb/orderhome <ejb-ref-type>session foo.bar.orderlocalhome foo.bar.orderlocalhome the aa will read the dd and think: "well, the bd informed me he used 'ejb/orderhome' to refer to the order bean defined in the <enterprise-beans> section with the <ejb-name> 'purchaseorders'. i just need to link the name used by the bd to the label (<ejb-name>) identifying this bean.

<ejb-ref>

<ejb-ref-name>ejb/orderhome <ejb-ref-type>session foo.bar.orderhome foo.bar.orderhome <ejb-link>purchaseorders //this is responsibility of the aa

if, in the .ear file there is more than one ejb-jar file and the <ejb-name> element with the content 'purchaseorders' has been defined in more than one ejb-jar file, there is a name conflict. the aa can use the alternate form of <ejb-link> to give the absolute path to the jar file containing the bean to link to <ejb-ref>, followed by the '#' and the value of <ejb-name>. the dpy has got the responsibility of ensuring that the bean reference used by the bd is of the right type for the bean home deployed in the operational environment.

+---------------------------------------------------------------------------+ + r e f e r e n c i n g a r e s o u r c e e n v i r o n m e n t + + + + v a r i a b l e s +---------------------------------------------------------------------------+ roles involved: bd and dpy ----------------------------------the business requirement: ------------------------the bd needs to get a reference to a resource environment variable. again, she will lookup the special jndi environment and get a connection, typically, to a queue or a topic (jms destinations). she will then probably send a message to the administered object. the software solution: ---------------------from within the bean class the bd will use something like the following: try { javax.jms.queue queue = (javax.jms.queue)ctx.lookup("java:comp/env/jms/queuea"); //use the queue } catch (...) //checked exception

in the deployment descriptor: <ejb-jar> <enterprise-beans> <session> .. .. jms/queuea javax.jms.queue the dpy will need to ensure that a queue or topic with the jndi name 'jms/queuea' is up and running in the operational environment. the dpy will ensure this using vendor specific tools.