scbcd for ejb 2.

0
document edited by marco tedone
jemos group (www.jemos.co.uk)
for comments and suggestions please email: mtedone@jemos.co.uk
-------------------------------------------------

/******************************************************************
* i n t e r f a c e s *
******************************************************************/

1) ejbhome interface

a) ejbmetadata getejbmetadata();
b) homehandle gethomehandle();
c) void remove(handle h);
d) void remove(object key);

2) ejblocalhome interface

a) void remove(object key);

3) ejbobject interface

a) object getprimarykey();
b) ejbhome getejbhome();
c) handle gethandle();
d) void remove();
e) boolean isidentical();

4) ejblocalobject interface

a) object getprimarykey();
b) ejblocalhome getejblocalhome();
c) void remove();
d) boolean isidentical();

5) sessioncontext interface

a) ejbhome getejbhome(); --> from ejbcontext

b) ejblocalhome getejblocalhome(); --> from ejbcontext
c) ejbobject getejbobject();
d) ejblocalobject getejblocalobject();
e) boolean getrollbackonly(); --> from ejbcontext
f) void setrollbackonly(boolean b); --> from ejbcontext
g) usertransaction getusertransaction(); --> from ejbcontext
h) boolean iscallerinrole(string s); --> from ejbcontext
i) principal getcallerprincipal(); --> from ejbcontext

6) entitycontext interface

a) ejbhome getejbhome(); --> from ejbcontext

b) ejblocalhome getejblocalhome(); --> from ejbcontext
c) ejbobject getejbobject();
d) ejblocalobject getejblocalobject();
e) boolean getrollbackonly(); --> from ejbcontext
f) void setrollbackonly(boolean b); --> from ejbcontext
 g) boolean iscallerinrole(string s); --> from ejbcontext
h) principal getcallerprincipal(); --> from ejbcontext
i) object getprimarykey();

7) messagedrivencontext interface

a) ejbhome getejbhome(); --> from ejbcontext (not used)

b) ejblocalhome getejblocalhome(); --> from ejbcontext (not used)

e) boolean getrollbackonly(); --> from ejbcontext

f) void setrollbackonly(boolean b); --> from ejbcontext
g) usertransaction getusertransaction(); --> from ejbcontext
h) boolean iscallerinrole(string s); --> from ejbcontext (not used)
i) principal getcallerprincipal(); --> from ejbcontext (not used)

8) sessionbean interface

a) void ejbactivate();
b) void ejbpassivate();
c) void ejbremove();
d) void setsessioncontext(sessioncontext ctx);

9) entitybean interface

a) void ejbactivate();
b) void ejbpassivate();
c) void ejbremove();
d) void setentitycontext(entitycontext ctx);
e) void unsetentitycontext();
f) void ejbload();
g) void ejbstore();

10) messagedrivenbean interface

a) void ejbremove();
b) void setmessagedrivecontext(messagedrivencontext ctx);

11) messagelistener interface

a) onmessage(message m);

12) usertransaction interface

a) void begin()
b) void commit()
c) int getstatus()
d) void rollback()
e) setrollbackonly()
f) 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) query the container about client's security info
3) set a cmt transaction for roll-back
4) query the container to check if a cmt transaction has already been
marked for roll-back
5) access the jndi special environment
6) access other bean's methods
7) access other resource managers

c3) ejbpostcreate(), ejbremove()

1) get a reference to the bean's home interface

2) get a reference to the bean's component interface
3) get the primary key
4) query the container about client's security info
5) set a cmt transaction for roll-back
6) query the container to check if a cmt transaction has already been
marked for roll-back
7) access the jndi special environment
8) access other bean's methods
9) access other resource managers

c4) home business method

1) get a reference to the bean's home interface

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

c5) ejbactivate(), ejbpassivate()

1) get a reference to the bean's home interface

2) get a reference to the bean's component interface
3) get the primary key
4) access the jndi special environment

c6) ejbload(), ejbstore()

1) get a reference to the bean's home interface

2) get a reference to the bean's component interface
3) get the primary key
4) query the container about client's security info
5) set a cmt transaction for roll-back
6) query the container to check if a cmt transaction has already been
marked for roll-back
7) access the jndi special environment
8) access other bean's methods
9) access other resource managers

d) from the sessionsynchronization callback methods:

d1) from afterbegin() and beforecompletion() --> transaction safe

context
 d1a) get a reference to the home and component interfaces
d1b) query the container about client's security info
d1c) rollback a transaction
d1d) 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() --> not in a transaction

anymore. not safe

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) removeexception
c) finderexception
d) objectnotfoundexception
e) 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 <trans-attribute>
values:

a) required
b) mandatory
c) supports

case a) the bean's method throws an application exception.

----------------------------------------------------------

+-------------------+
+--------------+
+ container + + client
+
+-------------------+
+--------------+

1) throws the exception precisely 1) receives

the exception exactly as it is
as it is

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

-------------------------------------------------------------

+-------------------+
+--------------+
+ container + + client
+
+-------------------+
+--------------+

1) logs the exception 1) receives

javax.transaction.transactionrolledbackexception if remote
 2) marks the transaction for rollback 2) receives
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

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 <trans-attribute>
values:

a) required
b) requiresnew

case a) the bean's method invokes setrollbackonly() and throws an application

exception.
---------------------------------------------------------------------------------
-------

+-------------------+
+--------------+
+ container + + client
+
+-------------------+
+--------------+

