You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by bu...@apache.org on 2014/11/26 21:22:02 UTC
svn commit: r930651 [6/10] - in /websites/staging/deltaspike/trunk/content:
./ staging/documentation/
Added: websites/staging/deltaspike/trunk/content/staging/documentation/jpa.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/staging/documentation/jpa.html (added)
+++ websites/staging/deltaspike/trunk/content/staging/documentation/jpa.html Wed Nov 26 20:22:01 2014
@@ -0,0 +1,742 @@
+<!DOCTYPE html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="description" content="deltaspike-generate-pages">
+<meta name="author" content="chm">
+
+<title>JPA Module</title>
+
+<!-- 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. -->
+
+<!-- Styles -->
+
+<link href="https://deltaspike.apache.org/resources/css/bootstrap.css" rel="stylesheet">
+<link href="https://deltaspike.apache.org/resources/css/bootstrap-responsive.css" rel="stylesheet">
+
+<style type="text/css">
+/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
+/*pre.CodeRay {background-color:#f7f7f8;}*/
+.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
+.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
+.CodeRay .line-numbers strong{font-weight: normal}
+table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
+table.CodeRay td{vertical-align: top}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
+table.CodeRay td.code{padding:0 0 0 .5em}
+table.CodeRay td.code>pre{padding:0}
+.CodeRay .debug{color:#fff !important;background:#000080 !important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:#000080}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:#008080}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#00}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:#008080}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:#008080}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
+body {
+ padding-top: 60px;
+ padding-bottom: 40px;
+}
+</style>
+<script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-36103647-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+
+ </script>
+</head>
+
+<body>
+
+ <div class="navbar navbar-fixed-top">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="btn btn-navbar" data-toggle="collapse"
+ data-target=".nav-collapse"> <span class="icon-bar"></span> <span
+ class="icon-bar"></span> <span class="icon-bar"></span>
+ </a> <a class="brand logocolor"
+ href="http://deltaspike.apache.org/index.html">Apache
+ DeltaSpike</a>
+ <div class="nav-collapse">
+ <ul class="nav">
+ <li class="active"><a
+ href="http://deltaspike.apache.org/index.html">Home</a></li>
+ <li><a href="http://deltaspike.apache.org/documentation">Documentation</a></li>
+ <li><a href="http://deltaspike.apache.org/javadoc.html">Javadoc</a></li>
+ <li><a href="http://deltaspike.apache.org/documentation/source.html">Source</a></li>
+ <li><a href="http://deltaspike.apache.org/download.html">Download</a></li>
+ <li><a href="http://deltaspike.apache.org/community.html">Community</a></li>
+ <!-- <li><a href="./support.html">Support</a></li> -->
+ <li><a href="http://deltaspike.apache.org/news.html">News</a></li>
+ <li><a
+ href="http://deltaspike.apache.org/migration-guide.html">Migration</a></li>
+ </ul>
+ </div>
+ <!--/.nav-collapse -->
+ <form id="search-form" action="http://www.google.com/search"
+ method="get" class="navbar-search pull-right">
+ <input value="deltaspike.apache.org" name="sitesearch"
+ type="hidden"> <input class="search-query" name="q"
+ id="query" type="text">
+ </form>
+ </div>
+ </div>
+ </div>
+
+ <div class="container">
+ <div class="row">
+ <div class="span12">
+ <div class="page-title">
+ <h1>JPA Module</h1>
+ </div>
+
+ <div id="toc" class="toc">
+ <ul class="sectlevel1">
+<li><a href="#__transactional">@Transactional</a></li>
+<li><a href="#__transactionscoped">@TransactionScoped</a></li>
+<li><a href="#_extended_persistence_contexts">Extended Persistence Contexts</a></li>
+<li><a href="#_jta_support">JTA Support</a></li>
+</ul>
+ <hr>
+
+ <div class="sect1">
+<h2 id="__transactional">@Transactional</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>This annotation is an alternative to transactional EJBs which allows to
+execute a method within a transaction. Before it’s possible to start
+using the annotation, it’s required to implement a CDI producer for an
+<code>EntityManager</code> and it’s needed to inject the <code>EntityManager</code> in the
+bean which uses <code>@Transactional</code>. As shown later on it’s also possible
+to use multiple qualifiers for using different `EntityManager`s.</p>
+</div>
+<div class="paragraph">
+<p><strong>Hint:</strong> If you are using features described by this page with CDI 1.0
+(or DeltaSpike up to v1.1.0 with CDI 1.1+), you have
+to enable the transaction interceptor in your beans.xml file:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><beans></span>
+ <span class="comment"><!-- Not needed with CDI 1.1+ and DeltaSpike v1.1.1+ --></span>
+ <span class="tag"><interceptors></span>
+ <span class="tag"><class></span>org.apache.deltaspike.jpa.impl.transaction.TransactionalInterceptor<span class="tag"></class></span>
+ <span class="tag"></interceptors></span>
+<span class="tag"></beans></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The following example shows a simple producer for an <code>EntityManager</code> and
+the corresponding dispose-method. Producing it as request scoped bean
+means that the dispose method will be called on finishing the request.
+As an alternative it’s possible to use a special scope called
+<code>@TransactionScoped</code> provided by the same DeltaSpike module.</p>
+</div>
+<div class="paragraph">
+<p>Producer for the default EntityManager (<strong>no EE-Server</strong>):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span>
+{
+ <span class="comment">//or manual bootstrapping</span>
+ <span class="annotation">@PersistenceContext</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="annotation">@Produces</span>
+ <span class="annotation">@RequestScoped</span>
+ <span class="directive">protected</span> EntityManager createEntityManager()
+ {
+ <span class="keyword">return</span> <span class="local-variable">this</span>.entityManager;
+ }
+
+ <span class="directive">protected</span> <span class="type">void</span> closeEntityManager(<span class="annotation">@Disposes</span> EntityManager entityManager)
+ {
+ <span class="keyword">if</span> (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Producer for the default EntityManager (<strong>EE-Server</strong>):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ApplicationScoped</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span>
+{
+ <span class="annotation">@PersistenceUnit</span>
+ <span class="directive">private</span> EntityManagerFactory entityManagerFactory;
+
+ <span class="annotation">@Produces</span>
+ <span class="annotation">@Default</span>
+ <span class="annotation">@RequestScoped</span>
+ <span class="directive">public</span> EntityManager create()
+ {
+ <span class="keyword">return</span> <span class="local-variable">this</span>.entityManagerFactory.createEntityManager();
+ }
+
+ <span class="directive">public</span> <span class="type">void</span> dispose(<span class="annotation">@Disposes</span> <span class="annotation">@Default</span> EntityManager entityManager)
+ {
+ <span class="keyword">if</span> (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The following examples show how to use the <code>EntityManager</code> produced by
+the example above.</p>
+</div>
+<div class="paragraph">
+<p>Beans with transactional method:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">TransactionalBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="annotation">@Transactional</span>
+ <span class="directive">public</span> <span class="type">void</span> executeInTransaction()
+ {
+ <span class="comment">//...</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Simple transactional bean (all methods transactional):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//...</span>
+<span class="annotation">@Transactional</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">TransactionalBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="comment">//...</span>
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As illustrated in the following example it’s also possible to use
+<code>@Transactional</code> for stereotypes.</p>
+</div>
+<div class="paragraph">
+<p>Stereotype for transactional beans (+ usage):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Stereotype</span>
+<span class="annotation">@Transactional</span>
+<span class="annotation">@ApplicationScoped</span>
+<span class="directive">public</span> <span class="annotation">@interface</span> Repository
+{
+}
+
+<span class="comment">//...</span>
+<span class="annotation">@Repository</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">TransactionalBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="comment">//...</span>
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Besides such simple usages, it’s also supported to use qualifiers to
+access multiple persistence-units in parallel. The default qualifier for
+<code>@Transactional</code> is <code>@Any</code>. Therefore a transaction for every injected
+entity manager will be started. The example afterwards shows how to
+change this default behaviour.</p>
+</div>
+<div class="paragraph">
+<p>Producer for multiple entity managers (+ usage):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span>
+{
+ <span class="annotation">@PersistenceContext</span>(unitName = <span class="string"><span class="delimiter">"</span><span class="content">firstDB</span><span class="delimiter">"</span></span>)
+ <span class="directive">private</span> EntityManager firstEntityManager;
+
+ <span class="annotation">@PersistenceContext</span>(unitName = <span class="string"><span class="delimiter">"</span><span class="content">secondDB</span><span class="delimiter">"</span></span>)
+ <span class="directive">private</span> EntityManager secondEntityManager;
+
+ <span class="annotation">@Produces</span>
+ <span class="annotation">@First</span>
+ <span class="annotation">@RequestScoped</span>
+ <span class="directive">protected</span> EntityManager createFirstEntityManager()
+ {
+ <span class="keyword">return</span> <span class="local-variable">this</span>.firstEntityManager;
+ }
+
+ <span class="directive">protected</span> <span class="type">void</span> closeFirstEntityManager(<span class="annotation">@Disposes</span> <span class="annotation">@First</span> EntityManager entityManager)
+ {
+ <span class="keyword">if</span> (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+
+ <span class="annotation">@Produces</span>
+ <span class="annotation">@Second</span>
+ <span class="annotation">@RequestScoped</span>
+ <span class="directive">protected</span> EntityManager createSecondEntityManager()
+ {
+ <span class="keyword">return</span> <span class="local-variable">this</span>.secondEntityManager;
+ }
+
+ <span class="directive">protected</span> <span class="type">void</span> closeSecondEntityManager(<span class="annotation">@Disposes</span> <span class="annotation">@Second</span> EntityManager entityManager)
+ {
+ <span class="keyword">if</span> (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+}
+
+<span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">FirstLevelTransactionBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> <span class="annotation">@First</span> EntityManager firstEntityManager;
+
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> NestedTransactionBean nestedTransactionBean;
+
+ <span class="annotation">@Transactional</span>
+ <span class="directive">public</span> <span class="type">void</span> executeInTransaction()
+ {
+ <span class="comment">//...</span>
+ <span class="local-variable">this</span>.nestedTransactionBean.executeInTransaction();
+ }
+}
+
+<span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">NestedTransactionBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> <span class="annotation">@Second</span> EntityManager secondEntityManager;
+
+ <span class="annotation">@Transactional</span>
+ <span class="directive">public</span> <span class="type">void</span> executeInTransaction()
+ {
+ <span class="comment">//...</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The following example shows how to use only the specified
+<code>EntityManager</code>/s</p>
+</div>
+<div class="paragraph">
+<p>Activating entity managers manually:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">MultiTransactionBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> EntityManager defaultEntityManager;
+
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> <span class="annotation">@First</span> EntityManager firstEntityManager;
+
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> <span class="annotation">@Second</span> EntityManager secondEntityManager;
+
+ <span class="annotation">@Transactional</span>(qualifier = Default.class)
+ <span class="directive">public</span> <span class="type">void</span> executeInDefaultTransaction()
+ {
+ }
+
+ <span class="annotation">@Transactional</span>(qualifier = First.class)
+ <span class="directive">public</span> <span class="type">void</span> executeInFirstTransaction()
+ {
+ }
+
+ <span class="annotation">@Transactional</span>(qualifier = Second.class)
+ <span class="directive">public</span> <span class="type">void</span> executeInSecondTransaction()
+ {
+ }
+
+ <span class="annotation">@Transactional</span>(qualifier = {First.class, Second.class})
+ <span class="directive">public</span> <span class="type">void</span> executeInFirstAndSecondTransaction()
+ {
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>All examples also work with nested calls. In the following example the
+transaction handling is done on the entry point (after
+FirstLevelTransactionBean#executeInTransaction).</p>
+</div>
+<div class="paragraph">
+<p>Joining existing transaction in nested call:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">FirstLevelTransactionBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> NestedTransactionBean nestedTransactionBean;
+
+ <span class="annotation">@Transactional</span>
+ <span class="directive">public</span> <span class="type">void</span> executeInTransaction()
+ {
+ <span class="local-variable">this</span>.nestedTransactionBean.executeInTransaction();
+ }
+}
+
+<span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">NestedTransactionBean</span>
+{
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="annotation">@Transactional</span>
+ <span class="directive">public</span> <span class="type">void</span> executeInTransaction()
+ {
+ <span class="comment">//...</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The final transaction handling for all <code>EntityManager</code> s is also done
+after the outermost transactional method if <code>NestedTransactionBean</code> uses
+a different <code>EntityManager</code>. So it’s possible to catch an exception in
+<code>FirstLevelTransactionBean</code> e.g. to try an optional path instead of an
+immediate rollback.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="__transactionscoped">@TransactionScoped</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p><code>@Transactional</code> also starts a context which is available as long as the
+transaction started by <code>@Transactional</code>. Besides other beans you can use
+this scope for the <code>EntityManager</code> itself. That means the
+<code>EntityManager</code> will be closed after leaving the method annotated with
+<code>@Transactional</code>.</p>
+</div>
+<div class="paragraph">
+<p>Producer for the default EntityManager which should be used only for one
+transaction:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span>
+{
+ <span class="comment">//or manual bootstrapping</span>
+ <span class="annotation">@PersistenceContext</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="annotation">@Produces</span>
+ <span class="annotation">@TransactionScoped</span>
+ <span class="directive">protected</span> EntityManager createEntityManager()
+ {
+ <span class="keyword">return</span> <span class="local-variable">this</span>.entityManager;
+ }
+
+ <span class="directive">protected</span> <span class="type">void</span> closeEntityManager(<span class="annotation">@Disposes</span> EntityManager entityManager)
+ {
+ <span class="keyword">if</span> (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_extended_persistence_contexts">Extended Persistence Contexts</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Frameworks like MyFaces Orchestra provide a feature which allows keeping
+an <code>EntityManager</code> across multiple requests. That means it isn’t
+required to call <code>EntityManager#merge</code> to add detached entities to the
+context. However, several application architectures don’t allow such an
+approach (due to different reasons like scalability). In theory that
+sounds nice and it works pretty well for small to medium sized projects
+esp. if an application doesn’t rely on session replication in clusters.
+That also means that such an approach restricts your target environment
+from the very beginning. One of the base problems is that an
+<code>EntityManager</code> isn’t serializable. Beans which are scoped in a
+normal-scoped CDI context have to be serializable. So by default it
+isn’t allowed by CDI to provide a producer-method which exposes e.g. a
+conversation scoped <code>EntityManager</code> as it is. We <strong>don’t</strong> recommend to
+use this approach and therefore it isn’t available out-of-the-box.
+However, if you really need this approach to avoid calling <code>#merge</code> for
+your detached entities, it’s pretty simple to add this functionality.</p>
+</div>
+<div class="paragraph">
+<p>Usage of a simple <code>ExtendedEntityManager</code></p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Inject</span>
+<span class="directive">private</span> EntityManager entityManager;</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As you see the usage is the same. You <strong>don’t</strong> have to use
+<code>ExtendedEntityManager</code> at the injection point. It’s just needed in the
+producer-method:</p>
+</div>
+<div class="paragraph">
+<p>Producer for the default Extended-<code>EntityManager</code> (<strong>no EE-Server</strong>):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//...</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ExtendedEntityManagerProducer</span>
+{
+ <span class="comment">//or manual bootstrapping</span>
+ <span class="annotation">@PersistenceContext</span>
+ <span class="directive">private</span> EntityManager entityManager;
+
+ <span class="annotation">@Produces</span>
+ <span class="annotation">@RequestScoped</span>
+ <span class="directive">protected</span> ExtendedEntityManager createEntityManager()
+ {
+ <span class="keyword">return</span> <span class="keyword">new</span> ExtendedEntityManager(<span class="local-variable">this</span>.entityManager);
+ }
+
+ <span class="directive">protected</span> <span class="type">void</span> closeEntityManager(<span class="annotation">@Disposes</span> ExtendedEntityManager entityManager)
+ {
+ <span class="keyword">if</span> (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Producer for the default Extended-<code>EntityManager</code> (<strong>EE-Server</strong>):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ApplicationScoped</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ExtendedEntityManagerProducer</span>
+{
+ <span class="annotation">@PersistenceUnit</span>
+ <span class="directive">private</span> EntityManagerFactory entityManagerFactory;
+
+ <span class="annotation">@Produces</span>
+ <span class="annotation">@Default</span>
+ <span class="annotation">@RequestScoped</span>
+ <span class="directive">public</span> ExtendedEntityManager create()
+ {
+ <span class="keyword">return</span> <span class="keyword">new</span> ExtendedEntityManager(<span class="local-variable">this</span>.entityManagerFactory.createEntityManager());
+ }
+
+ <span class="directive">public</span> <span class="type">void</span> dispose(<span class="annotation">@Disposes</span> <span class="annotation">@Default</span> ExtendedEntityManager entityManager)
+ {
+ <span class="keyword">if</span> (entityManager.isOpen())
+ {
+ entityManager.close();
+ }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Implementation of a simple <code>ExtendedEntityManager</code>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Typed</span>()
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ExtendedEntityManager</span> <span class="directive">implements</span> EntityManager, <span class="predefined-type">Serializable</span>
+{
+ <span class="directive">private</span> <span class="directive">static</span> <span class="directive">final</span> <span class="type">long</span> serialVersionUID = <span class="integer">3770954229283539616L</span>;
+
+ <span class="directive">private</span> <span class="directive">transient</span> EntityManager wrapped;
+
+ <span class="directive">protected</span> ExtendedEntityManager()
+ {
+ }
+
+ <span class="directive">public</span> ExtendedEntityManager(EntityManager wrapped)
+ {
+ <span class="local-variable">this</span>.wrapped = wrapped;
+ }
+
+ <span class="comment">/*
+ * generated
+ */</span>
+ <span class="comment">//delegate all calls to this.wrapped - most IDEs allow to generate it</span>
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This approach just works if it <strong>doesn’t come to serialization</strong> of this
+wrapper e.g. in case of session-replication. If those beans get
+serialized, you have to overcome this restriction by storing the
+persistence-unit-name and recreate the <code>EntityManager</code> via
+<code>Persistence.createEntityManagerFactory(this.persistenceUnitName).createEntityManager();</code>
+and sync it with the database before closing it on serialization.
+Furthermore, you have to intercept some methods of the <code>EntityManager</code>
+to merge detached entities automatically if those entities get
+serialized as well. However, as mentioned before <strong>we don’t recommend</strong>
+such an approach.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_jta_support">JTA Support</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Per default the transaction-type used by <code>@Transactional`is
+'RESOURCE_LOCAL'. If you configure `transaction-type="JTA"`in the
+persistence.xml, you have to enable an alternative `TransactionStrategy</code>
+in the beans.xml which is called
+<code>org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy</code>.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><beans></span>
+ <span class="tag"><alternatives></span>
+ <span class="tag"><class></span>org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy<span class="tag"></class></span>
+ <span class="tag"></alternatives></span>
+<span class="tag"></beans></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If you have multiple persistence-units and you have to use both
+transaction-types or the settings for development have to be different
+than the production settings, you can use
+<code>org.apache.deltaspike.jpa.impl.transaction.EnvironmentAwareTransactionStrategy</code>
+instead.</p>
+</div>
+<div class="paragraph">
+<p><strong>Hint:</strong></p>
+</div>
+<div class="paragraph">
+<p>In case of some versions of Weld (or OpenWebBeans in BDA mode), you have
+to configure it as global-alternative instead of an <code><alternatives></code> in
+beans.xml. That means you have to add e.g.:
+<code>globalAlternatives.org.apache.deltaspike.jpa.spi.transaction.TransactionStrategy=org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy</code>
+to /META-INF/apache-deltaspike.properties</p>
+</div>
+</div>
+</div>
+ </div>
+
+ <hr>
+
+ <footer>
+ <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.</p>
+ <p>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+ </footer>
+
+ </div>
+ <!-- /.container -->
+
+</body>
+</html>
\ No newline at end of file