Author: buildbot
Date: Thu Apr 28 17:30:13 2016
New Revision: 986967
Log:
Staging update by buildbot for aries
Added:
websites/staging/aries/trunk/content/modules/tx-control/localJPA.html
websites/staging/aries/trunk/content/modules/tx-control/xaJPA.html
Modified:
websites/staging/aries/trunk/content/ (props changed)
websites/staging/aries/trunk/content/modules/transactioncontrol.html
websites/staging/aries/trunk/content/modules/tx-control/index.html
Propchange: websites/staging/aries/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Apr 28 17:30:13 2016
@@ -1 +1 @@
-1741467
+1741482
Modified: websites/staging/aries/trunk/content/modules/transactioncontrol.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/transactioncontrol.html
(original)
+++ websites/staging/aries/trunk/content/modules/transactioncontrol.html Thu
Apr 28 17:30:13 2016
@@ -289,6 +289,10 @@ ensure that the implementations are comp
<h1 id="getting-started">Getting started<a class="headerlink"
href="#getting-started" title="Permanent link">¶</a></h1>
<p>If you're new to the Transaction Control service then we recommend that you
read the <a href="tx-control/quickstart.html">quickstart documentation
first</a>.</p>
<p>More detailed documentation is available in the <a
href="tx-control/index.html">Aries Transaction Control Project</a></p>
+<h2 id="why-use-the-transaction-control-service">Why use the Transaction
Control service?<a class="headerlink"
href="#why-use-the-transaction-control-service" title="Permanent
link">¶</a></h2>
+<p>Simply put the Transaction Control service makes resource access easy!
There's no need to worry about
+transaction lifecycle or closing connections, and there's built in support for
useful features like
+connection pooling.</p>
<h2 id="modules">Modules<a class="headerlink" href="#modules" title="Permanent
link">¶</a></h2>
<p>The following modules are available for use in OSGi</p>
<ol>
@@ -302,14 +306,26 @@ Geronimo Transaction Manager. This can b
Local resources will make use of the last-participant gambit.</p>
</li>
<li>
-<p><a href="tx-control/localJDBC.html">tx-control-provider-jdbc-local</a> :- A
JDBC resource provider that can integrate with local transactions.
-The JDBCConnectionProviderFactory service may be used directly, or a service
may be configured using
-the <em>org.apache.aries.tx.control.jdbc.local</em> pid</p>
+<p><a href="tx-control/localJDBC.html">tx-control-provider-jdbc-local</a> :- A
JDBC resource provider that provides connection pooling and
+that can integrate with local transactions. The JDBCConnectionProviderFactory
service may be used
+directly, or a service may be configured using the
<em>org.apache.aries.tx.control.jdbc.local</em> pid</p>
</li>
<li>
-<p><a href="tx-control/xaJDBC.html">tx-control-provider-jdbc-xa</a> :- A JDBC
resource provider that can integrate with local or XA transactions.
-The JDBCConnectionProviderFactory service may be used directly, or a service
may be configured using
-the <em>org.apache.aries.tx.control.jdbc.xa</em> pid</p>
+<p><a href="tx-control/xaJDBC.html">tx-control-provider-jdbc-xa</a> :- A JDBC
resource provider that provides connection pooling and
+that can integrate with local or XA transactions. The
JDBCConnectionProviderFactory service may be
+used directly, or a service may be configured using the
<em>org.apache.aries.tx.control.jdbc.xa</em> pid</p>
+</li>
+<li>
+<p><a href="tx-control/localJPA.html">tx-control-provider-jpa-local</a> :- A
JPA resource provider that can integrate with local transactions.
+The JPAEntityManagerProviderFactory service may be used directly, or a service
may be configured using
+the <em>org.apache.aries.tx.control.jpa.local</em> pid. The implementation can
also provide connection pooling
+if required</p>
+</li>
+<li>
+<p><a href="tx-control/xaJPA.html">tx-control-provider-jpa-xa</a> :- A JDBC
resource provider that integrates with XA transactions.
+The JPAEntityManagerProviderFactory service may be used directly, or a service
may be configured using
+the <em>org.apache.aries.tx.control.jpa.xa</em> pid. The implementation can
also provide connection pooling
+if required</p>
</li>
</ol>
<h3 id="which-modules-should-i-use">Which modules should I use?<a
class="headerlink" href="#which-modules-should-i-use" title="Permanent
link">¶</a></h3>
@@ -325,10 +341,10 @@ tx-control-provider-jpa-xa resource prov
<p><strong>IT IS NOT RECOMMENDED</strong> to use both tx-control-service-xa
and tx-control-service-local at
the same time. This will be confusing, and may lead to problems if different
parts of the application
bind to different service implementations.</p>
-<p>There is also no reason to use the tx-control-provider-jdbc-local in
addition to the
+<p><strong>NOTE:</strong> There is also no reason to use the
tx-control-provider-jdbc-local in addition to the
tx-control-provider-jdbc-xa service. Using both together is not typically
harmful, however the
tx-control-provider-jdbc-xa bundle supports all of the same features as the
-tx-control-provider-jdbc-local bundle.</p>
+tx-control-provider-jdbc-local bundle. The same is <strong>not</strong> true
of the JPA provider implementations.</p>
<h2 id="pre-release-apis">Pre-release APIs<a class="headerlink"
href="#pre-release-apis" title="Permanent link">¶</a></h2>
<p>As part of the Aries Transaction Control implementations pre-release
versions of the OSGi Transaction Control
API are provided. Rather than putting the API into the wrong package
namespace, or outputting them at the wrong
Modified: websites/staging/aries/trunk/content/modules/tx-control/index.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/tx-control/index.html
(original)
+++ websites/staging/aries/trunk/content/modules/tx-control/index.html Thu Apr
28 17:30:13 2016
@@ -280,20 +280,28 @@ h2:hover > .headerlink, h3:hover > .head
<h1 id="the-transaction-control-service">The Transaction Control service<a
class="headerlink" href="#the-transaction-control-service" title="Permanent
link">¶</a></h1>
<p>If you're new to the Transaction Control service then we suggest that you
read the <a href="quickstart.html">Quick Start Page</a>
first.</p>
+<h2 id="why-use-the-transaction-control-service">Why use the Transaction
Control service?<a class="headerlink"
href="#why-use-the-transaction-control-service" title="Permanent
link">¶</a></h2>
+<p>Simply put the Transaction Control service makes resource access easy!
There's no need to worry about
+transaction lifecycle or closing connections, and there's built in support for
useful features like
+connection pooling.</p>
<h3 id="the-aries-transaction-control-implementations">The Aries Transaction
Control implementations<a class="headerlink"
href="#the-aries-transaction-control-implementations" title="Permanent
link">¶</a></h3>
+<p>These modules provide implementations of the TransactionControl service</p>
<ul>
<li><a href="localTransactions.html">The Local Transaction Control
Service</a></li>
<li><a href="xaTransactions">The XA Transaction Control Service and Last
Participant support</a></li>
</ul>
<h3 id="configuring-jdbc-access">Configuring JDBC access<a class="headerlink"
href="#configuring-jdbc-access" title="Permanent link">¶</a></h3>
+<p>These modules provide portable JDBC resource providers with built in
connection pooling and
+transactional resource access</p>
<ul>
<li><a href="localJDBC.html">JDBC with Local Transactions</a></li>
<li><a href="xaJDBC.html">JDBC with XA Transactions</a></li>
</ul>
<h3 id="configuring-jpa-access">Configuring JPA access<a class="headerlink"
href="#configuring-jpa-access" title="Permanent link">¶</a></h3>
+<p>These modules provide portable JPA resource providers for transactional
resource access</p>
<ul>
-<li>TODO With Local Transactions</li>
-<li>TODO With XA Transactions</li>
+<li><a href="localJPA.html">JPA with Local Transactions</a></li>
+<li><a href="xaJPA.html">JPA with XA Transactions</a></li>
</ul>
<h3 id="advanced-topics">Advanced topics<a class="headerlink"
href="#advanced-topics" title="Permanent link">¶</a></h3>
<ul>
Added: websites/staging/aries/trunk/content/modules/tx-control/localJPA.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/tx-control/localJPA.html
(added)
+++ websites/staging/aries/trunk/content/modules/tx-control/localJPA.html Thu
Apr 28 17:30:13 2016
@@ -0,0 +1,538 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";;>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html>
+ <head>
+ <link rel="shortcut icon"
href="http://aries.apache.org/images/favicon.ico";></link>
+ <link type="text/css" rel="stylesheet"
href="http://aries.apache.org/resources/site.css";></link>
+ </script><script src="http://aries.apache.org/resources/menus.js";
language="javascript" type="text/javascript"></script>
+ <meta name="keywords" content="..."/>
+ <meta name="description" content="..." />
+ <title>
+ Apache Aries - Aries Transaction Control JPA Provider (Local)
+ </title>
+ </head>
+<body onload="SetMenu()">
+
+<table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2"> </td>
+ <td id="cell-0-1"> </td>
+ <td id="cell-0-2" colspan="2"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0"> </td>
+ <td id="cell-1-1"> </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <!-- Banner -->
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+ <a href="http://aries.apache.org/"; title="Apache Aries"> <img
border="0" src="http://aries.apache.org/images/Arieslogo_Horizontal.gif";> </a>
+ </td>
+ <td align="right" nowrap="">
+ <a href="http://www.apache.org/"; title="The Apache Software
Foundation"> <img border="0"
src="http://aries.apache.org/images/apache_feather.png";> </a>
+ </td>
+ </tr>
+ </table>
+ <!-- Banner -->
+ </div>
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left">
+ <!-- Breadcrumbs -->
+ <!-- Breadcrumbs -->
+ </div>
+ </td>
+ <td>
+ <div align="right">
+ <!-- Quicklinks -->
+ <DIV style="padding: 5px 5px 0px 25px;">
+ <FORM action="http://www.google.com/search"; method="get"
style="font-size: 10px;">
+ <A href="http://www.apache.org/licenses/LICENSE-2.0.html";
class="external-link" rel="nofollow">License</A>
+ <INPUT name="ie" type="hidden" value="UTF-8"></INPUT>
+ <INPUT name="oe" type="hidden" value="UTF-8"></INPUT>
+ <INPUT maxlength="255" name="q" size="15" type="text"
value></INPUT>
+ <INPUT name="btnG" type="submit" value="Search"></INPUT>
+ <INPUT name="domains" type="hidden"
value="aries.apache.org"></INPUT>
+ <INPUT name="sitesearch" type="hidden"
value="aries.apache.org"></INPUT>
+ </FORM>
+ </DIV>
+ <!-- Quicklinks -->
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </td>
+ <td id="cell-1-3"> </td>
+ <td id="cell-1-4"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2"> </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <!-- NavigationBar -->
+ <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('documentation')" id="documentationTitle"
class="menutitle">Documentation</div>
+
+<div id="documentation" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/documentation/integrators-guide.html">Integrators Guide</a>
+ </div>
+ <div class="menuitem">
+ <a href="/documentation/articles.html">Articles</a>
+ </div>
+ <div class="menuitem">
+ <a href="https://svn.apache.org/repos/asf/aries/slides/";>Slides</a>
+ </div>
+ <div class="menuitem">
+ <a href="/documentation/tutorials.html">Tutorials</a>
+ </div>
+ <div class="menuitem">
+ <a href="/documentation/tools.html">Tools</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('modules')" id="modulesTitle"
class="menutitle">Modules</div>
+
+<div id="modules" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/modules/samples.html">Samples</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/async-svcs.html">Asynchronous Services</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprint.html">Blueprint</a>
+ </div>
+ <div class="menuitem">
+ <a
href="/modules/blueprint-maven-plugin.html">Blueprint-maven-plugin</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprintannotation.html">Blueprint Annotations</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprintnoosgi.html">Blueprint No-OSGi</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprintweb.html">Blueprint Web</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/esaanttask.html">ESA Ant Task </a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/ebamavenpluginproject.html">EBA Maven Plugin </a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/esamavenpluginproject.html">ESA Maven Plugin </a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/jmx.html">JMX</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/jndiproject.html">JNDI</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/jpaproject.html">JPA</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/transactioncontrol.html">Transaction Control
Service</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/transactionsproject.html">Transactions</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/rsa.html">Remote Service Admin (RSA)</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/spi-fly.html">SPI Fly</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/subsystems.html">Subsystems</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/applications.html">Applications (obsolete)</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('downloads')" id="downloadsTitle"
class="menutitle">Downloads</div>
+
+<div id="downloads" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/downloads/currentreleases.html">Current Releases</a>
+ </div>
+ <div class="menuitem">
+ <a href="/downloads/testresults.html">Compliance Tests</a>
+ </div>
+ <div class="menuitem">
+ <a href="/downloads/archived-releases.html">Archived Releases</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('community')" id="communityTitle"
class="menutitle">Community</div>
+
+<div id="community" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/community/resources.html">Community Resources</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/gettinginvolved.html">Getting Involved</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/people.html">Who we are</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/boardreports.html">Board Reports</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/logos.html">Logos for Users</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('development')" id="developmentTitle"
class="menutitle">Development</div>
+
+<div id="development" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/development/buildingaries.html">Building Aries </a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/guidelines.html">Cording Guidelines</a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/architecture.html">Architecture</a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/releasingaries.html">Releasing Aries </a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/compliancetesting.html">OSGi Compliance Tests
</a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/maintainingthewebpages.html">Web Site
Maintenance </a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('sponsorship')" id="sponsorshipTitle"
class="menutitle">Sponsorship</div>
+
+<div id="sponsorship" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="http://www.apache.org/foundation/thanks.html";>Thanks</a>
+ </div>
+ <div class="menuitem">
+ <a href="http://www.apache.org/foundation/sponsorship.html";>Sponsoring
Apache</a>
+ </div>
+</div>
+ <!-- NavigationBar -->
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <!-- Content -->
+ <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>
+<h1 id="aries-transaction-control-jpa-provider-local">Aries Transaction
Control JPA Provider (Local)<a class="headerlink"
href="#aries-transaction-control-jpa-provider-local" title="Permanent
link">¶</a></h1>
+<p>The Aries Local JPA provider implementation is available at the following
maven coordinates:</p>
+<div class="codehilite"><pre><span class="nt"><dependency></span>
+ <span class="nt"><groupId></span>org.apache.aries.tx-control<span
class="nt"></groupId></span>
+ <span
class="nt"><artifactId></span>tx-control-provider-jpa-local<span
class="nt"></artifactId></span>
+ <span class="nt"><version></span><span class="cp">${</span><span
class="n">aries</span><span class="o">.</span><span class="n">tx</span><span
class="o">.</span><span class="n">control</span><span class="o">.</span><span
class="n">version</span><span class="cp">}</span><span
class="nt"></version></span>
+<span class="nt"></dependency></span>
+</pre></div>
+
+
+<p>This module is a prototype implementation of the OSGi Transaction Control
JPA resource provider
+using Local transactions. It supports JPA 2.1, and is tested against Hibernate
5.0.9 and EclipseLink 2.6.0.
+It also supports JPA 2.0, and is tested against OpenJPA 2.4.1.</p>
+<h2 id="quick-start">Quick Start<a class="headerlink" href="#quick-start"
title="Permanent link">¶</a></h2>
+<p>A configured <code>JPAEntityManagerProvider</code> can be created quickly
using Configuration Admin,
+the OSGi JPA Service, and the OSGi JDBC Service.</p>
+<ol>
+<li>Package the persistence unit in a persistence bundle</li>
+<li>Find and install a JPA provider (for example Hibernate)</li>
+<li>Find and install a JDBC Service implementation for your chosen database
(e.g. the org.h2 bundle for H2)</li>
+<li>Install a JPA service extender, such as the Apache Aries JPA container</li>
+<li>Create a factory configuration using the factory pid
<code>org.apache.aries.tx.control.jpa.local</code>
+ and add the following properties:</li>
+<li><em>osgi.jdbc.driver.class</em> :- The driver class name for your
database(e.g. org.h2.Driver)</li>
+<li><em>url</em> :- The JDBC URL to use to connect to the database</li>
+<li><em>osgi.unit.name</em> :- The name of the persistence unit</li>
+</ol>
+<p>When the DataSourceFactory for the named
<code>osgi.jdbc.driver.class</code> and the
+<code>EntityManagerFactoryBuilder</code> for the named
<code>osgi.unit.name</code> become
+available the Local JPA Resource Provider will create a
JPAEntityManagerProvider and register it in the OSGi
+service registry. All configuration properties (apart from the database
password) will be registered as
+properties of the JPAEntityManagerProvider service. These properties can be
used to select a
+ResourceProvider if more than one is present in the Service Registry.</p>
+<h2 id="when-should-i-use-this-module">When should I use this module?<a
class="headerlink" href="#when-should-i-use-this-module" title="Permanent
link">¶</a></h2>
+<p>If you wish to use entirely lightweight, resource-local transactions then
it is best to pair this module
+with the <code>tx-control-service-local</code> bundle.</p>
+<p>If two-phase commit is needed across multiple resources then the
<code>tx-control-service-xa</code> and
+<code>tx-control-provider-jpa-xa</code> bundles should be used.</p>
+<h1 id="using-the-jpa-provider-bundle">Using the JPA Provider bundle<a
class="headerlink" href="#using-the-jpa-provider-bundle" title="Permanent
link">¶</a></h1>
+<p>This Resource Provider is used in conjunction with a TransactionControl
service to provide scoped
+access to a JPA EntityManager.</p>
+<h2 id="prerequisites">Prerequisites<a class="headerlink"
href="#prerequisites" title="Permanent link">¶</a></h2>
+<p>In order to use scoped JPA access the runtime must contain a JPA provider
(for example Hibernate),
+an implementation of the OSGi JPA service (e.g. Aries JPA), and a persistence
bundle.</p>
+<h3 id="suitable-persistence-bundles">Suitable Persistence bundles<a
class="headerlink" href="#suitable-persistence-bundles" title="Permanent
link">¶</a></h3>
+<p>OSGi Persistence bundles contain the persistence descriptor (typically an
XML file called
+META-INF/persistence.xml), all of the JPA Entities, and a Meta-Persistence
header
+pointing at the persistence descriptor. (See the JPA service specification for
more details).</p>
+<p>Unlike "normal" JPA it is usually best not to fully declare the persistence
unit in the persistence descriptor.
+In particular it is a good idea to avoid putting any database configuration in
the persistence unit.
+By not configuring the database inside the bundle the persistence unit remains
decoupled,
+and can be reconfigured for any database at runtime.</p>
+<p>For example the following persistence unit:</p>
+<div class="codehilite"><pre><span class="o"><</span><span
class="n">persistence</span><span class="o">-</span><span class="n">unit</span>
<span class="n">name</span><span class="p">=</span>"<span
class="n">test</span><span class="o">-</span><span
class="n">unit</span>"<span class="o">/></span>
+</pre></div>
+
+
+<p>can be reconfigured to use any database and to create/drop tables as
appropriate. Configuration
+for the persistence unit can be provided using Configuration Admin and the
EntityManagerFactoryBuilder.</p>
+<h2 id="creating-a-resource-programmatically">Creating a resource
programmatically<a class="headerlink"
href="#creating-a-resource-programmatically" title="Permanent
link">¶</a></h2>
+<p>Preparing a resource for use is very simple. Create a
JPAEntityManagerProvider using the the
+JPAEntityManagerProviderFactory, then connect the provider to a
TransactionControl service.
+This will return a thread-safe JPA EntityManager that can then be used in any
ongoing scoped work.</p>
+<p>The normal inputs to a JPAEntityManagerProviderFactory are an
EntityManagerFactoryBuilder,
+some JPA properties to connect to the database with, and some properties to
control the resource provider.</p>
+<h3 id="declarative-services-example">Declarative Services Example<a
class="headerlink" href="#declarative-services-example" title="Permanent
link">¶</a></h3>
+<div class="codehilite"><pre><span class="p">@</span><span
class="n">Component</span>
+<span class="n">public</span> <span class="n">class</span> <span
class="n">TransactionalJPAComponent</span> <span class="p">{</span>
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">TransactionControl</span> <span
class="n">txControl</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">DataSourceFactory</span> <span class="n">dsf</span><span
class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">EntityManagerFactoryBuilder</span> <span
class="n">emfb</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">JPAEntityManagerProviderFactory</span> <span
class="n">providerFactory</span><span class="p">;</span>
+
+ <span class="n">EntityManager</span> <span class="n">em</span><span
class="p">;</span>
+
+ <span class="p">@</span><span class="n">Activate</span>
+ <span class="n">void</span> <span class="n">start</span><span
class="p">(</span><span class="n">Config</span> <span
class="n">config</span><span class="p">)</span> <span class="p">{</span>
+
+ <span class="n">Properties</span> <span class="n">jdbcProps</span>
<span class="p">=</span> <span class="n">new</span> <span
class="n">Properties</span><span class="p">();</span>
+ <span class="n">jdbcProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span><span
class="n">JDBC_URL</span><span class="p">,</span> <span
class="n">config</span><span class="p">.</span><span class="n">url</span><span
class="p">());</span>
+ <span class="n">jdbcProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span><span
class="n">JDBC_USER</span><span class="p">,</span> <span
class="n">config</span><span class="p">.</span><span class="n">user</span><span
class="p">());</span>
+ <span class="n">jdbcProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span><span
class="n">JDBC_PASSWORD</span><span class="p">,</span> <span
class="n">config</span><span class="p">.</span><span
class="n">_password</span><span class="p">());</span>
+
+ <span class="n">Map</span><span class="o"><</span><span
class="n">String</span><span class="p">,</span> <span
class="n">Object</span><span class="o">></span> <span
class="n">jpaProps</span> <span class="p">=</span> <span class="n">new</span>
<span class="n">HashMap</span><span class="o"><></span><span
class="p">();</span>
+ <span class="n">jpaProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span>"<span
class="n">javax</span><span class="p">.</span><span
class="n">persistence</span><span class="p">.</span><span
class="n">nonJtaDataSource</span>"<span class="p">,</span>
+ <span class="n">dsf</span><span class="p">.</span><span
class="n">createDataSource</span><span class="p">(</span><span
class="n">jdbcProps</span><span class="p">));</span>
+
+ <span class="n">em</span> <span class="p">=</span> <span
class="n">providerFactory</span><span class="p">.</span><span
class="n">getProviderFor</span><span class="p">(</span><span
class="n">emfb</span><span class="p">,</span> <span
class="n">jpaProps</span><span class="p">,</span>
+ <span class="n">null</span><span class="p">).</span><span
class="n">getResource</span><span class="p">(</span><span
class="n">txControl</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span
class="n">findUserName</span><span class="p">(</span><span
class="n">String</span> <span class="n">id</span><span class="p">)</span> <span
class="p">{</span>
+ <span class="n">txControl</span><span class="p">.</span><span
class="n">required</span><span class="p">(()</span> <span
class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Use</span> <span
class="n">the</span> <span class="n">EntityManager</span> <span
class="n">in</span> <span class="n">here</span>
+ <span class="p">});</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>}</p>
+<p>If the JPA EntityManagerFactory is already configured then it can be passed
into the
+JPAEntityManagerProviderFactory instead of an EntityManagerFactoryBuilder and
JPA configuration.</p>
+<h2 id="creating-a-resource-using-a-factory-configuration">Creating a resource
using a factory configuration<a class="headerlink"
href="#creating-a-resource-using-a-factory-configuration" title="Permanent
link">¶</a></h2>
+<p>Whilst it is simple to use a EntityManagerFactoryBuilder it does require
some lifecycle code to be written.
+It is therefore possible to directly create JPA resources using factory
configurations. When created,
+the factory service will listen for an applicable EntityManagerFactoryBuilder
and potentially also a
+DataSourceFactory. Once suitable services are available then a
JPAEntityManagerProvider service
+will be published. </p>
+<p>Configuration properties (except the JPA/JDBC password) are set as service
properties for the registered
+JPAEntityManagerProvider. These properties may therefore be used in filters to
select a particular provider.</p>
+<div class="codehilite"><pre><span class="p">@</span><span
class="n">Component</span>
+<span class="n">public</span> <span class="n">class</span> <span
class="n">TransactionalJDBCComponent</span> <span class="p">{</span>
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">TransactionControl</span> <span
class="n">control</span><span class="p">;</span>
+
+ <span class="n">EntityManager</span> <span class="n">em</span><span
class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span><span
class="p">(</span><span class="n">target</span><span
class="p">=</span>"<span class="p">(</span><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="p">=</span><span
class="n">test</span><span class="o">-</span><span class="n">unit</span><span
class="p">)</span>"<span class="p">)</span>
+ <span class="n">void</span> <span class="n">setProvider</span><span
class="p">(</span><span class="n">JPAEntityManagerProvider</span> <span
class="n">provider</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">em</span> <span class="p">=</span> <span
class="n">provider</span><span class="p">.</span><span
class="n">getResource</span><span class="p">(</span><span
class="n">control</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span
class="n">findUserName</span><span class="p">(</span><span
class="n">String</span> <span class="n">id</span><span class="p">)</span> <span
class="p">{</span>
+ <span class="n">txControl</span><span class="p">.</span><span
class="n">required</span><span class="p">(()</span> <span
class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Use</span> <span
class="n">the</span> <span class="n">connection</span> <span
class="n">in</span> <span class="n">here</span>
+ <span class="p">});</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>}</p>
+<p>The factory pid is <em>org.apache.aries.tx.control.jpa.local</em> and it
may use the following properties
+ (all optional aside from <em>osgi.unit.name</em>):</p>
+<h3 id="resource-provider-properties">Resource Provider properties<a
class="headerlink" href="#resource-provider-properties" title="Permanent
link">¶</a></h3>
+<ul>
+<li>
+<p><em>osgi.unit.name</em> : The name of the persistence unit that this
configuration relates to.</p>
+</li>
+<li>
+<p><em>aries.emf.builder.target.filter</em> : The target filter to use when
searching for an EntityManagerFactoryBuilder. If not specified then any builder
for the named persistence unit will be used.</p>
+</li>
+<li>
+<p><em>aries.jpa.property.names</em> : The names of the properties to pass to
the EntityManagerFactoryBuilder when creating the EntityManagerFactory. By
default all properties are copied.</p>
+</li>
+<li>
+<p><em>aries.dsf.target.filter</em> : The target filter to use when searching
for a DataSourceFactory. If not specified then <em>osgi.jdbc.driver.class</em>
must be specified.</p>
+</li>
+<li>
+<p><em>aries.jdbc.property.names</em> : The names of the properties to pass to
the DataSourceFactory when creating the JDBC resources.</p>
+</li>
+<li>
+<p><em>osgi.jdbc.driver.class</em> : Used to locate the DataSourceFactory
service if the <em>aries.dsf.target.filter</em> is not set.</p>
+</li>
+<li>
+<p><em>osgi.local.enabled</em> : Defaults to true. If false then resource
creation will fail</p>
+</li>
+<li>
+<p><em>osgi.xa.enabled</em> : Defaults to false. If true then resource
creation will fail</p>
+</li>
+<li>
+<p><em>osgi.connection.pooling.enabled</em> : Defaults to true. If true then
the Database connections will be pooled.</p>
+</li>
+<li>
+<p><em>osgi.connection.max</em> : Defaults to 10. The maximum number of
connections that should be kept in the pool</p>
+</li>
+<li>
+<p><em>osgi.connection.min</em> : Defaults to 10. The minimum number of
connections that should be kept in the pool</p>
+</li>
+<li>
+<p><em>osgi.connection.timeout</em> : Defaults to 30,000 (30 seconds). The
maximum time in milliseconds to block when waiting for a database connection</p>
+</li>
+<li>
+<p><em>osgi.idle.timeout</em> : Defaults to 180,000 (3 minutes). The time in
milliseconds before an idle connection is eligible to be closed.</p>
+</li>
+<li>
+<p><em>osgi.connection.timeout</em> : Defaults to 10,800,000 (3 hours). The
maximum time in milliseconds that a connection may remain open before being
closed.</p>
+</li>
+<li>
+<p><em>osgi.use.driver</em> : Defaults to false. If true then use the
createDriver method to connect to the database.</p>
+</li>
+</ul>
+<h3 id="jdbc-properties">JDBC properties<a class="headerlink"
href="#jdbc-properties" title="Permanent link">¶</a></h3>
+<p>The following properties will automatically be passed to the
DataSourceFactory if they are present. The list of properties may be overridden
using the <em>aries.jdbc.property.names</em> property if necessary.</p>
+<ul>
+<li>
+<p><em>databaseName</em> : The name of the database</p>
+</li>
+<li>
+<p><em>dataSourceName</em> : The name of the dataSource that will be
created</p>
+</li>
+<li>
+<p><em>description</em> : A description of the dataSource being created</p>
+</li>
+<li>
+<p><em>networkProtocol</em> : The network protocol to use.</p>
+</li>
+<li>
+<p><em>portNumber</em> : The port number to use</p>
+</li>
+<li>
+<p><em>roleName</em> : The name of the JDBC role</p>
+</li>
+<li>
+<p><em>serverName</em> : The name of the database server</p>
+</li>
+<li>
+<p><em>url</em> : The JDBC url to use (often used instead of other properties
such as <em>serverName</em>, <em>portNumber</em> and <em>databaseName</em>).</p>
+</li>
+<li>
+<p><em>user</em> : The JDBC user</p>
+</li>
+<li>
+<p><em>password</em> : The JDBC password</p>
+</li>
+</ul>
+<h3 id="jpa-properties">JPA properties<a class="headerlink"
href="#jpa-properties" title="Permanent link">¶</a></h3>
+<p>The following properties are potentially useful when configuring JPA:</p>
+<p><em>javax.persistence.schema-generation.database.action</em> : May be used
to automatically create the database tables (see the OSGi spec)</p>
+<ul>
+<li>Other provider specific properties, for example configuring second-level
caching.</li>
+</ul></div>
+ <!-- Content -->
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0"> </td>
+ <td id="cell-3-1"> </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <!-- Footer -->
+ <div id="site-footer">
+ <a href="http://aries.apache.org/privacy-policy.html";;>Privacy
+Policy</a>
+ </div>
+ <!-- Footer -->
+ </div>
+ </td>
+ <td id="cell-3-3"> </td>
+ <td id="cell-3-4"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2"> </td>
+ <td id="cell-4-1"> </td>
+ <td id="cell-4-2" colspan="2"> </td>
+ </tr>
+</table>
+</body>
+</html>
Added: websites/staging/aries/trunk/content/modules/tx-control/xaJPA.html
==============================================================================
--- websites/staging/aries/trunk/content/modules/tx-control/xaJPA.html (added)
+++ websites/staging/aries/trunk/content/modules/tx-control/xaJPA.html Thu Apr
28 17:30:13 2016
@@ -0,0 +1,540 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";;>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html>
+ <head>
+ <link rel="shortcut icon"
href="http://aries.apache.org/images/favicon.ico";></link>
+ <link type="text/css" rel="stylesheet"
href="http://aries.apache.org/resources/site.css";></link>
+ </script><script src="http://aries.apache.org/resources/menus.js";
language="javascript" type="text/javascript"></script>
+ <meta name="keywords" content="..."/>
+ <meta name="description" content="..." />
+ <title>
+ Apache Aries - Aries Transaction Control JPA Provider (XA)
+ </title>
+ </head>
+<body onload="SetMenu()">
+
+<table width="100%" cellpadding="0" cellspacing="0">
+ <tr width="100%">
+ <td id="cell-0-0" colspan="2"> </td>
+ <td id="cell-0-1"> </td>
+ <td id="cell-0-2" colspan="2"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-1-0"> </td>
+ <td id="cell-1-1"> </td>
+ <td id="cell-1-2">
+ <div style="padding: 5px;">
+ <div id="banner">
+ <!-- Banner -->
+ <table border="0" cellpadding="0" cellspacing="0" width="100%">
+ <tr>
+ <td align="left" class="topbardiv" nowrap="">
+ <a href="http://aries.apache.org/"; title="Apache Aries"> <img
border="0" src="http://aries.apache.org/images/Arieslogo_Horizontal.gif";> </a>
+ </td>
+ <td align="right" nowrap="">
+ <a href="http://www.apache.org/"; title="The Apache Software
Foundation"> <img border="0"
src="http://aries.apache.org/images/apache_feather.png";> </a>
+ </td>
+ </tr>
+ </table>
+ <!-- Banner -->
+ </div>
+ </div>
+ <div id="top-menu">
+ <table border="0" cellpadding="1" cellspacing="0" width="100%">
+ <tr>
+ <td>
+ <div align="left">
+ <!-- Breadcrumbs -->
+ <!-- Breadcrumbs -->
+ </div>
+ </td>
+ <td>
+ <div align="right">
+ <!-- Quicklinks -->
+ <DIV style="padding: 5px 5px 0px 25px;">
+ <FORM action="http://www.google.com/search"; method="get"
style="font-size: 10px;">
+ <A href="http://www.apache.org/licenses/LICENSE-2.0.html";
class="external-link" rel="nofollow">License</A>
+ <INPUT name="ie" type="hidden" value="UTF-8"></INPUT>
+ <INPUT name="oe" type="hidden" value="UTF-8"></INPUT>
+ <INPUT maxlength="255" name="q" size="15" type="text"
value></INPUT>
+ <INPUT name="btnG" type="submit" value="Search"></INPUT>
+ <INPUT name="domains" type="hidden"
value="aries.apache.org"></INPUT>
+ <INPUT name="sitesearch" type="hidden"
value="aries.apache.org"></INPUT>
+ </FORM>
+ </DIV>
+ <!-- Quicklinks -->
+ </div>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </td>
+ <td id="cell-1-3"> </td>
+ <td id="cell-1-4"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-2-0" colspan="2"> </td>
+ <td id="cell-2-1">
+ <table>
+ <tr height="100%" valign="top">
+ <td height="100%">
+ <div id="wrapper-menu-page-right">
+ <div id="wrapper-menu-page-top">
+ <div id="wrapper-menu-page-bottom">
+ <div id="menu-page">
+ <!-- NavigationBar -->
+ <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('documentation')" id="documentationTitle"
class="menutitle">Documentation</div>
+
+<div id="documentation" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/documentation/integrators-guide.html">Integrators Guide</a>
+ </div>
+ <div class="menuitem">
+ <a href="/documentation/articles.html">Articles</a>
+ </div>
+ <div class="menuitem">
+ <a href="https://svn.apache.org/repos/asf/aries/slides/";>Slides</a>
+ </div>
+ <div class="menuitem">
+ <a href="/documentation/tutorials.html">Tutorials</a>
+ </div>
+ <div class="menuitem">
+ <a href="/documentation/tools.html">Tools</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('modules')" id="modulesTitle"
class="menutitle">Modules</div>
+
+<div id="modules" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/modules/samples.html">Samples</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/async-svcs.html">Asynchronous Services</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprint.html">Blueprint</a>
+ </div>
+ <div class="menuitem">
+ <a
href="/modules/blueprint-maven-plugin.html">Blueprint-maven-plugin</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprintannotation.html">Blueprint Annotations</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprintnoosgi.html">Blueprint No-OSGi</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/blueprintweb.html">Blueprint Web</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/esaanttask.html">ESA Ant Task </a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/ebamavenpluginproject.html">EBA Maven Plugin </a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/esamavenpluginproject.html">ESA Maven Plugin </a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/jmx.html">JMX</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/jndiproject.html">JNDI</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/jpaproject.html">JPA</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/transactioncontrol.html">Transaction Control
Service</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/transactionsproject.html">Transactions</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/rsa.html">Remote Service Admin (RSA)</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/spi-fly.html">SPI Fly</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/subsystems.html">Subsystems</a>
+ </div>
+ <div class="menuitem">
+ <a href="/modules/applications.html">Applications (obsolete)</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('downloads')" id="downloadsTitle"
class="menutitle">Downloads</div>
+
+<div id="downloads" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/downloads/currentreleases.html">Current Releases</a>
+ </div>
+ <div class="menuitem">
+ <a href="/downloads/testresults.html">Compliance Tests</a>
+ </div>
+ <div class="menuitem">
+ <a href="/downloads/archived-releases.html">Archived Releases</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('community')" id="communityTitle"
class="menutitle">Community</div>
+
+<div id="community" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/community/resources.html">Community Resources</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/gettinginvolved.html">Getting Involved</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/people.html">Who we are</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/boardreports.html">Board Reports</a>
+ </div>
+ <div class="menuitem">
+ <a href="/community/logos.html">Logos for Users</a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('development')" id="developmentTitle"
class="menutitle">Development</div>
+
+<div id="development" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="/development/buildingaries.html">Building Aries </a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/guidelines.html">Cording Guidelines</a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/architecture.html">Architecture</a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/releasingaries.html">Releasing Aries </a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/compliancetesting.html">OSGi Compliance Tests
</a>
+ </div>
+ <div class="menuitem">
+ <a href="/development/maintainingthewebpages.html">Web Site
Maintenance </a>
+ </div>
+</div>
+
+<div onclick="SwitchMenu('sponsorship')" id="sponsorshipTitle"
class="menutitle">Sponsorship</div>
+
+<div id="sponsorship" class="menuitemgroup">
+ <div class="menuitem">
+ <a href="http://www.apache.org/foundation/thanks.html";>Thanks</a>
+ </div>
+ <div class="menuitem">
+ <a href="http://www.apache.org/foundation/sponsorship.html";>Sponsoring
Apache</a>
+ </div>
+</div>
+ <!-- NavigationBar -->
+ </div>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td height="100%" width="100%">
+ <!-- Content -->
+ <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>
+<h1 id="aries-transaction-control-jpa-provider-xa">Aries Transaction Control
JPA Provider (XA)<a class="headerlink"
href="#aries-transaction-control-jpa-provider-xa" title="Permanent
link">¶</a></h1>
+<p>The Aries XA JPA provider implementation is available at the following
maven coordinates:</p>
+<div class="codehilite"><pre><span class="nt"><dependency></span>
+ <span class="nt"><groupId></span>org.apache.aries.tx-control<span
class="nt"></groupId></span>
+ <span class="nt"><artifactId></span>tx-control-provider-jpa-xa<span
class="nt"></artifactId></span>
+ <span class="nt"><version></span><span class="cp">${</span><span
class="n">aries</span><span class="o">.</span><span class="n">tx</span><span
class="o">.</span><span class="n">control</span><span class="o">.</span><span
class="n">version</span><span class="cp">}</span><span
class="nt"></version></span>
+<span class="nt"></dependency></span>
+</pre></div>
+
+
+<p>This module is a prototype implementation of the OSGi Transaction Control
JPA resource provider
+using XA transactions. It supports JPA 2.1, and is tested against Hibernate
5.0.9 and EclipseLink 2.6.0.
+It also supports JPA 2.0, and is tested against OpenJPA 2.4.1.</p>
+<h2 id="quick-start">Quick Start<a class="headerlink" href="#quick-start"
title="Permanent link">¶</a></h2>
+<p>A configured <code>JPAEntityManagerProvider</code> can be created quickly
using Configuration Admin,
+the OSGi JPA Service, and the OSGi JDBC Service.</p>
+<ol>
+<li>Package the persistence unit in a persistence bundle</li>
+<li>Find and install a JPA provider (for example Hibernate)</li>
+<li>Find and install a JDBC Service implementation for your chosen database
(e.g. the org.h2 bundle for H2)</li>
+<li>Install a JPA service extender, such as the Apache Aries JPA container</li>
+<li>Create a factory configuration using the factory pid
<code>org.apache.aries.tx.control.jpa.local</code>
+ and add the following properties:</li>
+<li><em>osgi.jdbc.driver.class</em> :- The driver class name for your
database(e.g. org.h2.Driver)</li>
+<li><em>url</em> :- The JDBC URL to use to connect to the database</li>
+<li><em>osgi.unit.name</em> :- The name of the persistence unit</li>
+</ol>
+<p>When the DataSourceFactory for the named
<code>osgi.jdbc.driver.class</code> and the
+<code>EntityManagerFactoryBuilder</code> for the named
<code>osgi.unit.name</code> become
+available the Local JPA Resource Provider will create a
JPAEntityManagerProvider and register it in the OSGi
+service registry. All configuration properties (apart from the database
password) will be registered as
+properties of the JPAEntityManagerProvider service. These properties can be
used to select a
+ResourceProvider if more than one is present in the Service Registry.</p>
+<h2 id="when-should-i-use-this-module">When should I use this module?<a
class="headerlink" href="#when-should-i-use-this-module" title="Permanent
link">¶</a></h2>
+<p>If you wish to use entirely lightweight, resource-local transactions then
it is best to pair this module
+with the <code>tx-control-service-local</code> bundle.</p>
+<p>If two-phase commit is needed across multiple resources then the
<code>tx-control-service-xa</code> and
+<code>tx-control-provider-jpa-xa</code> bundles should be used.</p>
+<p>Note that when using the JDBC Service to obtain a database connection this
implementation must be able to
+create an XADataSource.</p>
+<h1 id="using-the-jpa-provider-bundle">Using the JPA Provider bundle<a
class="headerlink" href="#using-the-jpa-provider-bundle" title="Permanent
link">¶</a></h1>
+<p>This Resource Provider is used in conjunction with an XA TransactionControl
service to provide scoped
+access to a JPA EntityManager.</p>
+<h2 id="prerequisites">Prerequisites<a class="headerlink"
href="#prerequisites" title="Permanent link">¶</a></h2>
+<p>In order to use scoped JPA access the runtime must contain a JPA provider
(for example Hibernate),
+an implementation of the OSGi JPA service (e.g. Aries JPA), and a persistence
bundle.</p>
+<h3 id="suitable-persistence-bundles">Suitable Persistence bundles<a
class="headerlink" href="#suitable-persistence-bundles" title="Permanent
link">¶</a></h3>
+<p>OSGi Persistence bundles contain the persistence descriptor (typically an
XML file called
+META-INF/persistence.xml), all of the JPA Entities, and a Meta-Persistence
header
+pointing at the persistence descriptor. (See the JPA service specification for
more details).</p>
+<p>Unlike "normal" JPA it is usually best not to fully declare the persistence
unit in the persistence descriptor.
+In particular it is a good idea to avoid putting any database configuration in
the persistence unit.
+By not configuring the database inside the bundle the persistence unit remains
decoupled,
+and can be reconfigured for any database at runtime.</p>
+<p>For example the following persistence unit:</p>
+<div class="codehilite"><pre><span class="o"><</span><span
class="n">persistence</span><span class="o">-</span><span class="n">unit</span>
<span class="n">name</span><span class="p">=</span>"<span
class="n">test</span><span class="o">-</span><span
class="n">unit</span>"<span class="o">/></span>
+</pre></div>
+
+
+<p>can be reconfigured to use any database and to create/drop tables as
appropriate. Configuration
+for the persistence unit can be provided using Configuration Admin and the
EntityManagerFactoryBuilder.</p>
+<h2 id="creating-a-resource-programmatically">Creating a resource
programmatically<a class="headerlink"
href="#creating-a-resource-programmatically" title="Permanent
link">¶</a></h2>
+<p>Preparing a resource for use is very simple. Create a
JPAEntityManagerProvider using the the
+JPAEntityManagerProviderFactory, then connect the provider to a
TransactionControl service.
+This will return a thread-safe JPA EntityManager that can then be used in any
ongoing scoped work.</p>
+<p>The normal inputs to a JPAEntityManagerProviderFactory are an
EntityManagerFactoryBuilder,
+some JPA properties to connect to the database with, and some properties to
control the resource provider.</p>
+<h3 id="declarative-services-example">Declarative Services Example<a
class="headerlink" href="#declarative-services-example" title="Permanent
link">¶</a></h3>
+<div class="codehilite"><pre><span class="p">@</span><span
class="n">Component</span>
+<span class="n">public</span> <span class="n">class</span> <span
class="n">TransactionalJPAComponent</span> <span class="p">{</span>
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">TransactionControl</span> <span
class="n">txControl</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">DataSourceFactory</span> <span class="n">dsf</span><span
class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">EntityManagerFactoryBuilder</span> <span
class="n">emfb</span><span class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">JPAEntityManagerProviderFactory</span> <span
class="n">providerFactory</span><span class="p">;</span>
+
+ <span class="n">EntityManager</span> <span class="n">em</span><span
class="p">;</span>
+
+ <span class="p">@</span><span class="n">Activate</span>
+ <span class="n">void</span> <span class="n">start</span><span
class="p">(</span><span class="n">Config</span> <span
class="n">config</span><span class="p">)</span> <span class="p">{</span>
+
+ <span class="n">Properties</span> <span class="n">jdbcProps</span>
<span class="p">=</span> <span class="n">new</span> <span
class="n">Properties</span><span class="p">();</span>
+ <span class="n">jdbcProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span><span
class="n">JDBC_URL</span><span class="p">,</span> <span
class="n">config</span><span class="p">.</span><span class="n">url</span><span
class="p">());</span>
+ <span class="n">jdbcProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span><span
class="n">JDBC_USER</span><span class="p">,</span> <span
class="n">config</span><span class="p">.</span><span class="n">user</span><span
class="p">());</span>
+ <span class="n">jdbcProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span><span
class="n">JDBC_PASSWORD</span><span class="p">,</span> <span
class="n">config</span><span class="p">.</span><span
class="n">_password</span><span class="p">());</span>
+
+ <span class="n">Map</span><span class="o"><</span><span
class="n">String</span><span class="p">,</span> <span
class="n">Object</span><span class="o">></span> <span
class="n">jpaProps</span> <span class="p">=</span> <span class="n">new</span>
<span class="n">HashMap</span><span class="o"><></span><span
class="p">();</span>
+ <span class="n">jpaProps</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span>"<span
class="n">javax</span><span class="p">.</span><span
class="n">persistence</span><span class="p">.</span><span
class="n">nonJtaDataSource</span>"<span class="p">,</span>
+ <span class="n">dsf</span><span class="p">.</span><span
class="n">createDataSource</span><span class="p">(</span><span
class="n">jdbcProps</span><span class="p">));</span>
+
+ <span class="n">em</span> <span class="p">=</span> <span
class="n">providerFactory</span><span class="p">.</span><span
class="n">getProviderFor</span><span class="p">(</span><span
class="n">emfb</span><span class="p">,</span> <span
class="n">jpaProps</span><span class="p">,</span>
+ <span class="n">null</span><span class="p">).</span><span
class="n">getResource</span><span class="p">(</span><span
class="n">txControl</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span
class="n">findUserName</span><span class="p">(</span><span
class="n">String</span> <span class="n">id</span><span class="p">)</span> <span
class="p">{</span>
+ <span class="n">txControl</span><span class="p">.</span><span
class="n">required</span><span class="p">(()</span> <span
class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Use</span> <span
class="n">the</span> <span class="n">EntityManager</span> <span
class="n">in</span> <span class="n">here</span>
+ <span class="p">});</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>}</p>
+<p>If the JPA EntityManagerFactory is already configured then it can be passed
into the
+JPAEntityManagerProviderFactory instead of an EntityManagerFactoryBuilder and
JPA configuration.</p>
+<h2 id="creating-a-resource-using-a-factory-configuration">Creating a resource
using a factory configuration<a class="headerlink"
href="#creating-a-resource-using-a-factory-configuration" title="Permanent
link">¶</a></h2>
+<p>Whilst it is simple to use a EntityManagerFactoryBuilder it does require
some lifecycle code to be written.
+It is therefore possible to directly create JPA resources using factory
configurations. When created,
+the factory service will listen for an applicable EntityManagerFactoryBuilder
and potentially also a
+DataSourceFactory. Once suitable services are available then a
JPAEntityManagerProvider service
+will be published. </p>
+<p>Configuration properties (except the JPA/JDBC password) are set as service
properties for the registered
+JPAEntityManagerProvider. These properties may therefore be used in filters to
select a particular provider.</p>
+<div class="codehilite"><pre><span class="p">@</span><span
class="n">Component</span>
+<span class="n">public</span> <span class="n">class</span> <span
class="n">TransactionalJDBCComponent</span> <span class="p">{</span>
+ <span class="p">@</span><span class="n">Reference</span>
+ <span class="n">TransactionControl</span> <span
class="n">control</span><span class="p">;</span>
+
+ <span class="n">EntityManager</span> <span class="n">em</span><span
class="p">;</span>
+
+ <span class="p">@</span><span class="n">Reference</span><span
class="p">(</span><span class="n">target</span><span
class="p">=</span>"<span class="p">(</span><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="p">=</span><span
class="n">test</span><span class="o">-</span><span class="n">unit</span><span
class="p">)</span>"<span class="p">)</span>
+ <span class="n">void</span> <span class="n">setProvider</span><span
class="p">(</span><span class="n">JPAEntityManagerProvider</span> <span
class="n">provider</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">em</span> <span class="p">=</span> <span
class="n">provider</span><span class="p">.</span><span
class="n">getResource</span><span class="p">(</span><span
class="n">control</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="n">public</span> <span class="n">void</span> <span
class="n">findUserName</span><span class="p">(</span><span
class="n">String</span> <span class="n">id</span><span class="p">)</span> <span
class="p">{</span>
+ <span class="n">txControl</span><span class="p">.</span><span
class="n">required</span><span class="p">(()</span> <span
class="o">-></span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Use</span> <span
class="n">the</span> <span class="n">connection</span> <span
class="n">in</span> <span class="n">here</span>
+ <span class="p">});</span>
+ <span class="p">}</span>
+</pre></div>
+
+
+<p>}</p>
+<p>The factory pid is <em>org.apache.aries.tx.control.jpa.local</em> and it
may use the following properties
+ (all optional aside from <em>osgi.unit.name</em>):</p>
+<h3 id="resource-provider-properties">Resource Provider properties<a
class="headerlink" href="#resource-provider-properties" title="Permanent
link">¶</a></h3>
+<ul>
+<li>
+<p><em>osgi.unit.name</em> : The name of the persistence unit that this
configuration relates to.</p>
+</li>
+<li>
+<p><em>aries.emf.builder.target.filter</em> : The target filter to use when
searching for an EntityManagerFactoryBuilder. If not specified then any builder
for the named persistence unit will be used.</p>
+</li>
+<li>
+<p><em>aries.jpa.property.names</em> : The names of the properties to pass to
the EntityManagerFactoryBuilder when creating the EntityManagerFactory. By
default all properties are copied.</p>
+</li>
+<li>
+<p><em>aries.dsf.target.filter</em> : The target filter to use when searching
for a DataSourceFactory. If not specified then <em>osgi.jdbc.driver.class</em>
must be specified.</p>
+</li>
+<li>
+<p><em>aries.jdbc.property.names</em> : The names of the properties to pass to
the DataSourceFactory when creating the JDBC resources.</p>
+</li>
+<li>
+<p><em>osgi.jdbc.driver.class</em> : Used to locate the DataSourceFactory
service if the <em>aries.dsf.target.filter</em> is not set.</p>
+</li>
+<li>
+<p><em>osgi.local.enabled</em> : Defaults to false. If true then resource
creation will fail</p>
+</li>
+<li>
+<p><em>osgi.xa.enabled</em> : Defaults to true. If false then resource
creation will fail</p>
+</li>
+<li>
+<p><em>osgi.connection.pooling.enabled</em> : Defaults to true. If true then
the Database connections will be pooled.</p>
+</li>
+<li>
+<p><em>osgi.connection.max</em> : Defaults to 10. The maximum number of
connections that should be kept in the pool</p>
+</li>
+<li>
+<p><em>osgi.connection.min</em> : Defaults to 10. The minimum number of
connections that should be kept in the pool</p>
+</li>
+<li>
+<p><em>osgi.connection.timeout</em> : Defaults to 30,000 (30 seconds). The
maximum time in milliseconds to block when waiting for a database connection</p>
+</li>
+<li>
+<p><em>osgi.idle.timeout</em> : Defaults to 180,000 (3 minutes). The time in
milliseconds before an idle connection is eligible to be closed.</p>
+</li>
+<li>
+<p><em>osgi.connection.timeout</em> : Defaults to 10,800,000 (3 hours). The
maximum time in milliseconds that a connection may remain open before being
closed.</p>
+</li>
+<li>
+<p><em>osgi.use.driver</em> : Defaults to false. If true then use the
createDriver method to connect to the database.</p>
+</li>
+</ul>
+<h3 id="jdbc-properties">JDBC properties<a class="headerlink"
href="#jdbc-properties" title="Permanent link">¶</a></h3>
+<p>The following properties will automatically be passed to the
DataSourceFactory if they are present. The list of properties may be overridden
using the <em>aries.jdbc.property.names</em> property if necessary.</p>
+<ul>
+<li>
+<p><em>databaseName</em> : The name of the database</p>
+</li>
+<li>
+<p><em>dataSourceName</em> : The name of the dataSource that will be
created</p>
+</li>
+<li>
+<p><em>description</em> : A description of the dataSource being created</p>
+</li>
+<li>
+<p><em>networkProtocol</em> : The network protocol to use.</p>
+</li>
+<li>
+<p><em>portNumber</em> : The port number to use</p>
+</li>
+<li>
+<p><em>roleName</em> : The name of the JDBC role</p>
+</li>
+<li>
+<p><em>serverName</em> : The name of the database server</p>
+</li>
+<li>
+<p><em>url</em> : The JDBC url to use (often used instead of other properties
such as <em>serverName</em>, <em>portNumber</em> and <em>databaseName</em>).</p>
+</li>
+<li>
+<p><em>user</em> : The JDBC user</p>
+</li>
+<li>
+<p><em>password</em> : The JDBC password</p>
+</li>
+</ul>
+<h3 id="jpa-properties">JPA properties<a class="headerlink"
href="#jpa-properties" title="Permanent link">¶</a></h3>
+<p>The following properties are potentially useful when configuring JPA:</p>
+<p><em>javax.persistence.schema-generation.database.action</em> : May be used
to automatically create the database tables (see the OSGi spec)</p>
+<ul>
+<li>Other provider specific properties, for example configuring second-level
caching.</li>
+</ul></div>
+ <!-- Content -->
+ </td>
+ </tr>
+ </table>
+ </td>
+ <td id="cell-2-2" colspan="2"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-3-0"> </td>
+ <td id="cell-3-1"> </td>
+ <td id="cell-3-2">
+ <div id="footer">
+ <!-- Footer -->
+ <div id="site-footer">
+ <a href="http://aries.apache.org/privacy-policy.html";;>Privacy
+Policy</a>
+ </div>
+ <!-- Footer -->
+ </div>
+ </td>
+ <td id="cell-3-3"> </td>
+ <td id="cell-3-4"> </td>
+ </tr>
+ <tr width="100%">
+ <td id="cell-4-0" colspan="2"> </td>
+ <td id="cell-4-1"> </td>
+ <td id="cell-4-2" colspan="2"> </td>
+ </tr>
+</table>
+</body>
+</html>
![http://aries.apache.org/images/Arieslogo_Horizontal.gif"](http://aries.apache.org/images/Arieslogo_Horizontal.gif"){kind=link}
![http://aries.apache.org/images/apache_feather.png"](http://aries.apache.org/images/apache_feather.png"){kind=link}