aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r957184 - in /websites/staging/aries/trunk/content: ./ modules/jpaproject.html
Date Mon, 06 Jul 2015 09:14:19 GMT
Author: buildbot
Date: Mon Jul  6 09:14:19 2015
New Revision: 957184

Log:
Staging update by buildbot for aries

Modified:
    websites/staging/aries/trunk/content/   (props changed)
    websites/staging/aries/trunk/content/modules/jpaproject.html

Propchange: websites/staging/aries/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jul  6 09:14:19 2015
@@ -1 +1 @@
-1688981
+1689341

Modified: websites/staging/aries/trunk/content/modules/jpaproject.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/jpaproject.html (original)
+++ websites/staging/aries/trunk/content/modules/jpaproject.html Mon Jul  6 09:14:19 2015
@@ -98,7 +98,18 @@
                 <div id="wrapper-menu-page-bottom">
                   <div id="menu-page">
                     <!-- NavigationBar -->
-          <div onclick="SwitchMenu('overview')" id="overviewTitle" class="menutitle">Overview</div>
+          <style type="text/css">
+/* The following code is added by mdx_elementid.py
+   It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+  visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover
> .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink
{ visibility: visible }</style>
+<div onclick="SwitchMenu('overview')" id="overviewTitle" class="menutitle">Overview</div>
 
 <div id="overview" class="menuitemgroup">
     <div class="menuitem">
@@ -281,8 +292,19 @@
           </td>
           <td height="100%" width="100%">
             <!-- Content -->
-            <div class="wiki-content"><p>Title: JPAProject</p>
-<h1 id="jpa">JPA</h1>
+            <div class="wiki-content"><style type="text/css">
+/* The following code is added by mdx_elementid.py
+   It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+  visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover
> .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink
{ visibility: visible }</style>
+<p>Title: JPAProject</p>
+<h1 id="jpa">JPA<a class="headerlink" href="#jpa" title="Permanent link">&para;</a></h1>
 <p>The Aries JPA project will make it easy for JPA persistence providers such
 as <a href="http://openjpa.apache.org/">Apache OpenJPA</a>
  to be used in an OSGi environment and will provide container managed
@@ -294,17 +316,11 @@ Release 4, Version 4.2" available for pu
 <p>Developing an Aries JPA project is very easy and can be achieved with simple steps
described in the 
 "Creation of a JPA project using Maven" section. First, however it is useful to understand
some of
 the basic concepts.</p>
-<h2 id="persistence-bundles">Persistence bundles</h2>
-<p>The Aries JPA container provides managed JPA support in an OSGi framework for OSGi
persistence bundles.
-A persistence bundle is an OSGi bundle with three special characteristics:</p>
-<ul>
-<li>It contains one or more JPA mapped classes (Entity classes, Mapped superclasses
and Embeddables)</li>
-<li>It contains a JPA persistence descriptor describing one or more persistence units</li>
-<li>The bundle manifest contains the header <strong>Meta-Persistence:</strong>
</li>
-</ul>
-<p>The value of the Meta-Persistence: header is a comma separated list of locations
where JPA persistence 
-descriptors can be found. If the header value is empty then a default of META-INF/persistence.xml
is used.
-(This behaviour is taken from the JPA service specification).</p>
+<p>Aries JPA provides container managed JPA support in an OSGi framework.</p>
+<h2 id="persistence-bundles">Persistence bundles<a class="headerlink" href="#persistence-bundles"
title="Permanent link">&para;</a></h2>
+<p>A bundle is regarded as a persistence bundle if it contains the header <strong>Meta-Persistence:</strong>
 in it's Manifest.
+The value of the Meta-Persistence: header is a comma separated list of locations where JPA
persistence 
+descriptors can be found. If the header value is empty then a default of META-INF/persistence.xml
is used.</p>
 <p>For example:</p>
 <div class="codehilite"><pre><span class="n">Meta</span><span
class="o">-</span><span class="n">Persistence</span><span class="p">:</span>
 </pre></div>
@@ -318,19 +334,12 @@ descriptors can be found. If the header
 <p>means that the locations "persistence/myPu.xml" (relative to the root of the bundle),
and 
 "someFolder/anotherPu.xml" (relative to the root of pUnit.jar, which is in the root of
 the bundle) will be searched.</p>
-<h2 id="the-aries-jpa-container">The Aries JPA container</h2>
-<p>The Aries JPA container consists of four main pieces, the two most important of
which are the API bundle
-and the container bundle.</p>
-<h3 id="the-aries-jpa-api-bundle">The Aries JPA API bundle</h3>
-<p>The Aries JPA container API bundle is <strong>not</strong> the JPA API,
it is a set of interfaces for interacting with
-the Aries JPA container. Clients are unlikely to use this API, but you may need it if you
are building
-your own runtime. This bundle also defines the interfaces that the Aries JPA container bundles
use to
-talk to each other, as a result it is a mandatory dependency of all of the other Aries JPA
container bundles.</p>
-<h3 id="the-aries-jpa-container-bundle">The Aries JPA container bundle</h3>
-<p>The Aries JPA container bundle provides basic support for application managed JPA.
It is responsible for
-locating and parsing persistence descriptors. Any persistence units found will be processed
and used to
-create EntityManagerFactory services, which will be registered on behalf of the persistence
bundle when
-it starts.</p>
+<p>The persistence bundle typically also contains the JPA entities.</p>
+<h2 id="the-aries-jpa-2-modules">The Aries JPA 2 modules<a class="headerlink" href="#the-aries-jpa-2-modules"
title="Permanent link">&para;</a></h2>
+<p>Aries JPA consists of four bundles.</p>
+<h3 id="the-aries-jpa-container-bundle">The Aries JPA container bundle<a class="headerlink"
href="#the-aries-jpa-container-bundle" title="Permanent link">&para;</a></h3>
+<p>The Aries JPA container bundle implements the OSGi JPA service specification. </p>
+<p>It tracks persistence unit bundles and creates an EntityManagerFactory service as
soon as all dependencies are met.</p>
 <p>The EntityManagerFactory services will be registered with the following properties:
</p>
 <div class="codehilite"><pre><span class="n">osgi</span><span
class="p">.</span><span class="n">unit</span><span class="p">.</span><span
class="n">name</span> <span class="o">-</span> <span class="n">this</span>
<span class="n">is</span> <span class="n">the</span> <span class="n">name</span>
<span class="n">of</span> <span class="n">the</span> <span class="n">persistence</span>
<span class="n">unit</span>
 <span class="n">osgi</span><span class="p">.</span><span class="n">unit</span><span
class="p">.</span><span class="n">provider</span> <span class="o">-</span>
<span class="n">this</span> <span class="n">is</span> <span class="n">the</span>
<span class="n">class</span> <span class="n">name</span> <span
class="n">of</span> <span class="n">the</span> <span class="n">JPA</span>
<span class="n">PersistenceProvider</span> <span class="n">that</span>
<span class="n">was</span> <span class="n">used</span> <span class="n">to</span>
<span class="n">create</span> <span class="n">the</span> <span
class="n">EntityManagerFactory</span>
@@ -338,213 +347,107 @@ it starts.</p>
 </pre></div>
 
 
+<p>For each persistence unit jpa container first determines which persistence provider
to use by analyzing the "provider" property of persistence.xml.
+It will track a PersistenceProvider service that matches this name.</p>
+<p>The next step is to configure a DataSource. The spec defines that the database properties
are used to determine which DataSourceFactory service to use and
+create a DataSource from it.</p>
+<p>Additionally aries jpa supports refering to a DataSource service using the jta-datasource
or non-jta-datasource properties. The syntax is the aries jndi syntax to search for services.</p>
+<p>If using a JTA persistence unit keep in mind that you still have to supply a javax.sql.DataSource
not an XADataSource. This DataSource must wrap an XADataSource and provide XA resource enlistment.
The simplest way to achieve this is to use pax-jdbc.</p>
+<p>As soon as PersistenceProvider and DataSource are available the EntityManagerFactory
service is created.
+Aries JPA container also supports classpath scanning and load time weaving of JPA entities.</p>
 <p>Useful notes: </p>
 <ul>
-<li>
-<p>Older versions of the Aries JPA container (below 0.4) do not support classpath scanning
or load-time weaving, 
-this means that you must list all of your entity classes in your persistence descriptor,
and that you must 
-pre-enhance your entities. This restriction does not apply to versions newer than 0.4 when
running on OSGi
-frameworks implementing version 4.3 of the OSGi specification.</p>
-</li>
-<li>
-<p>You should never call close on the EntityManagerFactory service. This call will
be made by the container when
+<li>You should never call close on the EntityManagerFactory service. This call will
be made by the container when
 the persistence bundle is removed or refreshed. If you do close the EntityManagerFactory
service then it will be 
-closed for <strong>all</strong> users of the service.</p>
-</li>
+closed for <strong>all</strong> users of the service.</li>
 </ul>
-<h3 id="the-aries-jpa-container-context-bundle">The Aries JPA container context bundle</h3>
-<p>This bundle provides managed persistence context support. In order to function it
requires the Aries JPA container
-bundle to be running as it makes use of the managed EntityManagerFactory services.</p>
-<p>This bundle also depends on the presence of a JTA service specification implementation,
as it makes use of the
-TransactionSynchronizationRegistry service.</p>
-<p>It is unlikely that clients will use this bundle directly. To actually use managed
persistence contexts a client
-should use blueprint to inject one.</p>
-<h2 id="the-aries-jpa-container-blueprint-integration-bundle">The Aries JPA container
blueprint integration bundle</h2>
-<p>This bundle provides a blueprint custom namespace for persistence unit and persistence
context injection. To
-inject persistence units the Aries JPA container bundle is required. To inject persistence
contexts the Aries
-JPA container context bundle is also required.</p>
-<p>Example blueprint follows showing the full breadth of allowable injection syntax:</p>
-<div class="codehilite"><pre><span class="nt">&lt;blueprint</span>
<span class="na">xmlns=</span><span class="s">&quot;http://www.osgi.org/xmlns/blueprint/v1.0.0&quot;</span>

-  <span class="na">xmlns:jpa=</span><span class="s">&quot;http://aries.apache.org/xmlns/jpa/v1.1.0&quot;</span><span
class="nt">&gt;</span>
-
-  <span class="c">&lt;!-- Inject a persistence unit called &quot;myUnit&quot;
using the bean property &quot;setEmf&quot; --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;unit&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:unit</span> <span class="na">property=</span><span
class="s">&quot;emf&quot;</span> <span class="na">unitname=</span><span
class="s">&quot;myUnit&quot;</span> <span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- Inject an unnamed persistence unit using the bean property
&quot;setEmf2&quot; --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;unitNoName&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:unit</span> <span class="na">property=</span><span
class="s">&quot;emf2&quot;</span> <span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- Inject a persistence unit with name &quot;&quot;
using the bean property &quot;setEmf3&quot; --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;emptyUnitName&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:unit</span> <span class="na">property=</span><span
class="s">&quot;emf3&quot;</span> <span class="na">unitname=</span><span
class="s">&quot;&quot;</span> <span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- Inject a persistence context for the unit called &quot;myUnit&quot;
using the bean property &quot;setEm&quot; --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;context&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:context</span> <span class="na">property=</span><span
class="s">&quot;em&quot;</span> <span class="na">unitname=</span><span
class="s">&quot;myUnit&quot;</span><span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- </span>
-<span class="c">      Inject an Extended persistence context for an unnamed persistence
unit that is constructed</span>
-<span class="c">      passing in the supplied properties and injected using the bean
property &quot;setEm&quot; </span>
-<span class="c">  --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;contextWithProps&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:context</span> <span class="na">property=</span><span
class="s">&quot;em&quot;</span> <span class="na">type=</span><span
class="s">&quot;EXTENDED&quot;</span><span class="nt">&gt;</span>
-      <span class="nt">&lt;map&gt;</span>
-        <span class="nt">&lt;entry</span> <span class="na">key=</span><span
class="s">&quot;one&quot;</span> <span class="na">value=</span><span
class="s">&quot;eins&quot;</span> <span class="nt">/&gt;</span>
-        <span class="nt">&lt;entry</span> <span class="na">key=</span><span
class="s">&quot;two&quot;</span> <span class="na">value=</span><span
class="s">&quot;zwo&quot;</span> <span class="nt">/&gt;</span>
-      <span class="nt">&lt;/map&gt;</span>
-    <span class="nt">&lt;/jpa:context&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- Inject a persistence unit called &quot;myUnit&quot;
using constructor injection --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;withUnitArg&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:unit</span> <span class="na">unitname=</span><span
class="s">&quot;myUnit&quot;</span><span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- Inject a persistence context using the unit called &quot;myUnit&quot;
using constructor injection --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;withContextArg&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:context</span> <span class="na">unitname=</span><span
class="s">&quot;myUnit&quot;</span><span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- Inject a persistence unit called &quot;myUnit&quot;
using constructor injection and argument index 0 --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;withIndexedUnitArg&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:unit</span> <span class="na">index=</span><span
class="s">&quot;0&quot;</span> <span class="na">unitname=</span><span
class="s">&quot;myUnit&quot;</span><span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-
-  <span class="c">&lt;!-- Inject a persistence context using the unit called &quot;myUnit&quot;
using constructor injection and argument index 1 --&gt;</span>
-  <span class="nt">&lt;bean</span> <span class="na">id=</span><span
class="s">&quot;withIndexedContextArg&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;jpa:context</span> <span class="na">index=</span><span
class="s">&quot;1&quot;</span> <span class="na">unitname=</span><span
class="s">&quot;myUnit&quot;</span><span class="nt">/&gt;</span>
-  <span class="nt">&lt;/bean&gt;</span>
-<span class="nt">&lt;/blueprint&gt;</span>
-</pre></div>
-
-
-<p>This blueprint namespace can be used by any blueprint bundle (not just the persistence
bundle), and as the injection
-occurs via the service registry your blueprint will not start until the relevant JPA resources
are available there.</p>
-<h1 id="creation-of-a-jpa-project-using-maven">Creation of a JPA project using Maven</h1>
+<p>Aries JPA container is a standalone bundle with no other dependencies.</p>
+<h3 id="the-aries-jpa-api">The Aries JPA API<a class="headerlink" href="#the-aries-jpa-api"
title="Permanent link">&para;</a></h3>
+<p>A set of interfaces to make it easier to use JPA in OSGi. It contains two main interfaces:</p>
+<ul>
+<li>EmSupplier: Allows to get a thread safe EntityManager and mark entry and exit of
blocks that access the EntityManager. This
+is rather low level and meant to be used mainly by frameworks.</li>
+<li>JpaTemplate: Allows to write closures that can safely access an EntityManager and
are executed inside a transaction.</li>
+</ul>
+<h3 id="the-aries-jpa-support">The Aries JPA support<a class="headerlink" href="#the-aries-jpa-support"
title="Permanent link">&para;</a></h3>
+<p>For each EntityManagerFactory service this bundle provides additional EmSuppler
and JpaTemplate services.</p>
+<h2 id="the-aries-jpa-blueprint-extension">The Aries JPA blueprint extension<a class="headerlink"
href="#the-aries-jpa-blueprint-extension" title="Permanent link">&para;</a></h2>
+<p>Provides a blueprint extension for @PersistenceUnit and @PersistenceContext injection.</p>
+<p>For more details see the aries jpa blueprint example: https://svn.apache.org/repos/asf/aries/trunk/jpa/examples/tasklist-blueprint/</p>
+<h1 id="creation-of-a-jpa-project-using-maven">Creation of a JPA project using Maven<a
class="headerlink" href="#creation-of-a-jpa-project-using-maven" title="Permanent link">&para;</a></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><strong>Step 1 : Module</strong></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>
-<div class="codehilite"><pre><span class="nt">&lt;groupId&gt;</span>org.apache.aries.samples.blog<span
class="nt">&lt;/groupId&gt;</span>
-<span class="nt">&lt;artifactId&gt;</span>org.apache.aries.samples.blog.persistence.jpa<span
class="nt">&lt;/artifactId&gt;</span>
-<span class="nt">&lt;name&gt;</span>Apache Aries blog sample persistence<span
class="nt">&lt;/name&gt;</span>
-<span class="nt">&lt;packaging&gt;</span>bundle<span class="nt">&lt;/packaging&gt;</span>
+<p><strong>Step 1 : Create a bundle </strong></p>
+<p>OSGi bundles are mostly regular jars but they need to contain some special OSGi
headers in the Manifest. The two changes make sure your maven project creates 
+a valid OSGi bundle.</p>
+<div class="codehilite"><pre><span class="nt">&lt;packaging&gt;</span>bundle<span
class="nt">&lt;/packaging&gt;</span>
 </pre></div>
 
 
 <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>
 <div class="codehilite"><pre><span class="nt">&lt;plugin&gt;</span>
-    <span class="nt">&lt;groupId&gt;</span>org.apache.felix<span class="nt">&lt;/groupId&gt;</span>
-    <span class="nt">&lt;artifactId&gt;</span>maven-bundle-plugin<span
class="nt">&lt;/artifactId&gt;</span>
-    <span class="nt">&lt;configuration&gt;</span>
-        <span class="nt">&lt;instructions&gt;</span>
-            <span class="nt">&lt;Bundle</span><span class="err">-SymbolicName</span><span
class="nt">&gt;</span><span class="cp">${</span><span class="n">project</span><span
class="o">.</span><span class="n">artifactId</span><span class="cp">}</span><span
class="nt">&lt;/Bundle-SymbolicName&gt;</span>
-            <span class="nt">&lt;Private</span><span class="err">-Package</span><span
class="nt">&gt;</span>org.apache.aries.samples.blog.persistence.jpa.*<span
class="nt">&lt;/Private-Package&gt;</span>
-            <span class="nt">&lt;Export</span><span class="err">-Package</span><span
class="nt">&gt;</span>!org.apache.aries.samples.blog.persistence.jpa.*<span
class="nt">&lt;/Export-Package&gt;</span>
-        <span class="nt">&lt;/instructions&gt;</span>
-    <span class="nt">&lt;/configuration&gt;</span>
+  <span class="nt">&lt;groupId&gt;</span>org.apache.felix<span class="nt">&lt;/groupId&gt;</span>
+  <span class="nt">&lt;artifactId&gt;</span>maven-bundle-plugin<span
class="nt">&lt;/artifactId&gt;</span>
+  <span class="nt">&lt;version&gt;</span>2.5.4<span class="nt">&lt;/version&gt;</span>
+  <span class="nt">&lt;extensions&gt;</span>true<span class="nt">&lt;/extensions&gt;</span>
+  <span class="nt">&lt;inherited&gt;</span>true<span class="nt">&lt;/inherited&gt;</span>
+  <span class="nt">&lt;configuration&gt;</span>
+    <span class="nt">&lt;instructions&gt;</span>
+          <span class="c">&lt;!-- Only needed for the persistence bundle containing
the jpa Entities --&gt;</span>
+      <span class="nt">&lt;Meta-Persistence&gt;</span>META-INF/persistence.xml<span
class="nt">&lt;/Meta-Persistence&gt;</span>
+      <span class="c">&lt;!-- Needed for runtime enhancement when using hibernate
--&gt;</span>
+          <span class="nt">&lt;Dynamic-Import-Package&gt;</span>*, org.hibernate.proxy,
javassist.util.proxy<span class="nt">&lt;/Dynamic-Import-Package&gt;</span>
+    <span class="nt">&lt;/instructions&gt;</span>
+  <span class="nt">&lt;/configuration&gt;</span>
 <span class="nt">&lt;/plugin&gt;</span>
 </pre></div>
 
 
-<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>
-<div class="codehilite"><pre><span class="nt">&lt;plugin&gt;</span>
-    <span class="nt">&lt;groupId&gt;</span>org.apache.felix<span class="nt">&lt;/groupId&gt;</span>
-    <span class="nt">&lt;artifactId&gt;</span>maven-bundle-plugin<span
class="nt">&lt;/artifactId&gt;</span>
-    <span class="nt">&lt;configuration&gt;</span>
-        <span class="nt">&lt;instructions&gt;</span>
-            <span class="nt">&lt;Meta-Persistence&gt;</span>META-INF/persistence.xml<span
class="nt">&lt;/Meta-Persistence&gt;</span>
-            ...
-        <span class="nt">&lt;/instructions&gt;</span>
-    <span class="nt">&lt;/configuration&gt;</span>
-<span class="nt">&lt;/plugin&gt;</span>
+<p><strong>Step 2 : Adapt the persistence file</strong></p>
+<p>We will cover here how to modify a persistence.xml for OSGi usage. For the most
part only the access to the DataSource has to be adapted for OSGi.
+With J2EE applications, you simply use the jdbc key with the name of the datasource associated
(jdbc/reportincidentdb). In OSGi jndi support is provided by aries jndi 
+(http://aries.apache.org/modules/jndiproject.html). It bridges jndi names to OSGi services.
+We must define two parameters, the "osgi:service" wich will allow to lookup OSGI services,
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>To access to the datasource, you must provide within the <jta-data-source>
or <non-jta-data-source> depending if you use transaction type JTA or RESOURCE_LOCAL.</p>
+<div class="codehilite"><pre><span class="nt">&lt;persistence-unit</span>
<span class="na">name=</span><span class="s">&quot;tasklist&quot;</span>
<span class="na">transaction-type=</span><span class="s">&quot;JTA&quot;</span><span
class="nt">&gt;</span>
+<span class="nt">&lt;jta-data-source&gt;</span>osgi:service/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/tasklist)<span
class="nt">&lt;/jta-data-source&gt;</span>
 </pre></div>
 
 
-<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><strong>Step 2 : Adapt the persistence file</strong></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>
-<div class="codehilite"><pre><span class="nt">&lt;persistence-unit</span>
<span class="na">name=</span><span class="s">&quot;ReportIncident&quot;</span>
<span class="na">transaction-type=</span><span class="s">&quot;JTA&quot;</span><span
class="nt">&gt;</span>
-<span class="nt">&lt;provider&gt;</span>org.apache.openjpa.persistence.PersistenceProviderImpl<span
class="nt">&lt;/provider&gt;</span>
-
-<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>
+<p>The other elements of the xml file are defined according to JPA specification. </p>
+<p><strong>Step 3 : Inject EntityManager into a bean and make it transactional
</strong></p>
+<p>The goal of this step is to provide a DAO layer that looks like JEE code on the
java level. For this we need to inject
+a thread safe EntityManager and ensure the DAO code is run inside a transational context.</p>
+<p>Aries JPA 1.x used a xml element inside each DAO bean to inject the EntityManager.
This syntax is not suppoerted for Aries JPA 2.x anymore.
+Instead simply enable standard @PesistenceContext and @PersistenceUnit annotation support
with the xml element <jpa:enable/> on top level.</p>
+<p>The transactional context is established using the xml element <tx:transaction>
on the bean level. In the example below we enable transactions for 
+all DAO methods. The scope of the transaction can be defined using the attribute value.</p>
+<p>Example blueprint follows showing the full breadth of allowable injection syntax:</p>
+<div class="codehilite"><pre><span class="nt">&lt;blueprint</span>
<span class="na">xmlns=</span><span class="s">&quot;http://www.osgi.org/xmlns/blueprint/v1.0.0&quot;</span>

+  <span class="na">xmlns:jpa=</span><span class="s">&quot;http://aries.apache.org/xmlns/jpan/v1.0.0&quot;</span>
+  <span class="na">xmlns:tx=</span><span class="s">&quot;http://aries.apache.org/xmlns/transactions/v1.2.0&quot;</span>
+  <span class="na">xmlns:jpa=</span><span class="s">&quot;http://aries.apache.org/xmlns/jpa/v1.1.0&quot;</span><span
class="nt">&gt;</span>
+  <span class="nt">&lt;jpa:enable</span> <span class="nt">/&gt;</span>
+  <span class="nt">&lt;service</span> <span class="na">ref=</span><span
class="s">&quot;taskService&quot;</span> <span class="na">interface=</span><span
class="s">&quot;org.apache.aries.jpa.example.tasklist.model.TaskService&quot;</span><span
class="nt">/&gt;</span>
+  <span class="nt">&lt;bean</span> <span class="na">class=</span><span
class="s">&quot;org.apache.aries.jpa.example.tasklist.blueprint.impl.TaskServiceImpl&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="nt">/&gt;</span>
+  <span class="nt">&lt;/bean&gt;</span>
+<span class="nt">&lt;/blueprint&gt;</span>
 </pre></div>
 
 
-<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><strong>Step 3 : Define the services and expose them</strong></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><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>
+<p>Make sure you inject the EntityManager in your DAO class like this:</p>
+<div class="codehilite"><pre><span class="p">@</span><span class="n">PersistenceContext</span><span
class="p">(</span><span class="n">unitName</span><span class="p">=</span>&quot;<span
class="n">tasklist</span>&quot;<span class="p">)</span>
+<span class="n">EntityManager</span> <span class="n">em</span><span
class="p">;</span>
 </pre></div>
 
 
-<p></blueprint></p>
-<p>(1) The &lt;tx:transaction&gt; 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.<br />
-(2) The JPA context is created using &lt;jpa:context&gt;. 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.<br />
-(3) The &lt;service&gt; allows to expose an interface on the OSGI Registry Service
using as key the name of the interface ("javax,sql.Datasource").
-The &lt;service-properties&gt; will let to define a property that we will use to
retrieve the datasource from the registry</p>
 <p><strong>Step 4 : Package the solution</strong></p>
-<p>To package and deploy the solution, execute a "maven clean install" instruction
and deploy your project into your favorite OSGI platform. Depending in which OSGI container
-you plan to deploy your projects, the bundles (Aries JPA, OpenJPA, Aries Transaction, ....)
to be used will be
-different and you will have to identify them. The Aries samples project provides you a list
of <a href="https://svn.apache.org/repos/asf/aries/trunk/samples/blog/blog-itests/src/test/java/org/apache/aries/samples/blog/itests/JpaBlogSampleWithEbaTest.java">bundles</a>
and you 
-can use them as a starting point to create your first project.</p></div>
+<p>To package the solution, execute a "maven clean install" instruction. Installing
Aries JPA and Aries Transaction into arbitrary containers is beyond the scope of this document.
</p>
+<p>To keep the installation instructions small we only cover installation into Apache
Karaf 4.x. Karaf provides features for Aries JPA, Aries Transaction, Hibernate and Pax-jdbc
so installation is very easy.
+See the README at https://svn.apache.org/repos/asf/aries/trunk/jpa/examples/tasklist-blueprint</p></div>
             <!-- Content -->
           </td>
         </tr>



Mime
View raw message