1) rolls back the transaction 1) receives

application exception
2) re-throw the application exception to the client

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

---------------------------------------------------------------------------------
-------

+-------------------+
+--------------+
+ container + + client
+
 +-------------------+
+--------------+

1) attempts to commit the transaction 1) receives

application exception
2) re-throw the application exception to the client

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

---------------------------------------------------------------------------------
-------

+-------------------+
+--------------+
+ container + + client
+
+-------------------+
+--------------+

1) logs the exception 1) receives

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

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

if the container didn't start the transaction, it can only mark the transaction
for
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 non-
application
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 <trans-attribute>
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 + + client
+
+-------------------+
+--------------+

1) re-throw the exception as it is to the client 1) receives the

exception as it is

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

----------------------------------------------------------------------------------
------
+-------------------+
+--------------+
+ container + + client
+
+-------------------+
+--------------+

1) logs the exception 1) receives

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

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

* bmt entity/session beans business methods *

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

**********************************************************************************
*********
* 1st scenario (bmt): session beans
*
**********************************************************************************
*********

case a) the bean's method throws an application exception:

----------------------------------------------------------------------------------
------

+-------------------+
+--------------+
+ container + + client
+
+-------------------+
+--------------+

1) re-throws the application exception 1) receives

the application exception

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

----------------------------------------------------------------------------------
------

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

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: ejbactivate(), ejbpassivate(), ejbload(), ejbstore(),

setentitycontext(),
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 non-
application) as follows:

1) log the application exception

2) if the instance is in a transaction, mark the instance for rollback
3) discard the instance
4) if the exception occurred during a client's method invocation, and the
instance is
not running in the client's transaction context, throw remoteexception
to remote
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 to remote clients

b) javax.ejb.nosuchlocalobjectexception 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 to remote clients

b) javax.ejb.nosuchlocalobjectexception 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 <enterprise-

beans>
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) query the container about a principal's identity
2) query the container about a principal's permission
3) lookup for environment entries
4) lookup for resource manager connection factories
5) lookup for other enterprise javabeans
6) 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 ----> xml dd <---- a p p l i c a t i o n a s

s e m b l e r

b e a n 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 ----> bean developer

aa ----> application assembler
dpy ----> bean deployer
dd ----> 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
</description>
<role-name>agenericadmin</role-name>
</security-role-ref>

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 <assembly-descriptor> section of the dd, in the <security-
role>
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
</description>
<role-name>agenericadmin</role-name>
<role-link>superadmin</role-link> ---> the aa links 'agenericadmin' with
'superadmin'
</security-role-ref>
</session>
</enterprise-beans>

<assembly-descriptor>

<security-role>
<description>the superadmin role is the only role who can make changes
to monetary values.
</description>
<role-name>superadmin</role-name>
</security-role>
</assembly-descriptor>

</ejb-jar>

+---------------------------------------------------------------------------+
+ 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
</description>
<env-entry-name>bonusrate</env-entry-name>
<env-entry-type>java.lang.integer</env-entry-type>
<env-entry-value>1.5</env-entry-value>

</env-entry>

</session>

</enterprise-beans>

</ejb-jar>

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) javax.jms.queueconnectionfactory
2) javax.jms.topicconnectionfactory
3) javax.sql.datasource
4) javax.mail.session
5) 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>
..
..
<resource-ref>

<description>optional</description>
<res-ref-name>jdbc/myconnectionds</res-ref-name>
<res-type>javax.sql.datasource</res-type>
<!-- <res-type>javax.jms.queueconnectionfactory</res-type> -->
 <!-- <res-type>javax.jms.topicconnectionfactory</res-type> -->
<!-- <res-type>javax.mail.session</res-type> -->
<!-- <res-type>java.net.url</res-type> -->
<res-auth>container</res-auth>
<!-- <res-auth>bean</res-auth> -->
<res-sharing-scope>shareable</res-sharing-scope> //this is optional
<res-sharing-scope>unshareable</res-sharing-scope> //this is optional

</resource-ref>

</session>

</enterprise-beans>

</ejb-jar>

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-name>
<ejb-ref-type>session</ejb-ref-type>
<!-- <ejb-ref-type>entity</ejb-ref-type> -->
<home>foo.bar.orderhome</home>
<remote>foo.bar.orderhome</remote>

</ejb-ref>

<!-- or, if the client view is local -->

<ejb-local-ref>

<ejb-ref-name>ejb/orderhome</ejb-ref-name>
<ejb-ref-type>session</ejb-ref-type>
<!-- <ejb-ref-type>entity</ejb-ref-type> -->
<local-home>foo.bar.orderlocalhome</local-home>
<local>foo.bar.orderlocalhome</local>

</ejb-local-ref>

</session>

</enterprise-beans>

</ejb-jar>

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-name>
<ejb-ref-type>session</ejb-ref-type>
<!-- <ejb-ref-type>entity</ejb-ref-type> -->
<home>foo.bar.orderhome</home>
<remote>foo.bar.orderhome</remote>
<ejb-link>purchaseorders</ejb-link> //this is responsibility of the aa
</ejb-ref>

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>
..
..
<resource-env-ref>

<res-env-ref-name>jms/queuea</res-env-ref-name>
<res-env-ref-type>javax.jms.queue</res-env-ref-type>
<!-- <res-env-ref-type>javax.jms.topic</res-env-ref-type> -->
</resource-env-ref>

</session>

</enterprise-beans>

</ejb-jar>

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.