aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r975427 - in /websites/staging/aries/trunk/content: ./ modules/jpaproject.html
Date Sun, 13 Dec 2015 10:38:55 GMT
Author: buildbot
Date: Sun Dec 13 10:38:55 2015
New Revision: 975427

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 Sun Dec 13 10:38:55 2015
@@ -1 +1 @@
-1719328
+1719780

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 Sun Dec 13 10:38:55 2015
@@ -271,80 +271,96 @@ h2:hover > .headerlink, h3:hover > .head
   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>
-<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
-persistence for the Blueprint container.</p>
-<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>
-<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>
-<p>Aries JPA provides container managed JPA support in an OSGi framework.</p>
+<h1 id="aries-jpa">Aries JPA<a class="headerlink" href="#aries-jpa" title="Permanent
link">&para;</a></h1>
+<p>The Aries JPA project allows allows to use container managed persistence in OSGi
in a modular and clean way.</p>
+<p>The core is the jpa.container module. It implements the "JPA Service Specification
Version 1.0" from the OSGi 
+Enterprise Specification available for public download from the <a href="http://www.osgi.org/Download/Release4V42">OSGi
Alliance</a>. 
+The jpa.blueprint module implements container managed persistence for Aries Blueprint using
a programming model like in JEE.
+The jpa.support module provides support for container managed persistence for DS and other
injection frameworks using the
+JPATemplate interface.</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>
+descriptors can be found. If the header value is empty then a default of META-INF/persistence.xml
is used.
+The persistence bundle typically also contains the JPA entities.</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>
+<div class="codehilite"><pre>    <span class="n">Meta</span><span
class="o">-</span><span class="n">Persistence</span><span class="p">:</span>
 </pre></div>
 
 
 <p>means that META-INF/persistence.xml will be searched for. For non standard locations:</p>
-<div class="codehilite"><pre><span class="n">Meta</span><span
class="o">-</span><span class="n">Persistence</span><span class="p">:</span>
<span class="n">persistence</span><span class="o">/</span><span
class="n">myPu</span><span class="p">.</span><span class="n">xml</span><span
class="p">,</span> <span class="n">pUnit</span><span class="p">.</span><span
class="n">jar</span>!<span class="o">/</span><span class="n">someFolder</span><span
class="o">/</span><span class="n">anotherPu</span><span class="p">.</span><span
class="n">xml</span>
+<div class="codehilite"><pre>    <span class="n">Meta</span><span
class="o">-</span><span class="n">Persistence</span><span class="p">:</span>
<span class="n">persistence</span><span class="o">/</span><span
class="n">myPu</span><span class="p">.</span><span class="n">xml</span><span
class="p">,</span> <span class="n">pUnit</span><span class="p">.</span><span
class="n">jar</span>!<span class="o">/</span><span class="n">someFolder</span><span
class="o">/</span><span class="n">anotherPu</span><span class="p">.</span><span
class="n">xml</span>
 </pre></div>
 
 
 <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>
-<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="aries-jpa-container-orgapacheariesjpacontainer">Aries JPA container (org.apache.aries.jpa.container)<a
class="headerlink" href="#aries-jpa-container-orgapacheariesjpacontainer" 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 Aries JPA container bundle implements the OSGi JPA service specification. It
tracks persistence unit bundles and
+creates an EntityManagerFactory service as soon as all dependencies are met.</p>
+<h4 id="specifying-the-persistenceprovider">Specifying the PersistenceProvider<a
class="headerlink" href="#specifying-the-persistenceprovider" title="Permanent link">&para;</a></h4>
+<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. If no such property is
defined then the first 
+PersistenceProvider service found will be used.</p>
+<h4 id="specifying-a-datasource">Specifying a DataSource<a class="headerlink" href="#specifying-a-datasource"
title="Permanent link">&para;</a></h4>
+<p>The next step is to configure a DataSource. There are two ways to do this. The spec
conform way is to use the database properties to determine which
+DataSourceFactory service to use and to configure 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>
+<h4 id="properties-of-the-published-entitymanagerfactory-service">Properties of the
published EntityManagerFactory service<a class="headerlink" href="#properties-of-the-published-entitymanagerfactory-service"
title="Permanent link">&para;</a></h4>
 <p>The EntityManagerFactory services will be registered with the following properties:
</p>
 <ul>
 <li>osgi.unit.name: this is the name of the persistence unit</li>
 <li>osgi.unit.provider: this is the class name of the JPA PersistenceProvider that
