aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From timothyjw...@apache.org
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

Log:
Adding Charles Moulliard's JPA documentation contribution

Modified:
    websites/production/aries/   (props changed)
    websites/production/aries/content/documentation/ariesprogrammingmodel.html
    websites/production/aries/content/modules/jpaproject.html

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

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 @@
 <li>
 <p><a href="/modules/transactionsproject.html">Transactions</a></p>
 </li>
+<li>
+<p><a href="/modules/jpaproject.html">JPA</a></p>
+</li>
 </ol></div>
             <!-- Content -->
           </td>

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="http://www.osgi.org/Download/Release4V42">OSGi
Alliance</a>
-.</p></div>
+.</p>
+<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>
+<p>{code}
+    <groupId>org.apache.aries.samples.blog</groupId>
+    <artifactId>org.apache.aries.samples.blog.persistence.jpa</artifactId>
+    <name>Apache Aries blog sample persistence</name>
+    <packaging>bundle</packaging>
+{code} </p>
+<p>and that you must configure the maven-bundle-plugin (http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html)
+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>
+<p>{code}
+    <plugin>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>maven-bundle-plugin</artifactId>
+        <configuration>
+            <instructions>
+                <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
+                <Private-Package>org.apache.aries.samples.blog.persistence.jpa.<em></Private-Package>
+                <Export-Package>!org.apache.aries.samples.blog.persistence.jpa.</em></Export-Package>
+            </instructions>
+        </configuration>
+    </plugin>
+{code}</p>
+<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>
+<p>{code}
+    <plugin>
+        <groupId>org.apache.felix</groupId>
+        <artifactId>maven-bundle-plugin</artifactId>
+        <configuration>
+            <instructions>
+                <Meta-Persistence>META-INF/persistence.xml</Meta-Persistence>
+                ...
+            </instructions>
+        </configuration>
+    </plugin>
+{code}</p>
+<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 (http://aries.apache.org/modules/jndiproject.html).</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>
+<p>{code}
+    <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/(osgi.jndi.service.name=jdbc/reportincidentdb)<span
class="nt">&lt;/jta-data-source&gt;</span>
+</pre></div>
+
+
+<p>{code}</p>
+<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 "osgi.jndi.service.name",
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>
+<p>{code}
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.0.0"
+    xmlns:jpa="http://aries.apache.org/xmlns/jpa/v1.0.0"
+    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
class="nt">&gt;</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>
(1)
+    <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>
(2)
+<span class="nt">&lt;/bean&gt;</span>
+
+<span class="nt">&lt;service</span> <span class="na">ref=</span><span
class="s">&quot;incidentDAO&quot;</span>
+    <span class="na">interface=</span><span class="s">&quot;org.apache.camel.example.reportincident.dao.IncidentDAO&quot;</span><span
class="nt">&gt;</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
class="nt">&gt;</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
class="nt">/&gt;</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
class="s">&quot;jdbc:derby:/temp/reportincident;create=true&quot;</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;osgi.jndi.service.name&quot;</span> <span class="na">value=</span><span
class="s">&quot;jdbc/reportincidentdb&quot;</span><span class="nt">/&gt;</span>
(3)
+   <span class="nt">&lt;/service-properties&gt;</span>
+<span class="nt">&lt;/service&gt;</span>
+</pre></div>
+
+
+<p></blueprint>
+{code}</p>
+<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.
+file.
+(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 -->
           </td>
         </tr>



Mime
View raw message