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 2015/06/01 11:41:59 UTC
svn commit: r953396 [1/3] - in /websites/staging/deltaspike/trunk/content:
./ staging/documentation/
Author: buildbot
Date: Mon Jun 1 09:41:59 2015
New Revision: 953396
Log:
Staging update by buildbot for deltaspike
Added:
websites/staging/deltaspike/trunk/content/staging/documentation/asciidoc-temp9145708526139550128.xml (with props)
Modified:
websites/staging/deltaspike/trunk/content/ (props changed)
websites/staging/deltaspike/trunk/content/staging/documentation/bean-validation.html
websites/staging/deltaspike/trunk/content/staging/documentation/container-control.html
websites/staging/deltaspike/trunk/content/staging/documentation/data.html
websites/staging/deltaspike/trunk/content/staging/documentation/jpa.html
websites/staging/deltaspike/trunk/content/staging/documentation/jsf.html
websites/staging/deltaspike/trunk/content/staging/documentation/partial-bean.html
websites/staging/deltaspike/trunk/content/staging/documentation/scheduler.html
websites/staging/deltaspike/trunk/content/staging/documentation/security.html
websites/staging/deltaspike/trunk/content/staging/documentation/servlet.html
websites/staging/deltaspike/trunk/content/staging/documentation/test-control.html
Propchange: websites/staging/deltaspike/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jun 1 09:41:59 2015
@@ -1 +1 @@
-1680991
+1682851
Added: websites/staging/deltaspike/trunk/content/staging/documentation/asciidoc-temp9145708526139550128.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/deltaspike/trunk/content/staging/documentation/asciidoc-temp9145708526139550128.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Modified: websites/staging/deltaspike/trunk/content/staging/documentation/bean-validation.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/staging/documentation/bean-validation.html (original)
+++ websites/staging/deltaspike/trunk/content/staging/documentation/bean-validation.html Mon Jun 1 09:41:59 2015
@@ -281,7 +281,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect1">
-<h2 id="_configure_your_projects">Configure Your Projects</h2>
+<h2 id="_project_setup">Project Setup</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <a href="configure.html">Configure DeltaSpike in Your Projects</a>. For Maven-independent projects, see <a href="configure.html#config-maven-indep">Configure DeltaSpike in Maven-independent Projects</a>.</p>
@@ -305,10 +305,8 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect1">
-<h2 id="_use_the_module_features">Use the Module Features</h2>
+<h2 id="_scoping">Scoping</h2>
<div class="sectionbody">
-<div class="sect2">
-<h3 id="_scoping">Scoping</h3>
<div class="paragraph">
<p>A <code>ConstraintValidator</code> inherits the scope defined in the bean class.</p>
</div>
@@ -325,8 +323,10 @@ A <code>ConstraintValidator</code> may b
</table>
</div>
</div>
-<div class="sect2">
-<h3 id="_code_requirements">Code Requirements</h3>
+</div>
+<div class="sect1">
+<h2 id="_code_requirements">Code Requirements</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>There are no compile dependencies to use the Bean Validation module. You
simply need to override the factory. Then you can build your <code>ConstraintValidator</code> based on CDI programming rules.</p>
@@ -349,7 +349,6 @@ simply need to override the factory. The
</div>
</div>
</div>
-</div>
</div>
</div>
@@ -375,18 +374,14 @@ simply need to override the factory. The
<div class="fallback-toc">
<ul class="sectlevel1">
<li><a href="#_overview">Overview</a></li>
-<li><a href="#_configure_your_projects">Configure Your Projects</a>
+<li><a href="#_project_setup">Project Setup</a>
<ul class="sectlevel2">
<li><a href="#_declare_bean_validation_module_dependencies">Declare Bean Validation Module Dependencies</a></li>
</ul>
</li>
-<li><a href="#_use_the_module_features">Use the Module Features</a>
-<ul class="sectlevel2">
<li><a href="#_scoping">Scoping</a></li>
<li><a href="#_code_requirements">Code Requirements</a></li>
</ul>
-</li>
-</ul>
</div>
</div>
Modified: websites/staging/deltaspike/trunk/content/staging/documentation/container-control.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/staging/documentation/container-control.html (original)
+++ websites/staging/deltaspike/trunk/content/staging/documentation/container-control.html Mon Jun 1 09:41:59 2015
@@ -281,7 +281,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect1">
-<h2 id="_configure_your_projects">Configure Your Projects</h2>
+<h2 id="_project_setup">Project Setup</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <a href="configure.html">Configure DeltaSpike in Your Projects</a>. For Maven-independent projects, see <a href="configure.html#config-maven-indep">Configure DeltaSpike in Maven-independent Projects</a>.</p>
@@ -311,10 +311,8 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect1">
-<h2 id="_use_the_module_features">Use the Module Features</h2>
+<h2 id="_start_the_cdi_container_from_your_project">Start the CDI Container from Your Project</h2>
<div class="sectionbody">
-<div class="sect2">
-<h3 id="_start_the_cdi_container_from_your_project">Start the CDI Container from Your Project</h3>
<div class="paragraph">
<p>To start a CDI container in your application, you must instantiate a <code>CdiContainer</code> object and call the <code>#boot</code> method. When <code>#boot</code> is called, the <code>CdiContainer</code> scans CDI-enabled
archives for beans and CDI extensions. Before the application exits, <code>#shutdown</code> must be called to correctly destroy all beans. An example is given in the code snippet here.</p>
@@ -373,8 +371,10 @@ archives for beans and CDI extensions. B
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_cdicontainer">CdiContainer</h3>
+</div>
+<div class="sect1">
+<h2 id="_cdicontainer">CdiContainer</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>The <code>CdiContainer</code> interface provides booting and shutdown of the CDI containers from deployed applications, with <code>CdiContainerLoader</code> a simple factory providing access to the underlying <code>CdiContainer</code> implementation.</p>
</div>
@@ -385,14 +385,18 @@ archives for beans and CDI extensions. B
<p>For instructions and examples on using this feature in your projects, see <a href="cdiimp.html#javase6">Enable CDI For Your Java Environment: Java SE6+</a>.</p>
</div>
</div>
-<div class="sect2">
-<h3 id="_contextcontrol_usage">ContextControl Usage</h3>
+</div>
+<div class="sect1">
+<h2 id="_contextcontrol_usage">ContextControl Usage</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>The <code>ContextControl</code> interface provides life-cycle control of the CDI container built-in contexts. This includes starting and stoping built-in standard contexts like <code>@RequestScoped</code>, <code>@ConversationScoped</code>, and <code>@SessionScoped</code>. It is provided as an <code>@Dependent</code> bean and can be injected in the classic CDI way. This feature can be used and is helpful in all Java environments, including Java SE, as illustrated here.</p>
</div>
</div>
-<div class="sect2">
-<h3 id="_procedure_for_builing_uber_jar">Procedure for builing Uber jar</h3>
+</div>
+<div class="sect1">
+<h2 id="_procedure_for_building_an_uber_jar">Procedure for building an uber jar</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>Uber jar or executable jar can created by using the maven shade plugin. Some things you needs to be aware of when you use it.</p>
</div>
@@ -418,8 +422,8 @@ archives for beans and CDI extensions. B
</li>
</ul>
</div>
-<div class="sect3">
-<h4 id="_restart_the_requestcontext_in_unit_tests">Restart the RequestContext in Unit Tests</h4>
+<div class="sect2">
+<h3 id="_restart_the_requestcontext_in_unit_tests">Restart the RequestContext in Unit Tests</h3>
<div class="paragraph">
<p>In unit testing it can be necessary to test with attached and also with
detached JPA entities. A very common approach for JPA is the
@@ -451,8 +455,8 @@ EntityManager. Since a single unit test
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_attach_a_requestcontext_to_a_new_thread_in_ee">Attach a RequestContext to a New Thread in EE</h4>
+<div class="sect2">
+<h3 id="_attach_a_requestcontext_to_a_new_thread_in_ee">Attach a RequestContext to a New Thread in EE</h3>
<div class="paragraph">
<p>Accessing the <code>@RequestScoped</code> bean in a new thread will result in a
<code>ContextNotActiveException</code>. The RequestContext usually gets started
@@ -488,8 +492,10 @@ business services in for example a Quart
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_embedded_servlet_support">Embedded Servlet Support</h3>
+</div>
+<div class="sect1">
+<h2 id="_embedded_servlet_support">Embedded Servlet Support</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>From DeltaSpike 1.0.2, you can use DeltaSpike to power embedded Servlet
runtimes. This work is done via Servlet Listeners. The configuration is
@@ -515,8 +521,8 @@ cdiContainer.boot();
cdiContainer.getContextControl().startContexts();</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_jetty">Jetty</h4>
+<div class="sect2">
+<h3 id="_jetty">Jetty</h3>
<div class="paragraph">
<p>For Jetty, you need to add an <code>EventListener</code> which will be your
<code>CdiServletRequestListener</code>. The object must be instantiated. This must
@@ -536,8 +542,8 @@ server.start();</code></pre>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_undertow">Undertow</h4>
+<div class="sect2">
+<h3 id="_undertow">Undertow</h3>
<div class="paragraph">
<p>For Undertow, you register the <code>CdiServletRequestListener</code> via
<code>ListenerInfo</code> by passing in the class to their builders. Then you add
@@ -563,8 +569,8 @@ server.start();</code></pre>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_tomcat">Tomcat</h4>
+<div class="sect2">
+<h3 id="_tomcat">Tomcat</h3>
<div class="paragraph">
<p>For Tomcat, you need to register the <code>CdiServletContextListener</code> instead
of the <code>CdiServletRequestListener</code>. It is added as an
@@ -586,7 +592,6 @@ tomcat.start();</code></pre>
</div>
</div>
</div>
-</div>
</div>
</div>
@@ -605,33 +610,29 @@ tomcat.start();</code></pre>
<div class="fallback-toc">
<ul class="sectlevel1">
<li><a href="#_overview">Overview</a></li>
-<li><a href="#_configure_your_projects">Configure Your Projects</a>
+<li><a href="#_project_setup">Project Setup</a>
<ul class="sectlevel2">
<li><a href="#_enable_cdi_for_your_java_environment">Enable CDI For Your Java Environment</a></li>
<li><a href="#_declare_container_control_module_dependencies">Declare Container Control Module Dependencies</a></li>
</ul>
</li>
-<li><a href="#_use_the_module_features">Use the Module Features</a>
-<ul class="sectlevel2">
<li><a href="#_start_the_cdi_container_from_your_project">Start the CDI Container from Your Project</a></li>
<li><a href="#_cdicontainer">CdiContainer</a></li>
<li><a href="#_contextcontrol_usage">ContextControl Usage</a></li>
-<li><a href="#_procedure_for_builing_uber_jar">Procedure for builing Uber jar</a>
-<ul class="sectlevel3">
+<li><a href="#_procedure_for_building_an_uber_jar">Procedure for building an uber jar</a>
+<ul class="sectlevel2">
<li><a href="#_restart_the_requestcontext_in_unit_tests">Restart the RequestContext in Unit Tests</a></li>
<li><a href="#_attach_a_requestcontext_to_a_new_thread_in_ee">Attach a RequestContext to a New Thread in EE</a></li>
</ul>
</li>
<li><a href="#_embedded_servlet_support">Embedded Servlet Support</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_jetty">Jetty</a></li>
<li><a href="#_undertow">Undertow</a></li>
<li><a href="#_tomcat">Tomcat</a></li>
</ul>
</li>
</ul>
-</li>
-</ul>
</div>
</div>
Modified: websites/staging/deltaspike/trunk/content/staging/documentation/data.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/staging/documentation/data.html (original)
+++ websites/staging/deltaspike/trunk/content/staging/documentation/data.html Mon Jun 1 09:41:59 2015
@@ -328,7 +328,7 @@ chapters.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_configure_your_projects">Configure Your Projects</h2>
+<h2 id="_project_setup">Project Setup</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <a href="configure.html">Configure DeltaSpike in Your Projects</a>. For Maven-independent projects, see <a href="configure.html#config-maven-indep">Configure DeltaSpike in Maven-independent Projects</a>.</p>
@@ -422,12 +422,6 @@ configure the <code>TransactionStrategy<
<span class="tag"></beans></span></code></pre>
</div>
</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_use_the_module_features">Use the Module Features</h2>
-<div class="sectionbody">
<div class="admonitionblock important">
<table>
<tr>
@@ -441,10 +435,14 @@ annotation-based entities.
</tr>
</table>
</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_core_concepts">Core Concepts</h2>
+<div class="sectionbody">
<div class="sect2">
-<h3 id="_core_concepts">Core Concepts</h3>
-<div class="sect3">
-<h4 id="_repositories">Repositories</h4>
+<h3 id="_repositories">Repositories</h3>
<div class="paragraph">
<p>With the DeltaSpike Data module, it is possible to make a repository out
of basically any abstract class or interface (using a concrete class
@@ -474,8 +472,8 @@ classes or interfaces this is the only w
entity the repository relates to. In order to simplify this, DeltaSpike
Data provides several base types.</p>
</div>
-<div class="sect4">
-<h5 id="_the_code_entityrepository_code_interface">The <code>EntityRepository</code> Interface</h5>
+<div class="sect3">
+<h4 id="_the_code_entityrepository_code_interface">The <code>EntityRepository</code> Interface</h4>
<div class="paragraph">
<p>Although mainly intended to hold complex query logic, working with both
a repository and an <code>EntityManager</code> in the service layer might
@@ -549,9 +547,8 @@ is introduced, as we see in the next cha
</tr>
</table>
</div>
-</div>
<div class="sect4">
-<h5 id="_the_code_abstractentityrepository_code_class">The <code>AbstractEntityRepository</code> Class</h5>
+<h5 id="_the_abstractentityrepository_class">The AbstractEntityRepository Class</h5>
<div class="paragraph">
<p>This class is an implementation of the <code>EntityRepository</code> interface and
provides additional functionality when custom query logic needs also to
@@ -574,8 +571,9 @@ be implemented in the repository.</p>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_deactivating_repositories">Deactivating Repositories</h4>
+</div>
+<div class="sect2">
+<h3 id="_deactivating_repositories">Deactivating Repositories</h3>
<div class="paragraph">
<p>Repositories can be deactivated creating a <a href="spi.html#_classdeactivator">ClassDeactivator</a>.</p>
</div>
@@ -599,8 +597,8 @@ be implemented in the repository.</p>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_using_multiple_code_entitymanager_code">Using Multiple <code>EntityManager</code></h4>
+<div class="sect2">
+<h3 id="_using_multiple_entitymanagers">Using Multiple EntityManagers</h3>
<div class="paragraph">
<p>While most applications will run just fine with a single
<code>EntityManager</code>, there might be setups where multiple data sources are
@@ -635,8 +633,8 @@ the <code>@EntityManagerConfig</code> an
interface.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_other_code_entitymanager_code_methods">Other <code>EntityManager</code> Methods</h4>
+<div class="sect2">
+<h3 id="_other_entitymanager_methods">Other EntityManager Methods</h3>
<div class="paragraph">
<p>While the <code>EntityRepository</code> methods should cover most interactions
normally done with an <code>EntityManager</code>, for some specific cases it might
@@ -656,16 +654,18 @@ a JPA 2.0 <code>EntityManager</code>:</p
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_query_method_expressions">Query Method Expressions</h3>
+</div>
+<div class="sect1">
+<h2 id="_query_method_expressions">Query Method Expressions</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>Good naming is a difficult aspects in software engineering. A good
method name usually makes comments unnecessary and states exactly what
the method does. And with method expressions, the method name is
actually the implementation!</p>
</div>
-<div class="sect3">
-<h4 id="_using_method_expressions">Using Method Expressions</h4>
+<div class="sect2">
+<h3 id="_using_method_expressions">Using Method Expressions</h3>
<div class="paragraph">
<p>Let’s start by looking at a (simplified for readability) example:</p>
</div>
@@ -809,8 +809,8 @@ expressions:</p>
you will notice early in case you have a typo in those expressions.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_query_ordering">Query Ordering</h4>
+<div class="sect2">
+<h3 id="_query_ordering">Query Ordering</h3>
<div class="paragraph">
<p>Beside comparators it is also possible to sort queries by using the
<code>OrderBy</code> keyword, followed by the attribute name and the direction
@@ -828,8 +828,8 @@ you will notice early in case you have a
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_nested_properties">Nested Properties</h4>
+<div class="sect2">
+<h3 id="_nested_properties">Nested Properties</h3>
<div class="paragraph">
<p>To create a comparison on a nested property, the traversal parts can be
separated by a <code>_</code>:</p>
@@ -846,8 +846,8 @@ separated by a <code>_</code>:</p>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_query_options">Query Options</h4>
+<div class="sect2">
+<h3 id="_query_options">Query Options</h3>
<div class="paragraph">
<p>DeltaSpike supports query options on method expressions. If you want to
page a query, you can change the first result as well as the maximum
@@ -865,8 +865,8 @@ number of results returned:</p>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_method_prefix">Method Prefix</h4>
+<div class="sect2">
+<h3 id="_method_prefix">Method Prefix</h3>
<div class="paragraph">
<p>In case the <code>findBy</code> prefix does not comply with your team conventions,
this can be adapted:</p>
@@ -884,8 +884,10 @@ this can be adapted:</p>
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_query_annotations">Query Annotations</h3>
+</div>
+<div class="sect1">
+<h2 id="_query_annotations">Query Annotations</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>While method expressions are fine for simple queries, they will often
reach their limit once things get slightly more complex. Another aspect
@@ -894,8 +896,8 @@ best performance is over named queries.
cases, the DeltaSpike Data module supports also annotating methods for
more control on the generated query.</p>
</div>
-<div class="sect3">
-<h4 id="_using_query_annotations">Using Query Annotations</h4>
+<div class="sect2">
+<h3 id="_using_query_annotations">Using Query Annotations</h3>
<div class="paragraph">
<p>The simples way to define a specific query is by annotating a method and
providing the JPQL query string which has to be executed. In code, this
@@ -1007,8 +1009,8 @@ not JPQL but plain SQL:</p>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_annotation_options">Annotation Options</h4>
+<div class="sect2">
+<h3 id="_annotation_options">Annotation Options</h3>
<div class="paragraph">
<p>Beside providing a query string or reference, the <code>@Query</code> annotation
provides also two more attributes:</p>
@@ -1051,8 +1053,8 @@ provides also two more attributes:</p>
<p>Note that these options can also be applied to method expressions.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_query_options_2">Query Options</h4>
+<div class="sect2">
+<h3 id="_query_options_2">Query Options</h3>
<div class="paragraph">
<p>All the query options you have seen so far are more or less static. But
sometimes you might want to apply certain query options dynamically. For
@@ -1105,8 +1107,8 @@ supported for Hibernate, EclipseLink and
expressions.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_pagination">Pagination</h4>
+<div class="sect2">
+<h3 id="_pagination">Pagination</h3>
<div class="paragraph">
<p>We introduced the <code>QueryResult</code> type in the last chapter, which can also
be used for pagination:</p>
@@ -1127,8 +1129,8 @@ QueryResult<Person> paged = person
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_bulk_operations">Bulk Operations</h4>
+<div class="sect2">
+<h3 id="_bulk_operations">Bulk Operations</h3>
<div class="paragraph">
<p>While reading entities and updating them one by one might be fine for
many use cases, applying bulk updates or deletes is also a common usage
@@ -1153,8 +1155,8 @@ marking annotation <code>@Modifying</cod
the number of entities affected by the bulk operation.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_optional_query_results">Optional Query Results</h4>
+<div class="sect2">
+<h3 id="_optional_query_results">Optional Query Results</h3>
<div class="paragraph">
<p>The JPA spec requires to throw exceptions in case the
<code>getSingleResult()</code> method does either return no or more than one
@@ -1168,8 +1170,8 @@ sense for the current usecase. While the
aligned with JPA, it is also possible to request optional query results.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_zero_or_one_result">Zero or One Result</h4>
+<div class="sect2">
+<h3 id="_zero_or_one_result">Zero or One Result</h3>
<div class="paragraph">
<p>With this option, the query returns <code>null</code> instead of throwing a
<code>NoResultException</code> when there is no result returned. It is usable with
@@ -1199,8 +1201,8 @@ with the <code>SingleResultType.OPTIONAL
<code>NonUniqueResultException</code> is still thrown.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_any_result">Any Result</h4>
+<div class="sect2">
+<h3 id="_any_result">Any Result</h3>
<div class="paragraph">
<p>If the caller does not really mind what kind if result is returned, it is
also possible to request any result from the query. If there is no
@@ -1232,8 +1234,10 @@ annotations, the <code>singleResult</cod
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_transactions">Transactions</h3>
+</div>
+<div class="sect1">
+<h2 id="_transactions">Transactions</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>If you call any method expression, <code>@Query</code>-annotated method or a method
from the <code>EntityRepository</code>, the repository will figure out if a
@@ -1297,10 +1301,12 @@ their queries in the <code>transactional
implementation can be, for example, in an anonymous class).</p>
</div>
</div>
+</div>
+<div class="sect1">
+<h2 id="_extensions">Extensions</h2>
+<div class="sectionbody">
<div class="sect2">
-<h3 id="_extensions">Extensions</h3>
-<div class="sect3">
-<h4 id="_query_delegates">Query Delegates</h4>
+<h3 id="_query_delegates">Query Delegates</h3>
<div class="paragraph">
<p>While repositories defines several base interfaces, there might still be
the odd convenience method that is missing. This is actually intentional
@@ -1328,8 +1334,8 @@ repositories:</p>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_implementing_the_query_delegate">Implementing the Query Delegate</h4>
+<div class="sect2">
+<h3 id="_implementing_the_query_delegate">Implementing the Query Delegate</h3>
<div class="paragraph">
<p>The first step is to define an interface which contains the extra
methods for your repositories (as shown above):</p>
@@ -1377,8 +1383,10 @@ selected.</p>
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_mapping">Mapping</h3>
+</div>
+<div class="sect1">
+<h2 id="_mapping">Mapping</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>While repositories are primarily intended to work with Entities, it
might be preferable in some cases to have an additional mapping layer on
@@ -1474,8 +1482,8 @@ is mandatory. Also it is up to the mappe
correctly (in this example, a conversion from a <code>PersonDto</code> parameter to
<code>Person</code> entity and from <code>PersonId</code> to <code>Long</code> is necessary).</p>
</div>
-<div class="sect3">
-<h4 id="_simple_mappings">Simple Mappings</h4>
+<div class="sect2">
+<h3 id="_simple_mappings">Simple Mappings</h3>
<div class="paragraph">
<p>In many cases it is just required to map a DTO object back and forth. For
this case, the <code>SimpleQueryInOutMapperBase</code> class can be subclassed,
@@ -1518,8 +1526,10 @@ entity).</p>
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_jpa_criteria_api_support">JPA Criteria API Support</h3>
+</div>
+<div class="sect1">
+<h2 id="_jpa_criteria_api_support">JPA Criteria API Support</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>Beside automatic query generation, the DeltaSpike Data module also
provides a DSL-like API to create JPA 2 Criteria queries. It takes
@@ -1548,8 +1558,8 @@ strongest point is certainly its type sa
of readability. We’re trying to provide a middle way here. A less
powerful API, but still type safe and readable.</p>
</div>
-<div class="sect3">
-<h4 id="_api_usage">API Usage</h4>
+<div class="sect2">
+<h3 id="_api_usage">API Usage</h3>
<div class="paragraph">
<p>The API is centered around the Criteria class and is targeted to provide
a fluent interface to write criteria queries:</p>
@@ -1681,8 +1691,8 @@ method is called. This creates a JPA Typ
repository entity. If required, further processing can be applied here.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_joins">Joins</h4>
+<div class="sect2">
+<h3 id="_joins">Joins</h3>
<div class="paragraph">
<p>For simple cases, restricting on the repository entity only works out
fine, but once the Data model gets more complicated, the query will have
@@ -1731,8 +1741,8 @@ are slighly simpler as seen in the next
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_boolean_operators">Boolean Operators</h4>
+<div class="sect2">
+<h3 id="_boolean_operators">Boolean Operators</h3>
<div class="paragraph">
<p>By default, all query operators are concatenated as an and conjunction
to the query. The DeltaSpike criteria API also allows to add groups of
@@ -1761,8 +1771,8 @@ disjunctions.</p>
</div>
</div>
</div>
-<div class="sect3">
-<h4 id="_selections">Selections</h4>
+<div class="sect2">
+<h3 id="_selections">Selections</h3>
<div class="paragraph">
<p>It might not always be appropriate to retrieve full entities - you might
also be interested in scalar values or by modified entity attributes.
@@ -1872,8 +1882,10 @@ selection clause:</p>
</table>
</div>
</div>
-<div class="sect2">
-<h3 id="_auditing">Auditing</h3>
+</div>
+<div class="sect1">
+<h2 id="_auditing">Auditing</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>A common requirement for entities is tracking what is being done with
them. DeltaSpike provides a convenient way to support this requirement.</p>
@@ -1891,8 +1903,8 @@ requirement for your audits, have a look
</tr>
</table>
</div>
-<div class="sect3">
-<h4 id="_activating_auditing">Activating Auditing</h4>
+<div class="sect2">
+<h3 id="_activating_auditing">Activating Auditing</h3>
<div class="paragraph">
<p>DeltaSpike uses an entity listener to update auditing data before
entities get created or update. The entity listener must be activated
@@ -1938,14 +1950,14 @@ module. Alternatively, also the per enti
XML.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_using_auditing_annotations">Using Auditing Annotations</h4>
+<div class="sect2">
+<h3 id="_using_auditing_annotations">Using Auditing Annotations</h3>
<div class="paragraph">
<p>All that has to be done now is annotating the entity properties which
are used to audit the entity.</p>
</div>
-<div class="sect4">
-<h5 id="_updating_timestamps">Updating Timestamps</h5>
+<div class="sect3">
+<h4 id="_updating_timestamps">Updating Timestamps</h4>
<div class="paragraph">
<p>To keep track on creation and modification times, following annotations
can be used:</p>
@@ -1981,8 +1993,8 @@ the annotation can be customized:</p>
</div>
</div>
</div>
-<div class="sect4">
-<h5 id="_who_s_changing_my_entities">Who’s Changing My Entities?</h5>
+<div class="sect3">
+<h4 id="_who_s_changing_my_entities">Who’s Changing My Entities?</h4>
<div class="paragraph">
<p>Beside keeping track of when a change has happened, it is also often
critical to track who’s responsible for the change. Annotate a user
@@ -2049,7 +2061,6 @@ provider when persisting / updating the
</div>
</div>
</div>
-</div>
</div>
</div>
@@ -2079,30 +2090,31 @@ provider when persisting / updating the
<div class="fallback-toc">
<ul class="sectlevel1">
<li><a href="#_overview">Overview</a></li>
-<li><a href="#_configure_your_projects">Configure Your Projects</a>
+<li><a href="#_project_setup">Project Setup</a>
<ul class="sectlevel2">
<li><a href="#_1_declare_data_module_dependencies">1. Declare Data Module Dependencies</a></li>
<li><a href="#_2_complete_additional_java_environment_configuration">2. Complete Additional Java Environment Configuration</a></li>
<li><a href="#_3_complete_additional_project_configuration">3. Complete Additional Project Configuration</a></li>
</ul>
</li>
-<li><a href="#_use_the_module_features">Use the Module Features</a>
-<ul class="sectlevel2">
<li><a href="#_core_concepts">Core Concepts</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_repositories">Repositories</a>
+<ul class="sectlevel3">
+<li><a href="#_the_code_entityrepository_code_interface">The <code>EntityRepository</code> Interface</a>
<ul class="sectlevel4">
-<li><a href="#_the_code_entityrepository_code_interface">The <code>EntityRepository</code> Interface</a></li>
-<li><a href="#_the_code_abstractentityrepository_code_class">The <code>AbstractEntityRepository</code> Class</a></li>
+<li><a href="#_the_abstractentityrepository_class">The AbstractEntityRepository Class</a></li>
+</ul>
+</li>
</ul>
</li>
<li><a href="#_deactivating_repositories">Deactivating Repositories</a></li>
-<li><a href="#_using_multiple_code_entitymanager_code">Using Multiple <code>EntityManager</code></a></li>
-<li><a href="#_other_code_entitymanager_code_methods">Other <code>EntityManager</code> Methods</a></li>
+<li><a href="#_using_multiple_entitymanagers">Using Multiple EntityManagers</a></li>
+<li><a href="#_other_entitymanager_methods">Other EntityManager Methods</a></li>
</ul>
</li>
<li><a href="#_query_method_expressions">Query Method Expressions</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_using_method_expressions">Using Method Expressions</a></li>
<li><a href="#_query_ordering">Query Ordering</a></li>
<li><a href="#_nested_properties">Nested Properties</a></li>
@@ -2111,7 +2123,7 @@ provider when persisting / updating the
</ul>
</li>
<li><a href="#_query_annotations">Query Annotations</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_using_query_annotations">Using Query Annotations</a></li>
<li><a href="#_annotation_options">Annotation Options</a></li>
<li><a href="#_query_options_2">Query Options</a></li>
@@ -2124,18 +2136,18 @@ provider when persisting / updating the
</li>
<li><a href="#_transactions">Transactions</a></li>
<li><a href="#_extensions">Extensions</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_query_delegates">Query Delegates</a></li>
<li><a href="#_implementing_the_query_delegate">Implementing the Query Delegate</a></li>
</ul>
</li>
<li><a href="#_mapping">Mapping</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_simple_mappings">Simple Mappings</a></li>
</ul>
</li>
<li><a href="#_jpa_criteria_api_support">JPA Criteria API Support</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_api_usage">API Usage</a></li>
<li><a href="#_joins">Joins</a></li>
<li><a href="#_boolean_operators">Boolean Operators</a></li>
@@ -2143,17 +2155,15 @@ provider when persisting / updating the
</ul>
</li>
<li><a href="#_auditing">Auditing</a>
-<ul class="sectlevel3">
+<ul class="sectlevel2">
<li><a href="#_activating_auditing">Activating Auditing</a></li>
<li><a href="#_using_auditing_annotations">Using Auditing Annotations</a>
-<ul class="sectlevel4">
+<ul class="sectlevel3">
<li><a href="#_updating_timestamps">Updating Timestamps</a></li>
<li><a href="#_who_s_changing_my_entities">Who’s Changing My Entities?</a></li>
</ul>
</li>
</ul>
-</li>
-</ul>
</li>
</ul>
</div>
Modified: websites/staging/deltaspike/trunk/content/staging/documentation/jpa.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/staging/documentation/jpa.html (original)
+++ websites/staging/deltaspike/trunk/content/staging/documentation/jpa.html Mon Jun 1 09:41:59 2015
@@ -281,7 +281,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect1">
-<h2 id="_configure_your_projects">Configure Your Projects</h2>
+<h2 id="_project_setup">Project Setup</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The configuration information provided here is for Maven-based projects and it assumes that you have already declared the DeltaSpike version and DeltaSpike Core module for your projects, as detailed in <a href="configure.html">Configure DeltaSpike in Your Projects</a>. For Maven-independent projects, see <a href="configure.html#config-maven-indep">Configure DeltaSpike in Maven-independent Projects</a>.</p>
@@ -328,27 +328,27 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect1">
-<h2 id="_use_the_module_features">Use the Module Features</h2>
+<h2 id="__transactional">@Transactional</h2>
<div class="sectionbody">
-<div class="sect2">
-<h3 id="__transactional">@Transactional</h3>
<div class="paragraph">
-<p>This annotation is an alternative to transactional EJBs which allows to
-execute a method within a transaction. Before it is possible to start
+<p>This annotation is an alternative to transactional EJBs and enables the execution
+of a method within a transaction. Before it is possible to start
using the annotation, it is required to implement a CDI producer for an
<code>EntityManager</code> and it is needed to inject the <code>EntityManager</code> in the
bean which uses <code>@Transactional</code>. As shown later on, it is also possible
-to use multiple qualifiers for using different `EntityManager`s.</p>
+to use multiple qualifiers for using different EntityManagers.</p>
</div>
+<div class="sect2">
+<h3 id="_basic_usage">Basic usage</h3>
<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 is possible to use a special scope called
-<code>@TransactionScoped</code> provided by the same DeltaSpike module.</p>
+the corresponding disposer method. Producing it as request scoped bean
+means that the disposer method will be called on finishing the request.
+Alternatively it is possible to use a special scope called
+<a href="#__transactionscoped"><code>@TransactionScoped</code></a>.</p>
</div>
<div class="listingblock">
-<div class="title">Producer for the Default EntityManager (<strong>no EE-Server</strong>)</div>
+<div class="title">Producer for the Default EntityManager (non-EE server)</div>
<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>
@@ -375,7 +375,7 @@ As an alternative it is possible to use
</div>
</div>
<div class="listingblock">
-<div class="title">Producer for the Default EntityManager (<strong>EE-Server</strong>)</div>
+<div class="title">Producer for the Default EntityManager (EE server)</div>
<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>
@@ -406,7 +406,7 @@ As an alternative it is possible to use
the example above.</p>
</div>
<div class="listingblock">
-<div class="title">Beans with Transactional Method</div>
+<div class="title">Bean with a Transactional Method</div>
<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>
@@ -461,60 +461,156 @@ the example above.</p>
}</code></pre>
</div>
</div>
+</div>
+<div class="sect2">
+<h3 id="_multiple_entitymanagers">Multiple EntityManagers</h3>
+<div class="paragraph">
+<p>The default qualifier for <code>@Transactional</code> is <code>@Any</code> whereby a transaction gets started for every injected entity manager. Besides such simple usages, it is also possible to access multiple persistence units in parallel using qualifiers.</p>
+</div>
+<div class="paragraph">
+<p>First, the EntityManagers or EntityManagerFactories must be obtained from the JPA subsystem, then EntityManagers must be made available as CDI beans and finally injected into <code>@Transactional</code> beans for usage.</p>
+</div>
+<div class="sect3">
+<h4 id="_obtaining_entitymanagers_from_jpa">Obtaining EntityManagers from JPA</h4>
<div class="paragraph">
-<p>Besides such simple usages, it is 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>
+<p>In EE managed environments the EntityManager can be obtained directly or through an EntityManagerFactory using standard JPA annotations <code>@PersistenceContext</code> for an EntityManager or <code>@PersistenceUnit</code> for an EntityManagerFactory.</p>
</div>
<div class="listingblock">
-<div class="title">Producer for Multiple Entity Managers (+ Usage)</div>
+<div class="title">JPA Managed EntityManager</div>
<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>
-{
+<pre class="CodeRay highlight"><code data-lang="java"><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="comment">// ...</span>
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>An alternative for non-EE environments is available through DeltaSpike’s <code>@PersistenceUnitName</code> qualifier allowing to inject EntityManagerFactories.</p>
+</div>
+<div class="listingblock">
+<div class="title">Unmanaged EntityManagerFactory</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span> {
+
+ <span class="annotation">@Inject</span>
+ <span class="annotation">@PersistenceUnitName</span>(<span class="string"><span class="delimiter">"</span><span class="content">puA</span><span class="delimiter">"</span></span>)
+ <span class="directive">private</span> EntityManagerFactory emfA;
+
+ <span class="annotation">@Inject</span>
+ <span class="annotation">@PersistenceUnitName</span>(<span class="string"><span class="delimiter">"</span><span class="content">puB</span><span class="delimiter">"</span></span>)
+ <span class="directive">private</span> EntityManagerFactory emfB;
+
+ <span class="comment">// ...</span>
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Obtaining an EntityManager from an EntityManagerFactory is just a matter of calling <code>emfA.createEntityManager()</code>.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_producing_multiple_entitymanagers">Producing Multiple EntityManagers</h4>
+<div class="paragraph">
+<p>There are several ways to make multiple entity managers available for use in <code>@Transactional</code> methods, each suitable for a different situation.</p>
+</div>
+<div class="paragraph">
+<p>The simplest method employs a producer and a disposer for each EntityManager.</p>
+</div>
+<div class="listingblock">
+<div class="title">Deciding using qualifiers</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span> {
+
+ <span class="comment">// ...entity managers or factories injected here</span>
+
<span class="annotation">@Produces</span>
- <span class="annotation">@First</span>
- <span class="annotation">@RequestScoped</span>
- <span class="directive">protected</span> EntityManager createFirstEntityManager()
+ <span class="annotation">@RequestScoped</span> <span class="comment">// or other</span>
+ <span class="annotation">@DbA</span> <span class="comment">//custom qualifier annotation</span>
+ <span class="directive">public</span> EntityManager createEntityManagerA()
{
- <span class="keyword">return</span> <span class="local-variable">this</span>.firstEntityManager;
+ <span class="keyword">return</span> emfA.createEntityManager();
}
- <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="directive">public</span> <span class="type">void</span> closeEmA(<span class="annotation">@Disposes</span> <span class="annotation">@DbA</span> EntityManager em)
{
- <span class="keyword">if</span> (entityManager.isOpen())
- {
- entityManager.close();
- }
+ em.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="annotation">@DbB</span> <span class="comment">//custom qualifier annotation</span>
+ <span class="directive">public</span> EntityManager createEntityManagerB()
{
- <span class="keyword">return</span> <span class="local-variable">this</span>.secondEntityManager;
+ <span class="keyword">return</span> emfB.createEntityManager();
}
- <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="directive">public</span> <span class="type">void</span> closeEmB(<span class="annotation">@Disposes</span> <span class="annotation">@DbB</span> EntityManager em)
{
- <span class="keyword">if</span> (entityManager.isOpen())
- {
- entityManager.close();
- }
+ em.close();
}
-}
-<span class="comment">//...</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">FirstLevelTransactionBean</span>
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If there’s the need to decide dynamically on which EntityManager should be used when it’s possible to use the standard CDI facility of <code>InjectionPoint</code> to get information about the injection points and produce different EntityManagers with just one producer method.</p>
+</div>
+<div class="listingblock">
+<div class="title">Deciding using InjectionPoint</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span> {
+
+ <span class="comment">// ...entity managers or factories injected here</span>
+
+ <span class="annotation">@Produces</span>
+ <span class="directive">protected</span> EntityManager createEntityManager(InjectionPoint injectionPoint)
+ {
+ CustomQualifier customQualifier = injectionPoint.getAnnotated().getAnnotation(CustomQualifier.class);
+ <span class="keyword">return</span> selectEntityManager(customQualifier); <span class="comment">//selects firstEntityManager or secondEntityManager based on the details provided by CustomQualifier</span>
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The information necessary to make the decision about the EntityManager appropriate for the current situation and injection point may be available elsewhere, for example in a custom context.</p>
+</div>
+<div class="listingblock">
+<div class="title">Deciding using anything else</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">EntityManagerProducer</span> {
+
+ <span class="comment">// ...entity managers or factories injected here</span>
+
+ <span class="annotation">@Inject</span>
+ <span class="directive">private</span> CustomDatabaseContext customDatabaseContext;
+
+ <span class="annotation">@Produces</span>
+ <span class="directive">protected</span> EntityManager createEntityManager()
+ {
+ <span class="keyword">if</span> (customDatabaseContext.usePrimaryDb()) {
+ <span class="keyword">return</span> firstEntityManager;
+ }
+ <span class="keyword">return</span> secondEntityManager;
+ }
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_using_transactions_with_multiple_entitymanagers">Using transactions with multiple EntityManagers</h4>
+<div class="paragraph">
+<p>One use case for multiple EntityManagers is their usage in nested transactions. When a transactional method is called from within a transactional method, it joins the existing transaction.</p>
+</div>
+<div class="listingblock">
+<div class="title">Nested transactions with multiple EntityManagers</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><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;
@@ -530,7 +626,6 @@ change this default behaviour.</p>
}
}
-<span class="comment">//...</span>
<span class="directive">public</span> <span class="type">class</span> <span class="class">NestedTransactionBean</span>
{
<span class="annotation">@Inject</span>
@@ -545,11 +640,10 @@ change this default behaviour.</p>
</div>
</div>
<div class="paragraph">
-<p>The following example shows how to use only the specified
-<code>EntityManager</code>/s</p>
+<p>It’s also easy to use multiple EntityManagers in the same bean in different transactional methods. By default, a <code>@Transactional</code> method would enroll all of the EntityManagers in the transaction. By using <code>@Transactional(qualifier=…​)</code> it’s easy to choose individual EntityManagers for each transactional method.</p>
</div>
<div class="listingblock">
-<div class="title">Activating Entity Managers Manually</div>
+<div class="title">Selecting individual EntityManagers for a transactional method</div>
<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>
{
@@ -563,62 +657,13 @@ change this default behaviour.</p>
<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="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="directive">public</span> <span class="type">void</span> executeInFirstTransaction() {...}
<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="listingblock">
-<div class="title">Joining Existing Transaction in Nested Call</div>
-<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>
- }
+ <span class="directive">public</span> <span class="type">void</span> executeInFirstAndSecondTransaction() {...}
}</code></pre>
</div>
</div>
@@ -630,8 +675,12 @@ a different <code>EntityManager</code>.
immediate rollback.</p>
</div>
</div>
-<div class="sect2">
-<h3 id="__transactionscoped">@TransactionScoped</h3>
+</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
@@ -639,14 +688,10 @@ this scope for the <code>EntityManager</
<code>EntityManager</code> will be closed after leaving the method annotated with
<code>@Transactional</code>.</p>
</div>
-<div class="paragraph">
-<div class="title">Producer for the Default EntityManager which should be Used Only for One</div>
-<p>Transaction</p>
-</div>
<div class="listingblock">
+<div class="title">Using a transaction-scoped EntityManager</div>
<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>
+<pre class="CodeRay highlight"><code data-lang="java"><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>
@@ -670,8 +715,10 @@ this scope for the <code>EntityManager</
</div>
</div>
</div>
-<div class="sect2">
-<h3 id="_extended_persistence_contexts">Extended Persistence Contexts</h3>
+</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 is not
@@ -690,7 +737,7 @@ However, if you really need this approac
your detached entities, it is pretty simple to add this functionality.</p>
</div>
<div class="listingblock">
-<div class="title">Usage of a Simple <code>ExtendedEntityManager</code></div>
+<div class="title">Usage of a Simple extended EntityManager</div>
<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>
@@ -702,7 +749,7 @@ your detached entities, it is pretty sim
producer-method:</p>
</div>
<div class="listingblock">
-<div class="title">Producer for the Default Extended-<code>EntityManager</code> (<strong>no EE-Server</strong>)</div>
+<div class="title">Producer for an extended EntityManager (non-EE server)</div>
<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>
@@ -729,7 +776,7 @@ producer-method:</p>
</div>
</div>
<div class="listingblock">
-<div class="title">Producer for the Default Extended-<code>EntityManager</code> (<strong>EE-Server</strong>)</div>
+<div class="title">Producer for an extended EntityManager (EE server)</div>
<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>
@@ -756,7 +803,7 @@ producer-method:</p>
</div>
</div>
<div class="listingblock">
-<div class="title">Implementation of a Simple <code>ExtendedEntityManager</code></div>
+<div class="title">Implementation of a simple extended EntityManager</div>
<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>
@@ -794,8 +841,10 @@ serialized as well. However, as mentione
such an approach.</p>
</div>
</div>
-<div class="sect2">
-<h3 id="_jta_support">JTA Support</h3>
+</div>
+<div class="sect1">
+<h2 id="_jta_support">JTA Support</h2>
+<div class="sectionbody">
<div class="paragraph">
<p>By default the transaction-type used by <code>@Transactional</code> is
<code>RESOURCE_LOCAL</code>. If you configure <code>transaction-type="JTA"</code> in the
@@ -813,8 +862,8 @@ in the beans.xml which is called
</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
+<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>
@@ -838,7 +887,6 @@ to <code>/META-INF/apache-deltaspike.pro
</div>
</div>
</div>
-</div>
</div>
</div>
@@ -869,21 +917,28 @@ to <code>/META-INF/apache-deltaspike.pro
<div class="fallback-toc">
<ul class="sectlevel1">
<li><a href="#_overview">Overview</a></li>
-<li><a href="#_configure_your_projects">Configure Your Projects</a>
+<li><a href="#_project_setup">Project Setup</a>
<ul class="sectlevel2">
<li><a href="#_1_declare_jpa_module_dependencies">1. Declare JPA Module Dependencies</a></li>
<li><a href="#_2_enable_the_transaction_interceptor">2. Enable the Transaction Interceptor</a></li>
</ul>
</li>
-<li><a href="#_use_the_module_features">Use the Module Features</a>
+<li><a href="#__transactional">@Transactional</a>
<ul class="sectlevel2">
-<li><a href="#__transactional">@Transactional</a></li>
+<li><a href="#_basic_usage">Basic usage</a></li>
+<li><a href="#_multiple_entitymanagers">Multiple EntityManagers</a>
+<ul class="sectlevel3">
+<li><a href="#_obtaining_entitymanagers_from_jpa">Obtaining EntityManagers from JPA</a></li>
+<li><a href="#_producing_multiple_entitymanagers">Producing Multiple EntityManagers</a></li>
+<li><a href="#_using_transactions_with_multiple_entitymanagers">Using transactions with multiple EntityManagers</a></li>
+</ul>
+</li>
+</ul>
+</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>
-</li>
-</ul>
</div>
</div>