was used to create the EntityManagerFactory</li>
 <li>org.apache.aries.jpa.container.managed: this property will be set to true, indicating
this is a managed EntityManagerFactory.</li>
 </ul>
-<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>
+<h4 id="useful-notes">Useful notes<a class="headerlink" href="#useful-notes" title="Permanent
link">&para;</a></h4>
 <ul>
+<li>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.</li>
+<li>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.</li>
 <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.</li>
 </ul>
-<p>Aries JPA container is a standalone bundle with no other dependencies.</p>
 <h3 id="aries-jpa-api-orgapacheariesjpaapi">Aries JPA API (org.apache.aries.jpa.api)<a
class="headerlink" href="#aries-jpa-api-orgapacheariesjpaapi" 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>EmSupplier (<strong>deprecated</strong>): 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="aries-jpa-supportorgapacheariesjpasupport">Aries JPA support(org.apache.aries.jpa.support)<a
class="headerlink" href="#aries-jpa-supportorgapacheariesjpasupport" title="Permanent link">&para;</a></h3>
-<p>For each EntityManagerFactory service this bundle provides additional EmSuppler
and JpaTemplate services.</p>
+<p>For each EntityManagerFactory service this bundle provides additional services not
defined in the OSGi spec that make it
+easier to use JPA without blueprint.</p>
+<ul>
+<li>EmSuppler (<strong>deprectaed</strong>): Use the new thread safe EntityManager
instead.</li>
+<li>EntityManager: Thread safe EntityManager. Requires to be run inside a Coordination</li>
+<li>JPATemplate: Is used similar to the spring JPATemplate. it takes care of the EntityManager
lifecycle and transaction handling</li>
+</ul>
+<h4 id="thread-safe-entitymanager">Thread safe EntityManager<a class="headerlink"
href="#thread-safe-entitymanager" title="Permanent link">&para;</a></h4>
+<p>The plain EntityManager provided by the PersistenceProvider may only be used by
one thread at a time. This is ok for EJB
+where there is a thread pool but not for OSGi where tpyically each class is just instantiated
once and meant to be used
+multi threaded.</p>
+<p>So Aries JPA provides a thread safe EntityManager that can be safely used. An OSGi
Coordinator service is used to bind the
+EntityManager to a thread and to manage its lifecycle. So to use the EntityManager service
you need to make sure you only
+call it inside a Coordination. The EntityManager will be created on first access and bound
to the Coordination. When the 
+outermost Coordination of the current thread exits the EntityManager will be closed. So typically
the EntityManager is
+created per Request.</p>
+<p>Most users will not use the EntityManager service directly and instead either use
the blueprint based Annotations or the JPATemplate.
+Both of these approaches take care of the transaction and Coordination handling transparently.</p>
 <h3 id="aries-jpa-blueprint-extension-orgapacheariesjpablueprint">Aries JPA blueprint
extension (org.apache.aries.jpa.blueprint)<a class="headerlink" href="#aries-jpa-blueprint-extension-orgapacheariesjpablueprint"
title="Permanent link">&para;</a></h3>
 <p>Provides a blueprint extension for @PersistenceUnit and @PersistenceContext injection.
 To use the extension add this namespace to your blueprint </p>
-<blockquote>
-<p>xmlns:jpa="http://aries.apache.org/xmlns/jpan/v1.0.0"</p>
-</blockquote>
+<div class="codehilite"><pre>    <span class="n">xmlns</span><span
class="p">:</span><span class="n">jpa</span><span class="p">=</span>&quot;<span
class="n">http</span><span class="p">:</span><span class="o">//</span><span
class="n">aries</span><span class="p">.</span><span class="n">apache</span><span
class="p">.</span><span class="n">org</span><span class="o">/</span><span
class="n">xmlns</span><span class="o">/</span><span class="n">jpa</span><span
class="o">/</span><span class="n">v2</span><span class="p">.</span>0<span
class="p">.</span>0&quot;
+</pre></div>
+
+
 <p>and enable annotation support using the element <jpa:enable /> on top level.
-For more details see the <a href="https://svn.apache.org/repos/asf/aries/trunk/jpa/examples/tasklist-blueprint/">Aries
JPA blueprint example</a>.</p>
+Typically this namespace is used together with the transaction namespace to also provide
annoation based transactions.</p>
+<p>For more details see the <a href="https://svn.apache.org/repos/asf/aries/trunk/jpa/examples/tasklist-blueprint/">Aries
JPA blueprint example</a>.</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



Mime
View raw message