CMP and CMR with jBoss 3.2
Summary
This article is a simple DIY for using CMP and CMR with jBoss 3.2.x. You will learn how to use XDoclet to quickly develop an EAR application and deploy this application in jBoss 3.2.x.
The author is Thierry Janaudy, a technical architect, expert in J2EE architectures. You can learn more about him by reading the interview we have made of him.
September, 13th 200
Prerequisites
I have used the following software on my Power Book G4 using J2SE 1.4.1:
The source code is available here.
Folders structure
You can use Eclipse to create a new Java project by pointing at the root folder of the source code distribution.
- client-module contains the client soure code as well as the jndi.properties file
- ejb-module contains our 2 entity beans CMP (ItemBean and OrderBean) as well as the generated XML deployment descriptors (using XDoclet)
- gen-src contains the generated source code for the home and remote interfaces
- article contains this html document and the related images
- build contains the build.xml file for ANT as well as the generated EAR file
- ear-module contains the generated JAR file and the application.xml file in META-INF
Introducing XDoclet
I have written an article for JavaWorld about EJBGen (Accelerate
EJB 2.0 development with EJBGen) which is an EJB 2.0 code
generator for the Weblogic Application Server from BEA.
Using EJBGen you can quickly develop and maintain EJB 2.0 code
because you only focus on the bean class, and by using tag
declaration in your code, EJBGen generates home and remote
interfaces as well as XML deployment descriptors.
Whereas EJBGen only targets EJB 2.0 code for Weblogic Server,
XDoclet uses the same paradigm - called Attribute Oriented Programming
- for a broader range of application servers (jBoss, OC4J, Pramati,
Websphere, Weblogic, ...) and technologies (EJB, JMX, JDO, Struts,
Webwork, ...).
The following code fragment shows how the Order Entity Bean CMP
is declared:
/**
* OrderBean
*
* @ejb.bean
* cmp-version="2.x"
* jndi-name="org.jyperion.sample.j2ee.ebcmr.OrderBean"
* name="Orders"
* primkey-field="orderid"
* type="CMP"
* view-type="remote"
* * @ejb.persistence
* table-name="Orders"
* * @ejb.finder
* method-intf="Home"
* query="SELECT OBJECT(o) FROM Orders o"
* signature="java.util.Collection findAllOrders()"
* * @ejb.finder
* method-intf="Home"
* query="SELECT OBJECT(o) FROM Orders AS o, IN(O.items) i
* WHERE i.description = ?1"
* signature="java.util.Collection
* findAllOrdersWithDescription(java.lang.String itemDesc)"
*
* @author janaudy
* @version 1.0
*/ public abstract class OrderBean implements EntityBean { ...
As you can see, the tags are simple. Please refer to the XDoclet documentation for an intensive description of all the tags.
CMP tag
Here is the tag declaration for a CMP field:
/** * @ejb.persistent-field * * @ejb.persistence * column-name="orderid" * * @ejb.interface-method * view-type="remote" * * @ejb.pk-field * * @return Order id */ public abstract String getOrderid();
This tag declares that orderid is a persistent cmp field to the column orderid of the table Orders (declared above) and that orderid is the primary-key of this class.
Remote method
Here is the tag declaration for a remote method:
/** * @ejb.interface-method * view-type="remote" * * @param Order date */ public abstract void setOrderDate(Date orderDate);
CMR tag
In our example, an order can have many items, there is a one-to-many
relationship between the Order Entity Bean and the Item Entity
Bean. Note that you can only work with local interfaces for the
CMR accessors.
|
Order Entity Bean: getItems accessor
/** * getItems * * Returns a collection of items (via its Local interface) * * @ejb.interface-method * view-type="local" * * @ejb.relation * name="order-items" * role-name="order-has-items" * target-ejb="Item" * target-multiple="no" * target-role-name="item-has-order" * * @jboss:target-relation * related-pk-field="orderid" * fk-column="orderid_fk" * * @return a Collectionn of items */ public abstract Collection getItems();
As you can see, the targeted ejb is set to Item (target-ejb="Item"), and the jBoss specific tag @jboss:target-relation is used to reference the foreign column in Item (fk-column) that obviously corresponds to the orderid in Order (related-pk-field).
The build file
In order to use XDoclet, you must use ANT. In the build.xml file provided, several steps are important.
Include the XDoclet jars in the classpath
<fileset dir="${xdoclet.libs}"> <include name="*.jar"/></fileset>
taskdef declaration
<taskdef name="xdoclet" classname="xdoclet.DocletTask" classpathref="my.class.path"/><taskdef name="ejbdoclet" classname="xdoclet.modules.ejb.EjbDocletTask" classpathref="my.class.path"/>
The target to use the xdoclet and ejbdoclet
<target name="ejbdoclet" depends="prepare">
<ejbdoclet destdir="${gen-src-folder}"
excludedtags="@version,@author,@todo"
addedtags="@xdoclet-generated at ${TODAY},@copyright
The XDoclet Team,@author XDoclet,@version 1.2 beta 2"
ejbspec="2.0"
verbose="true">
<fileset dir="${ejb-module}">
<include name="org/jyperion/j2ee/sample/ebcmr/*.java"/>
</fileset>
<deploymentdescriptor destdir="${ejb-meta-inf}"/>
<homeinterface/>
<remoteinterface/>
<localhomeinterface/>
<localinterface/>
<jboss version="3.0"
unauthenticatedPrincipal="nobody"
xmlencoding="UTF-8"
destdir="${ejb-meta-inf}"
validatexml="true"
preferredrelationmapping="relation-table"/>
</ejbdoclet> </target>
Introducing jBoss
No. I am just kidding. Everybody knows jBoss.
One thing worth mentioning though, jBoss is on the path to J2EE
certification. Read jBoss
and Apache (Bob Bickel) and JBoss,
Sun Approach Agreement On J2EE License
The best way to learn how to use jBoss is still to buy the jBoss
documentation.
The hardest part: the deployment in jBoss
Once you have built the ear file, just drop it in the deploy folder
of your jBoss distrib!
And because I am nice, click here for
a picture of the whole shebang on my Mac!
Author
Thierry Janaudy is a Technical Architect working for Jyperion Ltd.
