aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r786624 - in /websites/production/aries: ./ content/documentation/ariesprogrammingmodel.html content/modules/jpaproject.html
Date Mon, 07 Mar 2011 18:16:11 GMT
Author: timothyjward
Date: Mon Mar  7 18:16:10 2011
New Revision: 786624

Adding Charles Moulliard's JPA documentation contribution

    websites/production/aries/   (props changed)

Propchange: websites/production/aries/
--- svn:mergeinfo (original)
+++ svn:mergeinfo Mon Mar  7 18:16:10 2011
@@ -1 +1 @@

Modified: websites/production/aries/content/documentation/ariesprogrammingmodel.html
--- websites/production/aries/content/documentation/ariesprogrammingmodel.html (original)
+++ websites/production/aries/content/documentation/ariesprogrammingmodel.html Mon Mar  7
18:16:10 2011
@@ -255,6 +255,9 @@
 <p><a href="/modules/transactionsproject.html">Transactions</a></p>
+<p><a href="/modules/jpaproject.html">JPA</a></p>
             <!-- Content -->

Modified: websites/production/aries/content/modules/jpaproject.html
--- websites/production/aries/content/modules/jpaproject.html (original)
+++ websites/production/aries/content/modules/jpaproject.html Mon Mar  7 18:16:10 2011
@@ -242,7 +242,125 @@ persistence for the Blueprint container.
 <p>For more information, check out section "127 JPA Service Specification
 Version 1.0" in the "OSGi Service Platform Enterprise Specification,
 Release 4, Version 4.2" available for public download from the <a href="">OSGi
