User: ibruell
Date: 01/07/12 15:51:25
Modified: src/docs jbossdocs.xml
Added: src/docs howtoejbdoclet.xml
Log:
added my first snapshot of a sjbdoclet howto
Revision Changes Path
1.21 +4 -2 manual/src/docs/jbossdocs.xml
Index: jbossdocs.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/jbossdocs.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- jbossdocs.xml 2001/07/07 21:56:57 1.20
+++ jbossdocs.xml 2001/07/12 22:51:24 1.21
@@ -34,6 +34,7 @@
<!ENTITY howtovisualagedebug.xml SYSTEM "howtovisualagedebug.xml">
<!ENTITY howto_webcontainer.xml SYSTEM "howto_webcontainer.xml">
<!ENTITY webconfig.xml SYSTEM "webconfig.xml">
+ <!ENTITY howtoejbdoclet.xml SYSTEM "howtoejbdoclet.xml">
]>
<book>
<bookinfo>
@@ -53,7 +54,7 @@
<author>
<firstname>Aaron</firstname>
<surname>Mulder</surname>
- </author>
+ </author>
<email>[EMAIL PROTECTED]</email>
</para>
&jdbc-database.xml;
@@ -76,7 +77,7 @@
&howtotimer.xml;
&howtoj2eedeployer.xml;
&howtojaas.xml;
-&howtojavamail.xml;
+&howtojavamail.xml;
&howtojbuilderdebug.xml;
&howtovisualagedebug.xml;
&howtonetbeansdebug.xml;
@@ -88,5 +89,6 @@
&howtoverifier.xml;
&howtopetstore.xml;
&howto_webcontainer.xml;
+&howtoejbdoclet.xml;
</chapter>
</book>
1.1 manual/src/docs/howtoejbdoclet.xml
Index: howtoejbdoclet.xml
===================================================================
<?xml version = "1.0" encoding = "UTF-8"?>
<!-- brief howto for using ejbdoclet -->
<section id="howtoejbdoclet">
<title>How to use EJBDoclet</title>
<subtitle>In work(!)</subtitle>
<para>Author:
<author>
<firstname>Ingo</firstname>
<surname>Bruell</surname>
</author>
<email>[EMAIL PROTECTED]</email>
</para>
<para>
EJBDoclet is a tool, that makes coding of Enterprise JavaBeans much easier. You
only
have to code <emphasis>one</emphasis> file to generate automaticly the needed
Interfaces and descriptor files. With the usage of <filename>ant</filename>
and the <filename>verifier</filename> it is very easy to produce correct Beans.
</para>
<para>
EJBDoclet is a OpenSource project initiated by Rickard Oberg which stays at
<ulink url="http://sf.net/projects/ejbdoclet";>sourceforge.net</ulink>.
</para>
<section id="ejbdoclet-requirements">
<title>Requirements</title>
<para>
You only need to download the ejbdoclet.jar and put it somwhere in you
classpath. I
think the usage of ant is very recommend (and for now the only way to use
ejbdoclet!).
</para>
</section>
<section id="ejbdoclet-createingthebean">
<title>Creating the Bean as a Template</title>
<para>
EJBDoclet uses JavaDoc Tags and the JavaDoc mechanism to generate the needed
files
out of the "template". Here is an example of an Entity Bean class section:
<programlisting>
/**
* This is an account bean. It is an example of how to use the EJBDoclet tags.
*
* @ejb:entity-cmp <co id="entity-cmp"/>
* @ejb:ejb-name bank/Account
* @ejb:jndi-name ejb/bank/Account
* @ejb:finder Collection findAll() <co id="finder"/>
* @ejb:finder Collection findByOwner(Customer owner)
* @ejb:finder Collection findLargeAccounts(int balance)
* @ejb:env-entry foo 1234 java.lang.Integer <co id="envvar"/>
* @ejb:ejb-ref bank/Customer <co id="ref"/>
* @ejb:security-role-ref admin Administrator
* @ejb:permission Teller
* @ejb:transaction Required
* @ejb:use-soft-locking
*
* JBoss specific <co id="jboss"/>
* @jboss:container-configuration Standard CMP EntityBean
*
* JBoss/JAWS CMP specific <co id="jaws"/>
* @jboss:table-name account
* @jboss:create-table true
* @jboss:remove-table true
* @jboss:tuned-updates true
* @jboss:read-only false
* @jboss:finder-query findLargeAccounts $1 > 1000
* @jboss:finder-order findLargeAccounts balance
*/
public abstract class AccountBean
{
</programlisting>
<calloutlist>
<callout arearefs="entity-cmp">
<para>
Here is specified that this would be an Entity Bean
</para>
</callout>
<callout arearefs="finder">
<para>
Defining the finder methods
</para>
</callout>
<callout arearefs="envvar">
<para>
Easy define envelope vars
</para>
</callout>
<callout arearefs="ref">
<para>
Define references to other beans
</para>
</callout>
<callout arearefs="jboss">
<para>
With these tags you could specify JBoss specific parameters (see
EJBDoclet docu
for more details about the tags).
</para>
</callout>
<callout arearefs="jaws">
<para>
And here you could define JAWS specific parameters (see EJBDoclet docu
for more details about the tags).
</para>
</callout>
</calloutlist>
How you can see it is very easy to create the Beanclass. The JBoss and JAWS
specific
part should only be used, if the standard values of JBoss not fit.
</para>
<para>
Now you need to define the method level tags like this:
<programlisting>
/**
* Create account.
*
* @ejb:permission Administrator <co id="permission"/>
*/
public AccountPK ejbCreate(AccountData data)
throws CreateException
{
setId(data.getId());
setData(data);
return null;
}
/**
* Id of this account.
*
* This is not remote since the primary key can be extracted by other means.
*
* @ejb:pk-field <co id="pk"/>
* @ejb:persistent-field
*
* @jboss:column-name pk
*/
public abstract int getId();
/**
* Id of this account.
*
*/
public abstract void setId(int id);
/**
* Owner of this account.
*
* @ejb:remote-method <co id="remote"/>
* @ejb:persistent-field <co id="persistent"/>
* @ejb:permission Administrator
* @ejb:transaction Supports
*/
public abstract Customer getOwner();
/**
* Owner of this account.
*
*/
public abstract void setOwner(Customer owner);
</programlisting>
<calloutlist>
<callout arearefs="permission">
<para>
With this tag permissions could be defined at method level
</para>
</callout>
<callout arearefs="pk">
<para>
With @ejb:pk-field a primary key field is defined
</para>
</callout>
<callout arearefs="remote">
<para>
@ejb:remote-method defines a remote method
</para>
</callout>
<callout arearefs="persistent">
<para>
And @ejb:persistent-field defines an attribute that should be stored
persistent.
</para>
</callout>
</calloutlist>
</para>
</section>
<section id="ejbdoclet-calling">
<title>Calling EJBDoclet</title>
<para>
For now there is no way to use EJBDoclet without ant, however.
</para>
</section>
<section id="ejbdoclet-ant">
<title>Using EJBDoclet with ant</title>
<para>
To use ant you must download it from the <ulink url="jakarta.apache.org">Apache
Jakarta project</ulink>. For EJBDoclet only the ant.jar is needed.
</para>
<para>
I prefer a project directory structure like the one JBoss uses:
<programlisting>
project
+-build
. +-[...]
+-dist
. +-[...]
+-lib
. +-ant.jar
. +-ejbdoclet.jar
. +-[...]
+-src
. +-resources
. . +-test
. . . +-META-INF
. +-main
. . +-test
. . . +-ejb
. . . . +-AccountBean.java
. . . . +-CustomerBean.java
</programlisting>
Here my ant script (build.xml)that generates the beans interfaces and the
descriptors
and after that it compiles the java files and package them into a jar file:
<programlisting><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
$Revision: 1.1 $ $Date: 2001/07/12 22:51:24 $ $Author: ibruell $
-->
<project name="test" default="main" basedir="../..">
<target name="init">
<property name="Name" value="TEST"/>
<property name="name" value="test"/>
<property name="version" value="1.0"/>
<property name="encoding" value="ISO-8859-1"/>
<property name="typemapping" value="Hypersonic SQL"/>
<property name="datasource" value="java:/DefaultDS"/>
<property name="src.dir" value="${basedir}/src/main"/>
<property name="src.resources" value="${basedir}/src/resources"/>
<property name="etc.dir" value="${basedir}/src/etc"/>
<property name="lib.dir" value="${basedir}/lib"/>
<property name="build.dir" value="${basedir}/build"/>
<property name="build.lib.dir" value="${basedir}/build/lib"/>
<property name="build.deploy.dir" value="${basedir}/build/deploy"/>
<property name="build.classes.dir" value="${basedir}/build/classes"/>
<property name="build.client.dir" value="${basedir}/build/client"/>
<property name="dist.dir" value="dist"/>
<property name="classpath"
value="${lib.dir}/jboss-j2ee.jar;${lib.dir}/jta-spec1_0_1.jar" />
<property name="packages" value="test"/>
<taskdef name="ejbdoclet" classname="ejbdoclet.EJBDocletTask"
classpath="${basedir}/lib/ejbdoclet.jar" />
<!-- <property name="build.compiler" value="jikes"/>-->
</target>
<target name="prepare" depends="init">
<mkdir dir="${build.dir}"/>
</target>
<!-- =================================================================== -->
<!-- Creates the Bean Classes with EJBDoclet -->
<!-- =================================================================== -->
<target name="buildbeans" depends="prepare">
<mkdir dir="${src.resources}/test"/>
<mkdir dir="${src.resources}/test/META-INF"/>
<!-- Call EJBDoclet -->
<ejbdoclet sourcepath="${src.dir}"
destdir="${src.dir}"
packagenames="test"
classpath="${classpath};${basedir}/lib/ejbdoclet.jar"
excludedtags="@version,@author">
<dataobject/>
<remoteinterface/>
<homeinterface/>
<entitypk/>
<entitycmp/>
<deploymentdescriptor xmlencoding="${encoding}"/>
<jboss xmlencoding="${encoding}"
typemapping="${typemapping}"
datasource="${datasource}"/>
</ejbdoclet>
<!-- copy the generated descriptor files in the resources directory -->
<copy file="${src.dir}/ejb-jar.xml" todir="${src.resources}/test/META-INF" />
<copy file="${src.dir}/jboss.xml" todir="${src.resources}/test/META-INF" />
<copy file="${src.dir}/jaws.xml" todir="${src.resources}/test/META-INF" />
<delete>
<fileset dir="${src.dir}" includes="*.xml"/>
</delete>
</target>
<!-- =================================================================== -->
<!-- Compiles the source code -->
<!-- =================================================================== -->
<target name="compile" depends="prepare">
<mkdir dir="${build.classes.dir}"/>
<javac srcdir="${src.dir}"
destdir="${build.classes.dir}"
classpath="${classpath}"
debug="off"
deprecation="off"
optimize="on"
includes="**/*.java"
excludes="**/*.jbx"
/>
</target>
<!-- =================================================================== -->
<!-- Creates the jar archives -->
<!-- =================================================================== -->
<target name="jar" depends="compile">
<mkdir dir="${build.client.dir}"/>
<mkdir dir="${build.lib.dir}"/>
<mkdir dir="${build.deploy.dir}"/>
<!-- Create Bean jar -->
<copy todir="${build.classes.dir}">
<fileset dir="${src.resources}/test" includes="**/*.xml"/>
</copy>
<jar jarfile="${build.deploy.dir}/test.jar"
basedir="${build.classes.dir}"
includes="test/**/*.class,
META-INF/**"
/>
<delete>
<fileset dir="${build.classes.dir}/META-INF" />
</delete>
</target>
<!-- =================================================================== -->
<!-- Verify Beans -->
<!-- =================================================================== -->
<target name="verify" depends="jar">
<java classname="org.jboss.verifier.Main" fork="true" failonerror="true">
<classpath path="${classpath}"/>
<arg value="${build.deploy.dir}/test.jar"/>
</java>
</target>
<!-- =================================================================== -->
<!-- Creates the binary structure -->
<!-- =================================================================== -->
<target name="main" depends="verify">
<mkdir dir="${dist.dir}"/>
<mkdir dir="${dist.dir}/bin"/>
<mkdir dir="${dist.dir}/lib"/>
<mkdir dir="${dist.dir}/deploy"/>
<mkdir dir="${dist.dir}/client"/>
<mkdir dir="${dist.dir}/conf"/>
<mkdir dir="${dist.dir}/images"/>
<copy todir="${dist.dir}/client">
<fileset dir="${build.client.dir}"/>
</copy>
<copy todir="${dist.dir}/lib">
<fileset dir="${build.lib.dir}"/>
</copy>
<copy todir="${dist.dir}/deploy">
<fileset dir="${build.deploy.dir}"/>
</copy>
<copy todir="${dist.dir}/lib">
<fileset dir="${src.resources}/test" includes="*.properties"/>
</copy>
<copy todir="${dist.dir}/conf">
<fileset dir="${etc.dir}/conf"/>
</copy>
<copy file="${src.lib}/connector.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/deploy.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jboss-j2ee.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jboss-client.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jbosssx-client.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jbossmq-client.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jndi.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jnp-client.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jta-spec1_0_1.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/stop.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/jaas.jar" todir="${dist.dir}/client" />
<copy file="${src.lib}/auth.conf" todir="${dist.dir}/client" />
<copy file="${src.lib}/jlfgr-1_0.jar" todir="${dist.dir}/client" />
<copy file="${etc.dir}/conf/jndi.properties" todir="${dist.dir}/client" />
</target>
<!-- =================================================================== -->
<!-- Cleans up generated stuff -->
<!-- =================================================================== -->
<target name="clean" depends="init">
<delete dir="${build.dir}"/>
<delete dir="${dist.dir}"/>
</target>
</project>
]]></programlisting>
</para>
</section>
</section>
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
