Menu
▾
▴
[Andromdaplugins-cvs] CVS update: cartridges/andromda-ejb3/src/site/axdoc howto7.xml installation.xml howto13.xml howto6.xml howto10.xml howto5.xml howto15.xml project.xml howto18.xml index.xml howto11.xml howto9.xml howto.xml howto14.xml howto16.xml howto1.xml howto19.xml howto4.xml howto3.xml howto2.xml howto8.xml howto21.xml howto12.xml howto20.xml howto17.xml tips.xml
|
From: Vance K. <va...@us...> - 2006-09-14 14:31:34
|
User: vancek
Date: 06/09/14 07:31:31
Added: andromda-ejb3/src/site/axdoc howto7.xml installation.xml
howto13.xml howto6.xml howto10.xml howto5.xml
howto15.xml project.xml howto18.xml index.xml
howto11.xml howto9.xml howto.xml howto14.xml
howto16.xml howto1.xml howto19.xml howto4.xml
howto3.xml howto2.xml howto8.xml howto21.xml
howto12.xml howto20.xml howto17.xml tips.xml
Removed: andromda-ejb3/src/site/xdoc howto.xml howto12.xml
project.xml index.xml howto2.xml installation.xml
howto14.xml howto13.xml howto5.xml howto21.xml
howto1.xml howto18.xml howto6.xml howto3.xml
howto16.xml howto9.xml howto4.xml howto10.xml
howto17.xml howto15.xml howto11.xml howto7.xml
tips.xml howto8.xml howto20.xml howto19.xml
Log:
move xml from xdoc folder to new axdoc folder to be picked up by the andromda doxia xdoc module
Revision Changes Path
1.1 cartridges/andromda-ejb3/src/site/axdoc/howto7.xml
Index: howto7.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<author email="va...@us...">Vance Karimi</author>
<title>AndroMDA - EJB3 - HowTo Exceptions</title>
</properties>
<body>
<section name="Exceptions">
<p>
The EJB3 cartridge provides a similar exception handling process for applications
as the other persistence cartridges.
</p>
<p>
Simply model a class and assign it the <![CDATA[<<ApplicationException>>]]> stereotype or
the <![CDATA[<<UnexpectedException>>]]> stereotype (you will need to enable the Java cartridge
for this to work).
</p>
<p>
A default exception will be generated for all services since the
<code>allowDefaultServiceException</code> namespace property is set to <code>true</code> by
default. A set of default crud exceptions will also be generated and used in manageable service
beans for manageable entities. Please refer to <a href="howto16.html">Manageable Entities</a>
for more information on manageable service exceptions.
</p>
<p class="highlight">
EJB3 entities no longer throw exceptions. Following the session facade pattern, all business
logic should reside in the session bean, therefore, only the session bean should throw
application specific exceptions.
</p>
<p>
The next thing to do is draw a dependency from a <![CDATA[<<Service>>]]> to this exception,
this will make all operations throw this exception.
You may choose to have a single operation throw a specific exception by drawing the dependency
from that operation to the exception.
</p>
<p>
The following example builds on top of our tutorial example and adds the <code>RentalException</code>
application exception which is thrown from all operations of the <code>RentalService</code>
related classes. Notice how the bean class, bean implementation class, interface classes and
delegate class throw this exception from all operations.
</p>
<p>
<img src="images/org/andromda/test/7/a/uml.gif"/>
</p>
<p>
<ul>
<li class="gen">Auto-generated source that does not need manual editing</li>
<li class="impl">Auto-generated source that should be edited manually</li>
<li class="changed">File that is affected by the modifications applied in this section</li>
</ul>
</p>
<p>
<ul>
<li class="gen"><a href="src/org/andromda/test/howto7/a/CarEmbeddable.java"><code>CarEmbeddable.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto7/a/Car.java"><code>Car.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/CarType.java"><code>CarType.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/CarDao.java"><code>CarDao.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/CarDaoBase.java"><code>CarDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto7/a/CarDaoImpl.java"><code>CarDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/CarDaoException.java"><code>CarDaoException.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/Person.java"><code>Person.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/PersonDao.java"><code>PersonDao.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/PersonDaoBase.java"><code>PersonDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto7/a/PersonDaoImpl.java"><code>PersonDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/PersonDaoException.java"><code>PersonDaoException.java</code></a></li>
<li class="impl"><a class="changed" href="src/org/andromda/test/howto7/a/RentalServiceBean.java"><code>RentalServiceBean.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto7/a/RentalServiceRemote.java"><code>RentalServiceRemote.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/ServiceDelegateBase.java"><code>ServiceDelegateBase.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto7/a/RentalServiceDelegate.java"><code>RentalServiceDelegate.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto7/a/RentalServiceBase.java"><code>RentalServiceBase.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto7/a/RentalServiceException.java"><code>RentalServiceException.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto7/a/RentalException.java"><code>RentalException.java</code></a></li>
</ul>
</p>
</section>
<section name="Next">
<p>
The next section covers the declarative security handling with JBossSX, click
<a href="howto8.html">here</a> to go to that section.
</p>
</section>
</body>
</document>
1.1 cartridges/andromda-ejb3/src/site/axdoc/installation.xml
Index: installation.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<author email="va...@us...">Vance Karimi</author>
<title>AndroMDA - EJB3 - Installation & Configuration</title>
</properties>
<body>
<section name="Installation">
<p>
Since the EJB3 cartridge is not part of the base AndroMDA package, you need to know a
few things to get started with the cartridge. This installation and configuration
guide should provide enough information to get you started.
</p>
<a name="Requirements"/>
<subsection name="Requirements">
<p>
You must have the latest Maven (currently 2.0.4) installed and configured.
You can install Maven
<a href="http://maven.apache.org/download.html#Installation">here</a>.
</p>
<p class="highlight">
If you want to build the site docs, you need to download the latest Maven 2.0.x source
from https://svn.apache.org/repos/asf/maven/components/branches/maven-2.0.x and follow
the instructions to build, assemble and set your M2_HOME and PATH variables.
</p>
<p>
You need to have an instance of AndroMDA 3.2. At the time of writing this, 3.2 RC1
was released but the latest 3.2-SNAPSHOT from CVS contains updates to the project generator
and site plugin; this is more suitable to use with the EJB3 cartridge. Follow the anonymous
CVS access at <a href="http://sourceforge.net/cvs/?group_id=73047">AndroMDA project</a> to
checkout and build the latest <b>andromda-all</b> source.
</p>
</subsection>
<a name="Getting_the_Cartridge"/>
<subsection name="Getting the Cartridge">
<p>
Once you have met the requirements above, checkout the latest EJB3 cartridge from
CVS HEAD.
You have two options:
<ul>
<li>
Follow the anonymous CVS access at
<a href="http://sourceforge.net/cvs/?group_id=154568">andromdaplugins project</a>
on SourceForge to checkout the latest <b>andromda-plugins</b> module from
<code>HEAD</code>.
</li>
<li>
If you are using an IDE like Eclipse, open your CVS repository exploring perspective,
create a new repository with connection type (pserver), username (anonymous),
password(<i>blank</i>) host (andromdaplugins.cvs.sourceforge.net) and repository path
(/cvsroot/andromdaplugins). Once connected, expand HEAD and check out
<code>andromda-plugins</code>.
</li>
</ul>
Note that this will check out all cartridges and plugins
which are not relevant to the EJB3 cartridge, but will ease the your build process.
</p>
</subsection>
<a name="Building_the_Cartridge"/>
<subsection name="Building the Cartridge">
<p>
Once you have checked out the <code>andromda-plugins</code> project, you can simply build
the <b>andromda-ejb3</b> catridge in <code>andromda-plugins/cartridges/andromda-ejb3</code>
by running <i>mvn</i> in the latter location.
</p>
</subsection>
<a name="Building_Reports"/>
<subsection name="Building Reports">
<p>
To build the EJB3 cartridge site documentation requires a few extra Maven 2 plugins
to be downloaded from the Maven 2 sandbox in SVN. The
<a href="http://maven.apache.org/guides/development/guide-building-m2.html">Maven build</a>
documentation will give you some information on how to access their SVN.
</p>
<p>
You will need to check out the following plugins from Maven <b>sandbox</b>.
<ul>
<li>maven-changes-plugin</li>
<li>maven-changelog-plugin</li>
</ul>
Once you have built them (mvn install), these plugins will reside in your local repo.
</p>
<p>
In adopting the existing AndroMDA site format for the documentation, the Maven Doxia
plugin needs a patch to be applied. You can check out <b>doxia-1.0-alpha-8</b>
from Maven SVN and apply the patch <a href="http://jira.codehaus.org/browse/MNG-545">here</a>.
It is not critical to apply this patch, but if it's not applied, the generated XHTML will
not be formated correctly but still acceptable.
</p>
<p>
All other require plugins will be downloaded to your local repo if they don't already
exist.
</p>
<p>
You can download the source examples used in the howto for all sections
<a href="HowToModel-src.zip">here</a> and extract to the target/site folder of the
andromda-ejb3 plugin.
</p>
</subsection>
</section>
<section name="Next">
<p>
Before starting with the EJB3 howtos, find out how to generate your
<a href="project.html">EJB 3.0 project</a>.
</p>
</section>
</body>
</document>
1.1 cartridges/andromda-ejb3/src/site/axdoc/howto13.xml
Index: howto13.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<author email="va...@us...">Vance Karimi</author>
<title>AndroMDA - EJB3 - Interceptors</title>
</properties>
<body>
<section name="Interceptor">
<p>
Adding custom written interceptors is very easy using the EJB3 cartridge. The following sections
will provide you with enough detail to add your custom interceptors to session and
message-driven beans. It discusses default, class and method interceptors.
</p>
<p>
All interceptors are configured through the ejb-jar deployment descriptor. The EJB3 cartridges
does NOT use annotations to define interceptors and their exclusions.
</p>
<p>
The following example shows how to model a default interceptor as well as 2 class level
interceptors for the <code>RentalService</code> bean. Method level interceptor are
modelled in the same fashion, but a dependency is drawn from the session bean method rather than
the actual session bean class.
</p>
<p>
<img src="images/org/andromda/test/13/a/uml.gif"/>
</p>
<p>
<ul>
<li class="gen">Auto-generated source that does not need manual editing</li>
<li class="impl">Auto-generated source that should be edited manually</li>
<li class="changed">File that is affected by the modifications applied in this section</li>
</ul>
</p>
<p>
<ul>
<li class="gen"><a href="src/org/andromda/test/howto13/a/CarEmbeddable.java"><code>CarEmbeddable.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto13/a/Car.java"><code>Car.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/CarType.java"><code>CarType.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/CarDao.java"><code>CarDao.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/CarDaoBase.java"><code>CarDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto13/a/CarDaoImpl.java"><code>CarDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/CarDaoException.java"><code>CarDaoException.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/Person.java"><code>Person.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/PersonDao.java"><code>PersonDao.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/PersonDaoBase.java"><code>PersonDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto13/a/PersonDaoImpl.java"><code>PersonDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/PersonDaoException.java"><code>PersonDaoException.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/ServiceDelegateBase.java"><code>ServiceDelegateBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto13/a/RentalServiceBean.java"><code>RentalServiceBean.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/RentalServiceRemote.java"><code>RentalServiceRemote.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/RentalServiceDelegate.java"><code>RentalServiceDelegate.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/RentalServiceBase.java"><code>RentalServiceBase.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/RentalServiceException.java"><code>RentalServiceException.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/RentalException.java"><code>RentalException.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto13/a/ejb-jar.xml"><code>ejb-jar.xml</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto13/a/jboss.xml"><code>jboss.xml</code></a></li>
<li class="impl"><a class="changed" href="src/org/andromda/test/howto13/a/DefaultInterceptor.java"><code>DefaultInterceptor.java</code></a></li>
<li class="impl"><a class="changed" href="src/org/andromda/test/howto13/a/LogInterceptor.java"><code>LogInterceptor.java</code></a></li>
<li class="impl"><a class="changed" href="src/org/andromda/test/howto13/a/AdminCheckerInterceptor.java"><code>AdminCheckerInterceptor.java</code></a></li>
</ul>
</p>
<a name="Default_Interceptors"/>
<subsection name="Default Interceptor">
<p>
A default interceptor is invoked any time a business method of any bean within that
deployment is invoked, unless default interceptors have been excluded on beans or
business methods of beans.
</p>
<p>
To define a default interceptor for your deployment, model the standard
<![CDATA[<<Interceptor>>]]> stereotype on a class and specify the
<code>@andromda.service.interceptor.default</code> tagged value as true on this class.
Since this interceptor is invoked
for all business methods of all beans, you do not need to model any dependencies on it.
The cartridge will generate the class with the necessary interceptor operation and
corresponding annotations within the interceptor class. It will also add the
<code>interceptor-binding</code> attribute to the <code>assembly-descriptor</code> element
of the ejb-jar deployment descriptor.
</p>
<p>
You can model as many default interceptor as you require, but at this stage, the ordering
of default interceptors is not guaranteed.
</p>
</subsection>
<a name="Class_Level_Interceptor"/>
<subsection name="Class Level Interceptor">
<p>
Class level interceptors are invoked when business methods of the modelled class are invoked,
unless class level interceptors have been excluded on business methods.
</p>
<p>
To define a class level interceptor, model the <![CDATA[<<Interceptor>>]]> stereotype on
a class. You must model a dependency from a source bean to this target class level interceptor
so that the cartridge knows to configure this interceptor at the class level in the ejb-jar
deployment descriptor.
</p>
<p>
If you would like to define multiple class level interceptors, then to guarantee the ordering
in which these interceptors are invoked, you must draw a dependency from the first interceptor
to the second interceptor and so forth. This will chain the interceptors and allow the
cartridge to configure them correctly in the ejb-jar deployment descriptor.
</p>
</subsection>
<a name="Method_Level_Interceptor"/>
<subsection name="Method Level Interceptor">
<p>
Method level interceptors are very much similar to class level interceptors, but they are
bound to a specific business method within a bean. This means that they are only invoked
when the modelled business methods of the bean are invoked.
</p>
<p>
To define a method level interceptor, model the <![CDATA[<<Interceptor>>]]> stereotype on
a class. You must model a dependency from a bean method to this target method level interceptor
so that the cartridge knows to configure this interceptor at the method level in the ejb-jar
deployment descriptor.
</p>
<p>
Chaining method level interceptors is exactly the same process as for class level interceptors.
</p>
</subsection>
<a name="Interceptor_Ordering"/>
<subsection name="Interceptor Ordering">
<p>
The following shows the ordering of default, class and method level interceptors.
</p>
<p>
<ul>
<li>Default Interceptors - Invoked before all other interceptors</li>
<li>
Class Level Interceptors - Invoked in the chain after default interceptors and before
method level interceptors.
</li>
<li>Method Level Interceptors - Invoked in the chain after all class level interceptors.</li>
</ul>
</p>
<p>
The above are the ordering for externally defined interceptors. If you define
class interceptor methods within your bean, then these are the last interceptors
to be invoked.
</p>
</subsection>
<a name="Interceptor_Exclusion"/>
<subsection name="Interceptor Exclusions">
<p>
The EJB3 cartridge allows you to exclude default interceptors for beans and bean methods.
It also allows you to exclude class level interceptors for bean methods.
</p>
<p>
To exclude the default interceptors, model the
<code>@andromda.service.interceptor.excludeDefault</code> tagged value. If this is applied to
a bean class, then the interceptor will be ignored for all methods of the bean class. If
it is modelled on a business method of a bean, then invocation of that business method
will NOT trigger invocation of the defined default interceptors.
</p>
<p>
To exclude class level interceptors, model the
<code>@andromda.service.interceptor.excludeClass</code> tagged value on business method
of beans. This will prevent the container from invoking the defined class level interceptor
when the associated bean method is invoked.
</p>
</subsection>
<a name="Interceptor_Tips"/>
<subsection name="Interceptor Tips">
<p>
In situations where you have an inheritance hierarchy, interceptor methods from the super
class are always invoked first. The exception to this rule is the case where the interceptor
has been overridden, regardless of whether the overriding method is defined as an
interceptor.
</p>
<p>
Once the interceptors have been generated, they will never be overwritten. This way, you
can add your implementation for the interceptor and call <code>InvocationContext.proceed()</code>
to continue to call the next interceptor.
</p>
<p>
Similar to bean classes, interceptor classes enjoy the benefits of dependency injection
in much the same way.
You can inject resources using the <code>@Resource</code> annotation or an
entity manager using the <code>@PersistenceContext</code> annotation.
</p>
</subsection>
</section>
<section name="Next">
<p>
For usage of lifecycle callbacks in entity, session and message-driven beans
click <a href="howto14.html">here</a>.
</p>
</section>
</body>
</document>
1.1 cartridges/andromda-ejb3/src/site/axdoc/howto6.xml
Index: howto6.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<author email="va...@an...">Vance Karimi</author>
<title>AndroMDA - HowTo - Queries</title>
</properties>
<body>
<section name="Queries">
<p>
All enterprise applications need to perform operations on the underlying datasource, and EJB3
supports this with <b>EJB Query Language</b> or <b>native query</b> support.
</p>
<p>
Most of what you are going to read here is very similar to the Hibernate cartridge support
for queries. There are a few differences which will be further discussed.
</p>
<p>
UML allows you to specify queries, be it in a more generic language. For this purpose OCL can
be used, which supports <code>body</code> constructs since OCL 2.0. Although you can choose
to override any generated query using a tagged value specifying your custom query, it is
strongly recommended to use OCL since this will guarantee your code to remain portable over different
technologies. If you don't want to get to know OCL and have no problem sticking to EJBQL
then you might consider using tagged values instead.
</p>
<p>
Finder methods require the <code>query flag</code> to be set, usually operations with this flag have
the <code>commercial at</code> symbol '@' in front of their name when displayed in diagrams. Make sure
you model the operation in <em>classifier scope</em>, in diagrams this will show them as underlined and
check the <code>Query</code> checkbox for the operation to indicate this is a finder method. By
enabling this checkbox, the '@' symbol will appear in front of the operation in your model.
</p>
<p>
Remember that classifier scoped operations go into the DAO while instance scoped operations go into the
entity's implementation class (they are considered to be business operations).
</p>
<p>
The documentation discussing the modeling of queries in UML is found here:
<a href="../andromda-ocl-query-library/modeling.html">Query Translation-Library Modeling</a>.
The tagged value overriding queries using EJB QL directly is found here:
<a href="../profile.html#@andromda_ejb_query">@andromda.ejb.query</a>.
</p>
<p>
<img src="images/org/andromda/test/6/a/uml.gif"/>
</p>
<p>
<ul>
<li class="gen">Auto-generated source that does not need manual editing</li>
<li class="impl">Auto-generated source that should be edited manually</li>
<li class="changed">File that is affected by the modifications applied in this section</li>
</ul>
</p>
<p>
<ul>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto6/a/CarEmbeddable.java"><code>CarEmbeddable.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto6/a/Car.java"><code>Car.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/CarType.java"><code>CarType.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/CarDetails.java"><code>CarDetails.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/CarListItem.java"><code>CarListItem.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto6/a/CarDao.java"><code>CarDao.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto6/a/CarDaoBase.java"><code>CarDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto6/a/CarDaoImpl.java"><code>CarDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/CarDaoException.java"><code>CarDaoException.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto6/a/PersonEmbeddable.java"><code>PersonEmbeddable.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto6/a/Person.java"><code>Person.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto6/a/PersonDao.java"><code>PersonDao.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto6/a/PersonDaoBase.java"><code>PersonDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto6/a/PersonDaoImpl.java"><code>PersonDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/PersonDaoException.java"><code>PersonDaoException.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto6/a/RentalServiceBean.java"><code>RentalServiceBean.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/RentalServiceRemote.java"><code>RentalServiceRemote.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/ServiceDelegateBase.java"><code>ServiceDelegateBase.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/RentalServiceDelegate.java"><code>RentalServiceDelegate.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/RentalServiceBase.java"><code>RentalServiceBase.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto6/a/RentalServiceException.java"><code>RentalServiceException.java</code></a></li>
</ul>
</p>
<p>
If you look at the <code>Car</code> and <code>Person</code> Java entities, you will notice that
a set of <code>@NamedQuery</code> annotations define the named queries for each entity. By default
the <code>entityGenericFinders</code> namespace property is enabled, therefore a <code>findAll</code>
named query will always exist for every entity. Other named queries are either defined using AndroMDA's
default creation or OCL.
</p>
<p>
It is important to note that until the ORM xml descriptor is available, named queries are defined
in the class with the <code>@Entity</code> annotation. This has a drawback for entities with
instance scoped operations where a mapped superclass contains most of the persistence mapping
annotations, but the implementation class contains the <code>@Entity</code> and named query(ies)
annotations. In this example, the <code>Car</code> entity is an example of this case. Because
the <code>isRented()</code> operation is an instance scoped method, the named queries are defined
in the <code>Car.java</code> implementation which extends the <code>CarEmbeddable.java</code> class.
As a result, adding new finder methods to the <code>Car</code> entity will not generate these
named query definitions since the implementation class is not overriden. This is not the case for
the <code>Person</code> entity since it is always regenerated.
</p>
<p>
The DAO base classes provide the ability to use the named queries declared in the entities
or by specifying the query manually. By default, unless you manually specify the query string,
the DAO finder methods will use named queries, so keep this in mind when performing dynamic
queries. The <code>loadAll</code> DAO operation also used the generic finder method
named query defintion.
</p>
<p>
Currently, named queries are defined in two ways. Either you let AndroMDA auto create
your basic EJB QL for you, or use OCL to configure your query. Named queries will NOT be
defined if you use the <ocde>@andromda.ejb.query</ocde> tagged value. It would be suggested
that a new tagged value i.e <code>@andromda.ejb.query.named</code> be added to manually
set the named query, but OCL is still the preferred solution.
</p>
</section>
<section name="Nice to know">
<subsection name="A few supported query features">
<p>
</p>
</subsection>
<subsection name="Overriding queries">
<p>
It's allowed to override queries such as finders in the DAO, just override the appropriate method
in an entity's DAO implementation class. What follows is an example of a code snippet
overriding a generated EJBQL query (example taken from a ficticous <code>UserDAOImpl</code> class):
<source language="java"><![CDATA[
public List findActiveUsers(int transform)
{
// the next query is user-specified and overrides the one generated in super.findActiveUsers(int transform)
return super.findActiveUsers(transform, "from Users as user where user.exitDate is null");
}
]]></source>
</p>
<p>
You might consider doing this when you think the generated query is not performant enough, or
when you need to do something which is so complex the OCL translation can't properly handle it.
</p>
</subsection>
</section>
<section name="Next">
<p>
The next section will cover the modeling of exceptions, click
<a href="howto7.html">here</a> to go to that section.
</p>
</section>
</body>
</document>
1.1 cartridges/andromda-ejb3/src/site/axdoc/howto10.xml
Index: howto10.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<author email="va...@us...">Vance Karimi</author>
<title>AndroMDA - EJB3 - Message Driven Beans</title>
</properties>
<body>
<section name="Message Driven Beans">
<p>
A message driven bean is simply an 'asynchronous message consumer'. It is invoked by the container
when a message is received at the destination that the MDB services. There is no client side
visibility or conversational state with MDBs and the lifetime of the MDB instance is totally
controlled by the container.
</p>
<p>
The EJB 3.0 spec states:
<i>
<p>
A message-driven bean instance has no state for a specific client. However, the instance
variables of the message-driven bean instance can contain state accross the handling of
client messages. Examples of such state include an open database connection and a reference
to an enterprise bean.
</p>
<p>
A further goal of the message-driven bean model is to allow for the concurrent processing of
a stream of messages by means of container-provided pooling of message-driven bean
instances.
</p>
</i>
</p>
<p>
Like a session bean, the EJB3 cartridge generates a message driven bean class which should NOT be
modified manually and a corresponding implementation class that requires the business logic
for message processing. The MDB class contains all the necessary annotations. The MDB
implementation class extends the MDB class.
</p>
<p>
Currently, EJB3 cartridge does not generate the <code>@MessageDriven</code> metadata annotation in the
MDB class. Instead, the <code>ejb-jar.xml</code> and <code>jboss.xml</code> deployment
descriptors contain the necessary metadata, due to the design of separation by inheritance where the
business logic is separated in the subclass from the auto-generated code in the base class.
</p>
<p>
The <code>abstract</code> message-driven bean class defines all the business methods as
abstract. The message-driven bean implementation class requires the business method implementations.
The implementation class also contains the implementation of the <code>onMessage</code>
callback in the <code>MessageListener</code>.
</p>
<p>
The following examples illustrates how the EJB3 cartridge will generate the message-drive bean
related classes and the required references in the session bean classes. The
<code>PaymentProcessor</code> is the message-driven bean that is servicing the <code>Queue</code>
which is located at <code>queue/howtomodel/howto10a</code>. The tagged values used are
explained further down.
</p>
<p>
<img src="images/org/andromda/test/10/a/uml.gif"/>
</p>
<p>
<ul>
<li class="gen">Auto-generated source that does not need manual editing</li>
<li class="impl">Auto-generated source that should be edited manually</li>
<li class="changed">File that is affected by the modifications applied in this section</li>
</ul>
</p>
<p>
<ul>
<li class="gen"><a href="src/org/andromda/test/howto10/a/CarEmbeddable.java"><code>CarEmbeddable.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto10/a/Car.java"><code>Car.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/CarType.java"><code>CarType.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/CarDao.java"><code>CarDao.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/CarDaoBase.java"><code>CarDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto10/a/CarDaoImpl.java"><code>CarDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/CarDaoException.java"><code>CarDaoException.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/Person.java"><code>Person.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/PersonDao.java"><code>PersonDao.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/PersonDaoBase.java"><code>PersonDaoBase.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto10/a/PersonDaoImpl.java"><code>PersonDaoImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/PersonDaoException.java"><code>PersonDaoException.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/ServiceDelegateBase.java"><code>ServiceDelegateBase.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/RentalServiceBase.java"><code>RentalServiceBase.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/RentalServiceRemote.java"><code>RentalServiceRemote.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/RentalServiceDelegate.java"><code>RentalServiceDelegate.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto10/a/RentalServiceBean.java"><code>RentalServiceBeanImpl.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/RentalServiceException.java"><code>RentalServiceException.java</code></a></li>
<li class="gen"><a href="src/org/andromda/test/howto10/a/RentalException.java"><code>RentalException.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/PaymentServiceBase.java"><code>PaymentServiceBase.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/PaymentServiceRemote.java"><code>PaymentServiceRemote.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/PaymentServiceDelegate.java"><code>PaymentServiceDelegate.java</code></a></li>
<li class="impl"><a class="changed" href="src/org/andromda/test/howto10/a/PaymentServiceBean.java"><code>PaymentServiceBean.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/PaymentServiceException.java"><code>PaymentServiceException.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/PaymentProcessorMDBBean.java"><code>PaymentProcessorMDBBean.java</code></a></li>
<li class="impl"><a class="changed" href="src/org/andromda/test/howto10/a/PaymentProcessorMDBBeanImpl.java"><code>PaymentProcessorMDBBeanImpl.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/ejb-jar.xml"><code>ejb-jar.xml</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto10/a/jboss.xml"><code>jboss.xml</code></a></li>
</ul>
</p>
<p>
The dependency from the <code>RentalService</code> session bean to the <code>PaymentProcessor</code>
MDB injects the required connection factory and destination objects into the session bean.
Similarly, the dependency from the <code>PaymentProcessor</code> MDB to the <code>PaymentService</code>
session bean injects the EJB instance of the session bean into the MDB.
</p>
<a name="Destination_Type"/>
<subsection name="Destination Type">
<p>
For every message-driven bean, you <i>MUST</i> specify the destination type for the servicing
MDB. This is achieved by simply modelling the <code>@andromda.ejb.mdb.destination.type</code>
tagged value on the MDB class. Your options are:
<ul>
<li>
<p>
<b>javax.jms.Queue</b>
</p>
<p>
If you have only ONE listener on a destination, then you specify the destination
type as a Queue.
</p>
</li>
<li>
<p>
<b>javax.jms.Topic</b>
</p>
<p>
If you have multiple subscribers on a destination, then you specify the destination
as a Topic.
</p>
</li>
</ul>
</p>
</subsection>
<a name="Destination"/>
<subsection name="Destination">
<p>
For every message-driven bean, you <i>MUST</i> specify the destination queue or topic name
that the MDB is associated with. This is achieved by modelling the
<code>@andromda.ejb.mdb.destination</code> tagged value.
</p>
</subsection>
<a name="Acknowledge_Mode"/>
<subsection name="Acknowledge Mode">
<p>
To specify the acknowledge mode for a JMS message driven bean, simply model the
<code>@andromda.ejb.mdb.acknowledge.mode</code> tagged value on the class.
This only needs to be specified if <code>DUPS_OK_ACKNOWLEDGE</code> mode is required since
the default is <code>AUTO_ACKNOWLEDGE</code>.
</p>
</subsection>
<a name="Message_Selector"/>
<subsection name="Message Selector">
<p>
By specifying a message selector constraint, you can limit the messages that a message-driven
bean is configured to received. To set a message selector, simply model the
<code>@andromda.ejb.mdb.selector</code> tagged value on the MDB class.
</p>
</subsection>
<a name="Subscription_Durability"/>
<subsection name="Subscription Durability">
<p>
You can specify the message-driven bean subscription durability by modelling the
<code>@andromda.ejb.mdb.subscription.durability</code> tagged value on the MDB class.
Queues are always durable by default. The durability only needs to specified on Topics.
By default, Topics are <b>non-durable</b>.
Your options are:
<ul>
<li>Durable</li>
<li>NonDurable</li>
</ul>
</p>
</subsection>
<a name="Listener_Interceptor"/>
<subsection name="Listener Interceptor">
<p>
Message driven beans have lifecycle callback interceptor methods or regular interceptors which
can be defined in a separate interceptor class using the EJB3 cartridge. To find out more
information on interceptors, click on <a href="howto13.html">interceptors</a>.
To find out more information on lifecycle callbacks, click on
<a href="howto14.html">lifecycle callbacks</a>.
</p>
</subsection>
<a name="Transaction_Context"/>
<subsection name="Transaction Context">
<p>
Like session beans, message-driven beans can use container-managed or bean-managed
transaction demarcation. By default and if unspecified, the container-managed transaction
demarcation is adopted. However, you can specify bean-managed transaction demarcation by
modelling the <code>@andromda.ejb.transaction.management</code> tagged value to
<code>BEAN</code> on the message-driven class.
</p>
<p>
If the MDB is specified using container-managed transaction demarcation, you can specify
the transaction attribute type to either:
<ul>
<li>REQUIRED</li>
<li>NOT_SUPPORTED</li>
</ul>
By default, the EJB3 cartridge will generate the <code>@TransactionAttribute</code>
annotation, setting the attribute type to <code>REQUIRED</code>. To override this default
value, you can model the <code>@andromda.ejb.transaction.type</code> tagged value on
the MDB class.
</p>
</subsection>
<a name="Security"/>
<subsection name="Security">
<p>
Because message-driven beans lifecycle is totally controlled by the container, a client is
NOT calling the <code>onMessage</code> method directly. Therefore, the security identity
for the execution of methods in the MDB is controlled via the <code>@RunAs</code>
annotation. This can easily be set by following the security howto
<a href="howto8.html#Modelling">here</a>.
</p>
</subsection>
<a name="Message_Driven_Context"/>
<subsection name="Message Driven Context">
The EJB3 cartridge injects the <code>MessageDrivenContext</code> into every MDB using the
<code>@Resource</code> annotation by default. The <code>MessageDrivenContext</code> instance,
named <code>context</code>, provides the following methods:
<ul>
<li>setRollbackOnly</li>
<li>getRollbackOnly</li>
<li>getUserTransaction</li>
<li>getTimerService</li>
<li>getCallerPrincipal</li>
<li>isCallerInRole</li>
<li>getEJBHome</li>
<li>getEJBLocalHome</li>
<li>lookup</li>
</ul>
</subsection>
<a name="Session_Bean_Injection"/>
<subsection name="Session Bean Injection">
To inject a session bean into the MDB, model a dependency from the MDB to the destination
session bean. As a result, the <code>EJB</code> annotation will be generation on the
attribute declaring the injected destination session bean.
</subsection>
<a name="Resource_Injection"/>
<subsection name="Resource Injections">
<p>
To inject an environment entry resource value, model an attribute with classifer scope
and set the attribute stereotype to <![CDATA[<<EnvEntry>>]]>. The environment
entries will be defined in the MDB class and configured in the ejb-jar.xml
deployment descriptor.
You must define a default value for these attributes in the model. Refer to
<a href="howto11.html">Environment Entry Injections</a> for further information.
</p>
</subsection>
<a name="Singleton_MDB"/>
<subsection name="Singleton MDB">
<p>
In some circumstance, you need to configure your MDB to maintain a max pool size of 1
such that you have a singleton message driven bean. This can be achieved via
the <a href="profile.html#@andromda.ejb.mdb.pool.size.max">maximum pool size</a>
tagged value which is modelled on the MDB.
</p>
<p>
You also have the option of configuring the
<a href="profile.html#@andromda.ejb.mdb.pool.size.min">minimum pool size</a>
of the MDB.
</p>
<p>
Both tagged values will add the appropriate activation config property to the
<code>ejb-jar.xml</code> deployment descriptor.
</p>
</subsection>
<a name="MQ_Destinations_Descriptor"/>
<subsection name="MQ Destinations Descriptor">
<p>
The EJB3 cartridge will create the default MQ destinations XML descriptor which can be
hot deployed to the JBoss container for creating your queues or topics. The following
is a very basic example with a single queue mbean definition.
<source language="xml"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<server>
<mbean code="org.jboss.mq.server.jmx.Queue"
name="jboss.mq.destination:service=Queue,name=EmailSenderMDBBean">
<depends optional-attribute-name="DestinationManager">jboss.mq:service=DestinationManager</depends>
<attribute name="JNDIName">queue/emailSender</attribute>
</mbean>
<!-- jboss mq destinations merge-point -->
</server>
]]></source>
This file is created in your project/app/target directory and will be named something like
<code>{PROJECT_NAME}-mq-destinations-service.xml</code>. Just deploy this to your JBoss
deploy directory before deploying your application EAR.
</p>
</subsection>
</section>
<section name="Next">
<p>
To find out how to inject environment entries to session and message driven beans, click
<a href="howto11.html">here</a>.
</p>
</section>
</body>
</document>
1.1 cartridges/andromda-ejb3/src/site/axdoc/howto5.xml
Index: howto5.xml
===================================================================
<?xml version="1.0" encoding="iso-8859-1"?>
<document>
<properties>
<author email="va...@us...">Vance Karimi</author>
<title>AndroMDA - EJB3 - HowTo Enumerations</title>
</properties>
<body>
<section name="Enumerations">
<p>
You might have noticed the attribute named <code>carType</code> in the <code>Car</code> entity. It is
is of type <code>String</code>, while in fact it makes more sense to restrict the set of possible
values for this attribute. This can be achieved using <i>type-safe enumerations</i>.
This is the topic discussed on this page.
</p>
<p>
Type-safe enumerations are modelled by means of a regular class, only this time you need
to use the <![CDATA[<<Enumeration>>]]> stereotype. All attributes on such an enumeration will
be known as enumeration literals, they will assume the default values you assign to the attributes,
or the name of the attribute if the default value is missing.
</p>
<p>
In the EJB3 cartridge, enumerations are <i>NOT</i> persisted behind the scenes, unlike the
Hibernate framework, however we can still use these enumeration types for entity attributes.
</p>
<p>
In the next picture we have replaced the type of the <code>type</code> attribute in the
<code>Car</code> entity from <code>datatype::String</code> to
<code>org.andromda.test.howto5.a.CarType</code> and set the enumeration type to <code>STRING</code>
(default being <code>ORDINAL</code>).
</p>
<p>
<img src="images/org/andromda/test/5/a/uml.gif"/>
</p>
<p>
<ul>
<li class="gen">Auto-generated source that does not need manual editing</li>
<li class="impl">Auto-generated source that should be edited manually</li>
<li class="changed">File that is affected by the modifications applied in this section</li>
</ul>
</p>
<p>
<ul>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto5/a/CarEmbeddable.java"><code>CarEmbeddable.java</code></a></li>
<li class="impl"><a href="src/org/andromda/test/howto5/a/Car.java"><code>Car.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto5/a/CarType.java"><code>CarType.java</code></a></li>
<li class="gen"><a class="changed" href="src/org/andromda/test/howto5/a/CarDao.java"><code>CarDao.java</code></a...
[truncated message content] |