+<p>Developing an Aries JPA project is very easy and can be achieved with simple steps
described hereafter.</p>
+<h1 id="maven_project_creation">Maven Project Creation</h1>
+<p>The first step consist in to create a maven module and make the following modifications
to allow to deploy
+ it as OSGI bundle on the platform and reference where the persistence XML file must loaded
by the classpath to
+ allow to the JPA container to configure the project accordingly.</p>
+<p>Step 1 : Module</p>
+<p>Every jar deployed on an OSGI platform must be adapted to be conform to OSGI standard.
That means that the maven
+packaging which is defined as the default value must be defined to bundle</p>
+    <groupId></groupId>
+    <artifactId></artifactId>
+    <name>Apache Aries blog sample persistence</name>
+    <packaging>bundle</packaging>
+{code} </p>
+<p>and that you must configure the maven-bundle-plugin (
+to generate the MANIFEST.MF file required by OSGI platform.</p>
+<p>Remark : the modification to be made (packages to be imported or exported depends
on your project setting)</p>
+    <plugin>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>maven-bundle-plugin</artifactId>
+        <configuration>
+            <instructions>
+                <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
+                <Private-Package><em></Private-Package>
+                <Export-Package>!</em></Export-Package>
+            </instructions>
+        </configuration>
+    </plugin>
+<p>To allow the Aries JPA Container to setup your persistence layer (akka : instantiate
the entityFactory with the information
+provided into the persistence.xml file), an additional modification must be made in your
pom.xml file to package this file
+into the META-INF directory</p>
+    <plugin>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>maven-bundle-plugin</artifactId>
+        <configuration>
+            <instructions>
+                <Meta-Persistence>META-INF/persistence.xml</Meta-Persistence>
+                ...
+            </instructions>
+        </configuration>
+    </plugin>
+<p>When this step is done, your pom.xml file is ready to be used to package and install
your bundle into the maven repository
+and next into a OSGI container (Apache Felix, Apache Karaf, Eclipse Equinox)</p>
+<p>Step 2 : Adapt the persistence file</p>
+<p>We will not cover how to define the different parameters of the persistence file
but present you what you should modify to
+deploy it on non J2EE platform, which is the case by definition for OSGI kernel. Curiously,
there is only one think
+to modify and it concerns the access to the datasource. In J2EE world, we use JNDI as registry
mecahnism to registry
+the datasource with a key used to find it from applications. JNDI is not supported like that
in OSGI world but OSGI EE
+specification has made a proposition to provide a similar mechanism that Aries JNDI project
covers (</p>
+<p>To access to the datasource, you must provide within the <jta-data-source>
or <non-jta-data-source> depending if you use a JTA
+transaction manager or not.</p>
+    <persistence-unit name="ReportIncident" transaction-type="JTA">
+        <provider>org.apache.openjpa.persistence.PersistenceProviderImpl</provider></p>
+<div class="codehilite"><pre>    <span class="nt">&lt;jta-data-source&gt;</span>osgi:service/javax.sql.DataSource/(<span
+<p>With J2EE applications, you simply use the jdbc key with the name of the datasource
associated (jdbc/reportincidentdb). As OSGI uses a
+ different mechanism, we must define two parameters, the "osgi:service" wich will allow to
find from the OSGI Service registry (aka proxy)
+ the interface "javax.sql.DataSource" and the name of the service "",
which is a filter property,  with its jndi name associated.</p>
+<p>The other tags of the xml file are defined according to JPA specification</p>
+<p>Step 3 : Define the services and expose them</p>
+<p>The last step consist in to use Annotations and Injection mechanism to let the Aries
JPA container to create the entity Manager
+with the classes of your DAO layer and add Transactional aspect into the methods. This way
of work allows to complety
+embed existing projects into ARIES sphere without modifications</p>
+<p>Here are the modifications to do in the blueprint xml file located under OSGI-INF/blueprint</p>
+<blueprint xmlns=""
+    xmlns:xsi=""
+    xmlns:tx=""
+    xmlns:jpa=""
+    default-activation="lazy"></p>
+<div class="codehilite"><pre><span class="nt">&lt;bean</span>
<span class="na">id=</span><span class="s">&quot;incidentDAO&quot;</span>
+    <span class="na">class=</span><span class="s">&quot;org.apache.camel.example.reportincident.dao.impl.IncidentDAOImpl&quot;</span><span
+    <span class="nt">&lt;tx:transaction</span> <span class="na">method=</span><span
class="s">&quot;*&quot;</span> <span class="na">value=</span><span
class="s">&quot;Required&quot;</span> <span class="nt">/&gt;</span>
+    <span class="nt">&lt;jpa:context</span> <span class="na">property=</span><span
class="s">&quot;entityManager&quot;</span> <span class="na">unitname=</span><span
class="s">&quot;ReportIncident&quot;</span> <span class="nt">/&gt;</span>
+<span class="nt">&lt;/bean&gt;</span>
+<span class="nt">&lt;service</span> <span class="na">ref=</span><span
+    <span class="na">interface=</span><span class="s">&quot;org.apache.camel.example.reportincident.dao.IncidentDAO&quot;</span><span
+<span class="nt">&lt;/service&gt;</span>
+<span class="c">&lt;!-- DataSource Derby --&gt;</span>
+<span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;dataSourceDerby&quot;</span> <span class="na">class=</span><span
class="s">&quot;org.apache.commons.dbcp.BasicDataSource&quot;</span> <span
class="na">destroy-method=</span><span class="s">&quot;close&quot;</span><span
+    <span class="nt">&lt;property</span> <span class="na">name=</span><span
class="s">&quot;driverClassName&quot;</span> <span class="na">value=</span><span
class="s">&quot;org.apache.derby.jdbc.EmbeddedDriver&quot;</span> <span
+    <span class="nt">&lt;property</span> <span class="na">name=</span><span
class="s">&quot;url&quot;</span> <span class="na">value=</span><span
<span class="nt">/&gt;</span>
+    <span class="nt">&lt;property</span> <span class="na">name=</span><span
class="s">&quot;username&quot;</span> <span class="na">value=</span><span
class="s">&quot;&quot;</span> <span class="nt">/&gt;</span>
+    <span class="nt">&lt;property</span> <span class="na">name=</span><span
class="s">&quot;password&quot;</span> <span class="na">value=</span><span
class="s">&quot;&quot;</span> <span class="nt">/&gt;</span>
+<span class="nt">&lt;/bean&gt;</span>
+<span class="c">&lt;!-- Expose DataSource as JNDI reference --&gt;</span>
+<span class="nt">&lt;service</span> <span class="na">ref=</span><span
class="s">&quot;dataSourceDerby&quot;</span> <span class="na">interface=</span><span
class="s">&quot;javax.sql.DataSource&quot;</span><span class="nt">&gt;</span>
+   <span class="nt">&lt;service-properties&gt;</span>
+     <span class="nt">&lt;entry</span> <span class="na">key=</span><span
class="s">&quot;;</span> <span class="na">value=</span><span
class="s">&quot;jdbc/reportincidentdb&quot;</span><span class="nt">/&gt;</span>
+   <span class="nt">&lt;/service-properties&gt;</span>
+<span class="nt">&lt;/service&gt;</span>
+<p>(1) The <tx:transaction> tag allows to inject in your DAO layer the transactional
aspect and using the following symbol
+"*", Aries Transaction manager will create for each method a session to begin / commit or
rollback a transaction in your class
+The scope of the transaction can be defined using the attribute value.
+(2) The JPA context is created using <jpa:context>. The entityManager (which corresponds
to the property of your DAO class) will be
+injected using the property="entityManager". The reference to your unit name (defined in
the persistence.xml file) is passed with the
+ attribute unitname.
+(3) The <service> allows to expose an interface on the OSGI Registry Service using
as key the name of the interface ("javax,sql.Datasource").
+The <service-properties> will let to define a property that we will use to retrieve
the datasource from the registry</p>
+<p>Step 4 : Package the solution</p>
+<p>To package and deploy the solution, execute a "maven clean install" instruction
and deploy your project on you OSGI platform</p></div>
             <!-- Content -->

View raw message