Update of /cvsroot/xdoclet/xdoclet/xdocs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv29691/xdocs
Modified Files:
navigation.xml
Added Files:
envhandling.xml
Log Message:
documentation for the new environment handling added (XDT-1325)
--- NEW FILE: envhandling.xml ---
<?xml version="1.0"?>
<document>
<properties>
<author email="[EMAIL PROTECTED]">Matthias Germann</author>
<title>EJB Environment Handling</title>
</properties>
<head>
<link rel="shortcut icon" href="favicon.ico" />
<link rel="icon" href="favicon.ico" />
</head>
<body>
<section name="EJB Environment Handling">
<p>
Declaring and accessing a Enterprise Java Bean's component
environment
properties (i.e. environment entries, ejb references, resource
references)
is complicated and error-prone. It's a source for typo's
which remain undiscovered until the EJB is deployed and run in
the
EJB Container. Moreover, the EJB Bean Provider has to write the
same lookup code
over and over again.
</p>
<p>
The Service Locator Pattern tries to solve the problem by
having a
centralized place for the lookups. The big disadvantage of this
pattern
is each bean must use the same naming for it's environment
properties. Thiy may
also be a source of very strange behaviour when two bean's use
the same name
for different things. A possible solution is to use the
physical JNDI-Names
instead of the names inside the <code>java:comp/env</code>
namespace. It
but it's at the border of the EJB specification because the
beans do no longer
declare their ejb and resource references.
</p>
<p>
XDoclet makes it now a lot easier to declare and access
environment properties
and it's even possible that each bean uses it's own naming!
This is done
by expanding the current tags for declaring environment
properties
(i.e. <code>@ejb.env-entry</code>, <code>@ejb.ejb-ref</code>)
to field and
method level. The lookup of the properties is delegated to the
technical
bean generated with the <code>session</code>, <code>mdb</code>,
<code>entitybmp</code> and <code>entitycmp</code> subtask.
This means that the only thing you have to do is to declare a
field or
a abstract method with a XDoclet tag. The deploymentdescriptor
entries and
the lookup from the JNDI-Tree is generated by XDoclet! The bean
has not a
single line of JNDI-Code.
</p>
<subsection name="A simple example">
<p>
Let's have a look at a simple example. This example declares a
field-level
environment entry and a method-level ejb reference. <b>Please
note that this
is not a complete example:</b> there are many tags missing,
only the ones
related to the new environment handling are presented here.
</p>
<source>
package example.ejb;
import javax.ejb.SessionBean;
/**
* This is a environment handling example for XDoclet.
*
* @ejb.bean
* type="Stateless"
* name="Customer"
* view-type="local"
*
*/
public abstract class MySessionEJB implements SessionBean {
/**
* @ejb.env-entry
* value="1234"
*/
protected int aFieldLevelEnvEntry();
/**
* @ejb.ejb-ref
* ejb-name="Customer"
*/
protected abstract CustomerLocal aMethodLevelEjbRef();
}
</source>
<p>
The field-level property must be declared protected to ensure
that it
can be set from the XDoclet-generated subclass. For the
method-level
property, the method must be declared protected and abstract so
that
it can be implemented by the XDoclet-generated subclass.
</p>
<p>
Let's see what the <code>deploymentdescriptor</code> subtask
generated. Here is a snipplet
of the generated ejb-jar.xml.
</p>
<source>
<![CDATA[
<env-entry>
<env-entry-name>aFieldLevelEnvEntry</env-entry-name>
<env-entry-type>java.lang.Integer</env-entry-type>
<env-entry-value>1234</env-entry-value>
</env-entry>
<ejb-local-ref>
<ejb-ref-name>aMethodLevelEjbRef</ejb-ref-name>
<ejb-ref-type>Session</ejb-ref-type>
<local-home>example.ejb.CustomerLocalHome</local-home>
<local>example.ejb.CustomerLocal</local>
</ejb-local-ref>
]]>
</source>
<p>
A env-entry element and a ejb-local-ref element are generated
for the
declared environment properties. The names are set to the
field- and
method-name. It is possible to customize the names with the
<code>name</code> and <code>ref-name</code> parameters of the
<code>@ejb.env-entry</code> resp. <code>@ejb.ejb-ref</code>
tag.
</p>
<p>
Now comes the intersting part. The XDoclet-generated technical
bean class.
This class is generated with the <code>session</code> subtask.
</p>
<source>
/*
* Generated by XDoclet - Do not edit!
*/
package example.ejb;
/**
* Session layer for MySession.
*/
public class MySessionSession
extends ejb.env.MySessionEJB
implements javax.ejb.SessionBean
{
public void setSessionContext(javax.ejb.SessionContext ctx)
{
javax.naming.Context namingCtx = null;
try
{
namingCtx = new javax.naming.InitialContext();
aFieldLevelEnvEntry = ((java.lang.Integer)
namingCtx.lookup("java:comp/env/aFieldLevelEnvEntry")).intValue();
aMethodLevelEjbRef = (example.ejb.CustomerLocalHome)
namingCtx.lookup("java:comp/env/aMethodLevelEjbRef");
}
catch(javax.naming.NamingException e)
{
throw new javax.ejb.EJBException("lookup failed", e);
}
finally {
if (namingCtx != null)
{
try
{
namingCtx.close();
}
catch(javax.naming.NamingException e)
{
e.printStackTrace();
}
}
}
}
private example.ejb.CustomerLocalHome aMethodLevelEjbRef;
protected example.ejb.CustomerLocal aMethodLevelEjbRef()
{
try
{
return aMethodLevelEjbRef.create();
}
catch(javax.ejb.CreateException e)
{
throw new javax.ejb.EJBException("create failed", e);
}
}
}
</source>
<p>
The XDoclet-generated class performs the lookup of the
declared environment properties.
The value is cached for method-level properties. If the
return-type of a method-level
ejb-reference is the component interface, a automatic call
to the <code>create()</code>
method of the home-interface was generated!
</p>
</subsection>
<subsection name="EJB references">
<p>
As you could see in the previous example, it's very easy to
make a reference to another
EJB by adding a abstract method which returns the
referenced EJB's component interface.
The XDoclet-generated technical bean class will do the
lookup and call the <code>create()</code>
method.
</p>
<p>
This makes it very easy to reference to a stateless session
bean. And it's also the recommended
way for this because the Home-Interface of a stateless
session bean is most of the time only used
for calling the <code>create()</code> method. But it's not
a good idea to use this feature for
references to stateful session beans and entity beans where
the Home-Interface plays a bigger role.
For those bean types, it's recommended that the abstract
method returns the Home-Interface
instead of the Component-Interface.
</p>
</subsection>
<subsection name="Caching">
<p>
For method-level properties, the values are cached in a
private memeber of the XDoclet-generated
technical bean class. Therefore, the developer is not
required to care about caching.
</p>
</subsection>
<subsection name="Stateful Session Bean Passivation">
<p>
When a stateful session bean is passivated, the nvironment
properties of the follwing
types are not passivated. They are set to <code>null</code>
in <code>ejbPassivate()</code>
and re-fetched from the JNDI-Tree in
<code>ejbActivate()</code>.
<ul>
<li><code>@ejb.resource-ref</code></li>
<li><code>@ejb.resource-env-ref</code></li>
<li><code>@ejb.destination-ref</code></li>
<li><code>@ejb.ejb-service-ref</code></li>
</ul>
</p>
<p>
Environment properties of the follwing types are passivated.
<ul>
<li><code>@ejb.env-entry</code></li>
<li><code>@ejb.ejb-ref</code></li>
<li><code>@ejb.ejb-env-ref</code></li>
</ul>
</p>
</subsection>
</section>
</body>
</document>
Index: navigation.xml
===================================================================
RCS file: /cvsroot/xdoclet/xdoclet/xdocs/navigation.xml,v
retrieving revision 1.47
retrieving revision 1.48
diff -C2 -r1.47 -r1.48
*** navigation.xml 8 Feb 2005 17:41:55 -0000 1.47
--- navigation.xml 12 Apr 2005 21:10:25 -0000 1.48
***************
*** 69,72 ****
--- 69,73 ----
<menu name="Feature Documentation">
<item name="Using Value Objects"
href="/valueobjects.html"/>
+ <item name="EJB Environment Handling" href="/envhandling.html"/>
</menu>
<menu name="Advanced">
-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click
_______________________________________________
xdoclet-devel mailing list
xdoclet-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/xdoclet-devel
