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 2020/02/05 11:59:54 UTC
svn commit: r1056146 [7/18] - in /websites/staging/deltaspike/trunk/content:
./ documentation/
Modified: websites/staging/deltaspike/trunk/content/documentation/data.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/documentation/data.html (original)
+++ websites/staging/deltaspike/trunk/content/documentation/data.html Wed Feb 5 11:59:54 2020
@@ -1,2487 +1,2487 @@
-<!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">
- <!-- No caching headers -->
- <meta http-equiv="cache-control" content="no-cache"/>
- <meta http-equiv="pragma" content="no-cache"/>
- <meta http-equiv="expires" content="-1"/>
-
- <title>Data 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">
- <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.1.0/css/font-awesome.min.css" rel="stylesheet">
-
-
-
-
- <!-- Tocify - nice dynamic autoscrolling TOC -->
- <link href="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/stylesheets/jquery.tocify.min.css" rel="stylesheet">
- <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
- <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
- <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/javascripts/jquery.tocify.min.js"></script>
-
-
- <script type="text/javascript">
- $(function () {
- $("#toc").tocify({
- scrollTo: 50,
- extendPage: true,
- context: "#doc-content",
- selectors: "h2,h3,h4,h5"
- });
- $(".fallback-toc").hide();
- });
- </script>
-
-
- <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;
- }
-
- .toc-like {
- border-radius: 6px;
- border: 1px solid #ccc;
- }
-
- .toc-like li {
- line-height: 30px;
- text-indent: 10px;
- }
-
- .toc-like li.custom-toc-header {
- font-weight: bold;
- background: #666;
- color: white;
- cursor: initial !important;
- padding: 5px;
- }
-
- .toc-like li.custom-toc-header a {
- color: white;
- font-style: normal;
- text-shadow: none;
- padding: 0;
- }
-
- .toc-like li.custom-toc-header:hover a {
- background: #666;
- }
-
- .page-title {
- text-align: left;
- }
-
- #doc-content h2,
- #doc-content h3,
- #doc-content h4,
- #doc-content h5,
- #doc-content h6 {
- padding-top: 0;
- margin-top: 25px;
- margin-bottom: 10px;
- line-height: 1.4em;
- }
-
- #doc-content h2 {
- border-bottom: 1px solid lightgrey;
- }
-
-
- </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="../index.html">Apache DeltaSpike</a>
-
- <div class="nav-collapse">
-
-
- <ul class="nav">
- <li><a href="../index.html">Home</a></li>
- <li class="active"><a href="../documentation">Documentation</a></li>
- <li ><a href="../javadoc.html">Javadoc</a></li>
- <li ><a href="../source.html">Source</a></li>
- <li ><a href="../download.html">Download</a></li>
- <li ><a href="../community.html">Community</a></li>
- <!-- <li><a href="./support.html">Support</a></li> -->
- <li ><a href="../news.html">News</a></li>
- </ul>
- </div>
- <!--/.nav-collapse -->
- <form id="search-form" action="https://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-fluid">
-
-
-
- <div class="span8">
- <div class="page-title">
- <h1>Data Module</h1>
- </div>
-
- <div id="doc-content">
- <div class="sect1">
-<h2 id="_overview">Overview</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The Data module provides capabilities for implementing repository patterns and thereby simplifying the repository layer. Repository patterns are ideal for simple queries that require boilerplate code, enabling centralization of query logic and consequently reducing code duplication and improving testability.</p>
-</div>
-<div class="paragraph">
-<p>The code sample below gives you a quick overview on the common usage
-scenarios of the data module:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> findByAgeBetweenAndGender(<span class="type">int</span> minAge, <span class="type">int</span> maxAge, Gender gender);
-
- <span class="annotation">@Query</span>(<span class="string"><span class="delimiter">"</span><span class="content">select p from Person p where p.ssn = ?1</span><span class="delimiter">"</span></span>)
- Person findBySSN(<span class="predefined-type">String</span> ssn);
-
- <span class="annotation">@Query</span>(named=Person.BY_FULL_NAME)
- Person findByFullName(<span class="predefined-type">String</span> firstName, <span class="predefined-type">String</span> lastName);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>As you see in the sample, there are several usage scenarios outlined
-here:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Declare a method which executes a query by simply translating its name
-and parameters into a query.</p>
-</li>
-<li>
-<p>Declare a method which automatically executes a given JPQL query
-string with parameters.</p>
-</li>
-<li>
-<p>Declare a method which automatically executes a named query with
-parameters.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The implementation of the method is done automatically by the CDI
-extension. A client can declare a dependency to the interface only. The
-details on how to use those features are outlined in the following
-chapters.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<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>
-</div>
-<div class="sect2">
-<h3 id="_1_declare_data_module_dependencies">1. Declare Data Module Dependencies</h3>
-<div class="paragraph">
-<p>Add the Data module to the list of dependencies in the project <code>pom.xml</code> file using this code snippet:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><dependency></span>
- <span class="tag"><groupId></span>org.apache.deltaspike.modules<span class="tag"></groupId></span>
- <span class="tag"><artifactId></span>deltaspike-data-module-api<span class="tag"></artifactId></span>
- <span class="tag"><version></span>${deltaspike.version}<span class="tag"></version></span>
- <span class="tag"><scope></span>compile<span class="tag"></scope></span>
-<span class="tag"></dependency></span>
-
-<span class="tag"><dependency></span>
- <span class="tag"><groupId></span>org.apache.deltaspike.modules<span class="tag"></groupId></span>
- <span class="tag"><artifactId></span>deltaspike-data-module-impl<span class="tag"></artifactId></span>
- <span class="tag"><version></span>${deltaspike.version}<span class="tag"></version></span>
- <span class="tag"><scope></span>runtime<span class="tag"></scope></span>
-<span class="tag"></dependency></span></code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Or if you’re using Gradle, add these dependencies to your <code>build.gradle</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code> runtime 'org.apache.deltaspike.modules:deltaspike-data-module-impl'
- compile 'org.apache.deltaspike.modules:deltaspike-data-module-api'</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_2_complete_additional_java_environment_configuration">2. Complete Additional Java Environment Configuration</h3>
-<div class="paragraph">
-<p>The Data module requires a JPA implementation to be available in the Java environment where your projects are deployed.</p>
-</div>
-<div class="paragraph">
-<p>The simplest way using the DeltaSpike Data module is to run your
-application in a Java EE container supporting at least the Java EE6 Web
-Profile. Other configurations like running it inside Tomcat or even a
-Java SE application should be possible - you need to include a JPA
-provider as well as a CDI container to your application manually.</p>
-</div>
-<div class="paragraph">
-<p>As of DeltaSpike v1.4.0, the Data module internally leverages the Proxy module, which wraps ASM 5. No external
-dependencies required, and now we have full support for interceptors on partial beans.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_3_complete_additional_project_configuration">3. Complete Additional Project Configuration</h3>
-<div class="paragraph">
-<p>DeltaSpike Data requires an <code>EntityManager</code> exposed via a CDI producer -
-which is common practice in Java EE6 applications.</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">EntityManagerProducer</span>
-{
- <span class="annotation">@PersistenceUnit</span>
- <span class="directive">private</span> EntityManagerFactory emf;
-
- <span class="annotation">@Produces</span> <span class="comment">// you can also make this @RequestScoped</span>
- <span class="directive">public</span> EntityManager create()
- {
- <span class="keyword">return</span> emf.createEntityManager();
- }
-
- <span class="directive">public</span> <span class="type">void</span> close(<span class="annotation">@Disposes</span> EntityManager em)
- {
- <span class="keyword">if</span> (em.isOpen())
- {
- em.close();
- }
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This allows the <code>EntityManager</code> to be injected over CDI instead of only
-being used with a <code>@PersistenceContext</code> annotation. Using multiple
-<code>EntityManager</code> is explored in more detail in a following section.</p>
-</div>
-<div class="paragraph">
-<p>If you use a JTA DataSource with your <code>EntityManager</code>, you also have to
-configure the <code>TransactionStrategy</code> your repositories use. Adapt your
-<code>beans.xml</code> for this:</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="admonitionblock important">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-important" title="Important"></i>
-</td>
-<td class="content">
-Using the DeltaSpike Data module in an EAR deployment is currently restricted to
-annotation-based entities.
-</td>
-</tr>
-</table>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_core_concepts">Core Concepts</h2>
-<div class="sectionbody">
-<div class="sect2">
-<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
-will work too, but you will not be able to use most of the CDI extension
-features). All that is required is to mark the type as such with a
-simple annotation:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">PersonRepository</span> {
- ...
-}
-
-<span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> {
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The <code>@Repository</code> annotation tells the extension that this is a
-repository for the <code>Person</code> entity. Any method defined on the repository
-will be processed by the framework. The annotation does not require to
-set the entity class (we’ll see later why) but if there are just plain
-classes or interfaces this is the only way to tell the framework what
-entity the repository relates to. In order to simplify this, DeltaSpike
-Data provides several base types.</p>
-</div>
-<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
-unnecessarily clutter code. In order to avoid this for the most common
-cases, DeltaSpike Data provides base types which can be used to replace
-the entity manager.</p>
-</div>
-<div class="paragraph">
-<p>The top base type is the <code>EntityRepository</code> interface, providing common
-methods used with an <code>EntityManager</code>. The following code shows the most
-important methods of the interface:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">EntityRepository</span><E, PK <span class="directive">extends</span> <span class="predefined-type">Serializable</span>>
-{
-
- E save(E entity);
-
- <span class="type">void</span> remove(E entity);
-
- <span class="type">void</span> refresh(E entity);
-
- <span class="type">void</span> flush();
-
- E findBy(PK primaryKey);
-
- <span class="predefined-type">List</span><E> findAll();
-
- <span class="predefined-type">List</span><E> findBy(E example, SingularAttribute<E, ?>... attributes);
-
- <span class="predefined-type">List</span><E> findByLike(E example, SingularAttribute<E, ?>... attributes);
-
- <span class="predefined-type">Long</span> count();
-
- <span class="predefined-type">Long</span> count(E example, SingularAttribute<E, ?>... attributes);
-
- <span class="predefined-type">Long</span> countLike(E example, SingularAttribute<E, ?>... attributes);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The concrete repository can then extend this basic interface. For our
-Person repository, this might look like the following:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- Person findBySsn(<span class="predefined-type">String</span> ssn);
-
-}</code></pre>
-</div>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-Annotations on interfaces do not inherit. If the <code>EntityRepository</code>
-interface is extended by another interface adding some more common
-methods, it is not possible to simply add the annotation there. It needs
-to go on each concrete repository. The same is not true if a base class
-is introduced, as we see in the next chapter.
-</td>
-</tr>
-</table>
-</div>
-<div class="sect4">
-<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
-be implemented in the repository.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> AbstractEntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="directive">public</span> <span class="predefined-type">List</span><Person> findBySSN(<span class="predefined-type">String</span> ssn)
- {
- <span class="keyword">return</span> typedQuery(<span class="string"><span class="delimiter">"</span><span class="content">select p from Person p where p.ssn = ?1</span><span class="delimiter">"</span></span>)
- .setParameter(<span class="integer">1</span>, ssn)
- .getResultList();
- }
-
-}</code></pre>
-</div>
-</div>
-</div>
-</div>
-</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>
-<div class="paragraph">
-<p>The <code>EntityRepository</code> interface implements the <a href="core.html#_deactivatable">Deactivatable</a> interface allowing it to be used in the ClassDeactivator.</p>
-</div>
-<div class="paragraph">
-<p>If your repository does not implement <code>EntityRepository</code> and you want to deactivate it, you will need to implement the <a href="core.html#_deactivatable">Deactivatable</a> interface yourself.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">PersonRepository</span> <span class="directive">implements</span> Deactivatable {
- ...
-}
-
-<span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> Deactivatable {
- ...
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_support_of_transactionscoped_entitymanagers">Support of @TransactionScoped EntityManagers</h3>
-<div class="paragraph">
-<p>For using <code>@TransactionScoped</code> beans like a <code>@TransactionScoped</code>-<code>EntityManager</code>,
-you need to annotate the Data-repository with @Transactional explicitly or one of the beans in the call-hierarchy.
-That’s needed, because the context bound to <code>@TransactionScoped</code> needs to be active,
-before the <code>@TransactionScoped</code>-<code>EntityManager</code> gets resolved (internally).</p>
-</div>
-<div class="paragraph">
-<p>The following examples illustrate the described usages:</p>
-</div>
-<div class="listingblock">
-<div class="title">@TransactionScoped EntityManager combined with a simple repository</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">@Produces</span>
- <span class="annotation">@TransactionScoped</span>
- <span class="directive">public</span> EntityManager create() { ... }
-
- <span class="directive">public</span> <span class="type">void</span> close(<span class="annotation">@Disposes</span> EntityManager em) { ... }
-}
-
-<span class="annotation">@ApplicationScoped</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyService</span>
-{
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> MyRepository myRepository;
-
- <span class="directive">public</span> <span class="type">void</span> create()
- {
- <span class="comment">//...</span>
- <span class="local-variable">this</span>.myRepository.save(...); <span class="comment">//executed in a transaction</span>
- <span class="comment">//...</span>
- }
-}
-
-<span class="annotation">@Transactional</span>
-<span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">MyRepository</span> <span class="directive">extends</span> EntityRepository<MyEntity, <span class="predefined-type">String</span>>
-{
- <span class="comment">//...</span>
-}</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="title">@TransactionScoped EntityManager combined with a simple repository called by a transactional bean</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">@Produces</span>
- <span class="annotation">@TransactionScoped</span>
- <span class="directive">public</span> EntityManager create() { ... }
-
- <span class="directive">public</span> <span class="type">void</span> close(<span class="annotation">@Disposes</span> EntityManager em) { ... }
-}
-
-<span class="annotation">@Transactional</span>
-<span class="annotation">@ApplicationScoped</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyService</span>
-{
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> MyRepository myRepository;
-
- <span class="directive">public</span> <span class="type">void</span> create() <span class="comment">//executed in a transaction</span>
- {
- <span class="comment">//...</span>
- <span class="local-variable">this</span>.myRepository.save(...);
- <span class="comment">//...</span>
- }
-}
-
-<span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">MyRepository</span> <span class="directive">extends</span> EntityRepository<MyEntity, <span class="predefined-type">String</span>>
-{
- <span class="comment">//...</span>
-}</code></pre>
-</div>
-</div>
-</div>
-<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
-used. This can be configured with the <code>EntityManagerConfig</code> annotation:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="annotation">@EntityManagerConfig</span>(entityManagerResolver = CrmEntityManagerResolver.class, flushMode = FlushModeType.COMMIT)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
- ...
-}
-
-<span class="directive">public</span> <span class="type">class</span> <span class="class">CrmEntityManagerResolver</span> <span class="directive">implements</span> EntityManagerResolver
-{
- <span class="annotation">@Inject</span> <span class="annotation">@CustomerData</span> <span class="comment">// Qualifier - assumes a producer is around...</span>
- <span class="directive">private</span> EntityManager em;
-
- <span class="annotation">@Override</span>
- <span class="directive">public</span> EntityManager resolveEntityManager()
- {
- <span class="keyword">return</span> em;
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Again, note that annotations on interfaces do not inherit, so it is not
-possible to create something like a base <code>CrmRepository</code> interface with
-the <code>@EntityManagerConfig</code> and then extending / implementing this
-interface.</p>
-</div>
-</div>
-<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
-still be useful to have one or the other method available. For this
-case, it is possible to extend / implement the <code>EntityManagerDelegate</code>
-interface for repositories, which offers most other methods available in
-a JPA 2.0 <code>EntityManager</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>, EntityManagerDelegate<Person>
-{
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Alternatively, you can extend the <code>FullEntityRepository</code> interface which is a short-hand for extending
-all of <code>EntityRepository</code>, <code>EntityManagerDelegate</code> and <code>CriteriaSupport</code>.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> FullEntityRepository<Person, <span class="predefined-type">Long</span>>
-{
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>For abstract classes, there is a convenience base class <code>AbstractFullEntityRepository</code> which also
-implements <code>EntityManagerDelegate</code> and <code>CriteriaSupport</code> and thus exposes most <code>EntityManager</code> methods:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="directive">abstract</span> PersonRepository <span class="directive">extends</span> AbstractFullEntityRepository<Person, <span class="predefined-type">Long</span>>
-{
- ...
-}</code></pre>
-</div>
-</div>
-</div>
-</div>
-</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="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>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Entity</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Person</span>
-{
-
- <span class="annotation">@Id</span> <span class="annotation">@GeneratedValue</span>
- <span class="directive">private</span> <span class="predefined-type">Long</span> id;
- <span class="directive">private</span> <span class="predefined-type">String</span> name;
- <span class="directive">private</span> <span class="predefined-type">Integer</span> age;
- <span class="directive">private</span> Gender gender;
-
-}
-
-<span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> findByNameLikeAndAgeBetweenAndGender(<span class="predefined-type">String</span> name,
- <span class="type">int</span> minAge, <span class="type">int</span> maxAge, Gender gender);
-
- <span class="type">long</span> countByName(<span class="predefined-type">String</span> name);
-
- <span class="type">void</span> removeByName(<span class="predefined-type">String</span> name);
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Looking at the method name, this can easily be read as query all Persons
-which have a name like the given name parameter, their age is between a
-min and a max age and having a specific gender. The DeltaSpike Data
-module can translate method names following a given format and directly
-generate the query implementation out of it (in EBNF-like form):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre>(Entity|Optional<Entity>|List<Entity>|Stream<Entity>) (prefix)(Property[Comparator]){Operator Property [Comparator]}</pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Or in more concrete words:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>The query method must return an entity, an <code>Optional</code> of an entity, a list of entities or a stream of entities.</p>
-</li>
-<li>
-<p>It must start with the <code>findBy</code> prefix (or related <code>findOptionalBy</code>, <code>findAnyBy</code>, <code>findAll</code>, <code>findFirst</code> or <code>findTop</code>).</p>
-</li>
-<li>
-<p>Followed by a property of the Repository entity and an optional comparator (we’ll define this later). The property will be used in the query together with the comparator. Note that the number of arguments passed to the method depend on the comparator.</p>
-</li>
-<li>
-<p>You can add more blocks of property-comparator which have to be concatenated by a boolean operator. This is either an <code>And</code> or <code>Or</code>.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>You can also use the same way for delete an entity:
-* It must start with the <code>removeBy</code> keyword (or related <code>deleteBy</code>).</p>
-</div>
-<div class="paragraph">
-<p>or for counting:
-* It must start with the <code>countBy</code> keyword.
-* It must return a int or long.</p>
-</div>
-<div class="paragraph">
-<p>Other assumptions taken by the expression evaluator:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>The property name starts lower cased while the property in the expression has an upper cases first character.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Following comparators are currently supported to be used in method
-expressions:</p>
-</div>
-<table class="tableblock frame-all grid-all">
-<colgroup>
-<col>
-<col>
-<col>
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Name</th>
-<th class="tableblock halign-left valign-top"># of Arguments</th>
-<th class="tableblock halign-left valign-top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Equal</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be equal to argument value. If the operator is omitted in the expression, this is assumed as default.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">EqualIgnoreCase</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be equal to argument value (case insensitive).</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">IgnoreCase</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be equal to argument value (case insensitive).</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">NotEqual</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be not equal to argument value.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">NotEqualIgnoreCase</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be not equal to argument value (case insensitive).</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Like</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be like the argument value. Use the %-wildcard in the argument.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">LikeIgnoreCase</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be like the argument value (case insensitive). Use the %-wildcard in the argument.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">NotLike <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be not like the argument value. Use the %-wildcard in the argument.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">GreaterThan</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be greater than argument value.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">GreaterThanEquals</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be greater than or equal to argument value.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">LessThan</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be less than argument value.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">LessThanEquals</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be less than or equal to argument value.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Between</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">2</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be between the two argument values.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">IsNull</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be null.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">IsNotNull</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be non-null.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">In <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be in the list of values given as a single argument. The argument should be of Collection type (e.g. List, Set, etc.).</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">NotIn <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be not in the list of values given as a single argument. The argument should be of Collection type (e.g. List, Set, etc.).</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">True <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be true.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">False <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be false.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Containing <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must be like the argument value. Don’t use the %-wildcard in the argument. The argument value would be automatically wrapped in a pair of %-wildcard.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">StartingWith <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must begin with the argument value. Don’t use the %-wildcard in the argument. A %-wildcard would be added automatically to the end of the argument value.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">EndingWith <code>*</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">1</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Property must end with the argument value. Don’t use the %-wildcard in the argument. A %-wildcard would be added automatically to the start of the argument value.</p></td>
-</tr>
-</tbody>
-</table>
-<div class="paragraph">
-<p><code>*</code> Comparator available since 1.9.1</p>
-</div>
-<div class="paragraph">
-<p>Note that DeltaSpike will validate those expressions during startup, so
-you will notice early in case you have a typo in those expressions.</p>
-</div>
-<div class="paragraph">
-<p>Also note that as of 1.7, the Entity type returned can either by the
-entity defined in this repository, or any other entity in your persistence
-unit, or any primitive type supported by your JPA implementation.</p>
-</div>
-</div>
-<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
-(<code>Asc</code> or <code>Desc</code>).</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> findByLastNameLikeOrderByAgeAscLastNameDesc(<span class="predefined-type">String</span> lastName);
-
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_query_limits">Query Limits</h3>
-<div class="paragraph">
-<p>Starting with Apache DeltaSpike 1.6.2, you can apply query limits using method
-expressions. They can be applied using <code>findFirst</code> or <code>findTop</code> prefixes in a
-method like this:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> findFirst2ByLastNameOrderByAgeAscLastNameDesc(<span class="predefined-type">String</span> lastName);
-
- <span class="predefined-type">List</span><Person> findTop2ByLastNameOrderByAgeAscLastNameDesc(<span class="predefined-type">String</span> lastName);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The number following the prefix indicates how many to limit by, when setting
-the <code>maxResults</code> attribute of the underlying query. You can pair this with
-a <code>@FirstResult</code> parameter to give consistent paging.</p>
-</div>
-<div class="paragraph">
-<p>Query Limits can be applied even when there is no where clause defined by your
-query.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> findAllOrderByAgeAsc();
-
- <span class="predefined-type">List</span><Person> findTop20OrderByLastNameDesc();
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The first query finding all entries ordered by age, and the second only 20
-ordered by last name.</p>
-</div>
-</div>
-<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>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> findByCompany_companyName(<span class="predefined-type">String</span> companyName);
-
-}</code></pre>
-</div>
-</div>
-</div>
-<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
-number of results returned:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> findByNameLike(<span class="predefined-type">String</span> name, <span class="annotation">@FirstResult</span> <span class="type">int</span> start, <span class="annotation">@MaxResults</span> <span class="type">int</span> pageSize);
-
-}</code></pre>
-</div>
-</div>
-</div>
-<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>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(methodPrefix = <span class="string"><span class="delimiter">"</span><span class="content">fetchWith</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="predefined-type">List</span><Person> fetchWithNameLike(<span class="predefined-type">String</span> name, <span class="annotation">@FirstResult</span> <span class="type">int</span> start, <span class="annotation">@MaxResults</span> <span class="type">int</span> pageSize);
-
-}</code></pre>
-</div>
-</div>
-</div>
-</div>
-</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
-is the way you want to use JPA: The recommended approach using JPA for
-best performance is over named queries. To help incorporate those use
-cases, the DeltaSpike Data module supports also annotating methods for
-more control on the generated query.</p>
-</div>
-<div class="sect2">
-<h3 id="_using_query_annotations">Using Query Annotations</h3>
-<div class="paragraph">
-<p>The simplest 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
-looks like the following sample:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="annotation">@Query</span>(<span class="string"><span class="delimiter">"</span><span class="content">select count(p) from Person p where p.age > ?1</span><span class="delimiter">"</span></span>)
- <span class="predefined-type">Long</span> countAllOlderThan(<span class="type">int</span> minAge);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The parameter binding in the query corresponds to the argument index in
-the method.</p>
-</div>
-<div class="paragraph">
-<p>You can also refer to a named query which is constructed and executed
-automatically. The <code>@Query</code> annotation has a named attribute which
-corresponds to the query name:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Entity</span>
-<span class="annotation">@NamedQueries</span>({
- <span class="annotation">@NamedQuery</span>(name = Person.BY_MIN_AGE,
- query = <span class="string"><span class="delimiter">"</span><span class="content">select count(p) from Person p where p.age > ?1 order by p.age asc</span><span class="delimiter">"</span></span>)
-})
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Person</span>
-{
-
- <span class="directive">public</span> <span class="directive">static</span> <span class="directive">final</span> <span class="predefined-type">String</span> BY_MIN_AGE = <span class="string"><span class="delimiter">"</span><span class="content">person.byMinAge</span><span class="delimiter">"</span></span>;
- ...
-
-}
-
-<span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="annotation">@Query</span>(named = Person.BY_MIN_AGE)
- <span class="predefined-type">Long</span> countAllOlderThan(<span class="type">int</span> minAge);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Same as before, the parameter binding corresponds to the argument index
-in the method. If the named query requires named parameters to be used,
-this can be done by annotating the arguments with the <code>@QueryParam</code>
-annotation.</p>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-Java does not preserve method parameter names (yet), that’s why the
-annotation is needed.
-</td>
-</tr>
-</table>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@NamedQuery</span>(name = Person.BY_MIN_AGE,
- query = <span class="string"><span class="delimiter">"</span><span class="content">select count(p) from Person p where p.age > :minAge order by p.age asc</span><span class="delimiter">"</span></span>)
-
-...
-
-<span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="annotation">@Query</span>(named = Person.BY_MIN_AGE)
- <span class="predefined-type">Long</span> countAllOlderThan(<span class="annotation">@QueryParam</span>(<span class="string"><span class="delimiter">"</span><span class="content">minAge</span><span class="delimiter">"</span></span>) <span class="type">int</span> minAge);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>It is also possible to set a native SQL query in the annotation. The
-<code>@Query</code> annotation has a native attribute which flags that the query is
-not JPQL but plain SQL:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Entity</span>
-<span class="annotation">@Table</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">PERSON_TABLE</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Person</span>
-{
- ...
-}
-
-<span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="annotation">@Query</span>(value = <span class="string"><span class="delimiter">"</span><span class="content">SELECT * FROM PERSON_TABLE p WHERE p.AGE > ?1</span><span class="delimiter">"</span></span>, isNative = <span class="predefined-constant">true</span>)
- <span class="predefined-type">List</span><Person> findAllOlderThan(<span class="type">int</span> minAge);
-
-}</code></pre>
-</div>
-</div>
-</div>
-<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>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="annotation">@Query</span>(named = Person.BY_MIN_AGE, max = <span class="integer">10</span>, lock = LockModeType.PESSIMISTIC_WRITE)
- <span class="predefined-type">List</span><Person> findAllForUpdate(<span class="type">int</span> minAge);
-
-}</code></pre>
-</div>
-</div>
-<table class="tableblock frame-all grid-all">
-<colgroup>
-<col>
-<col>
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Name</th>
-<th class="tableblock halign-left valign-top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">max</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Limits the number of results.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">lock</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Use a specific LockModeType to execute the query.</p></td>
-</tr>
-</tbody>
-</table>
-<div class="paragraph">
-<p>Note that these options can also be applied to method expressions.</p>
-</div>
-</div>
-<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
-example, sorting criteria could come from a user selection so they
-cannot be known beforehand. DeltaSpike allows you to apply query options
-at runtime by using the <code>QueryResult</code> result type:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="annotation">@Query</span>(<span class="string"><span class="delimiter">"</span><span class="content">select p from Person p where p.age between ?1 and ?2</span><span class="delimiter">"</span></span>)
- QueryResult<Person> findAllByAge(<span class="type">int</span> minAge, <span class="type">int</span> maxAge);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Once you have obtained a <code>QueryResult</code>, you can apply further options to
-the query:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">List</span><Person> result = personRepository.findAllByAge(<span class="integer">18</span>, <span class="integer">65</span>)
- .orderAsc(<span class="string"><span class="delimiter">"</span><span class="content">p.lastName</span><span class="delimiter">"</span></span>, <span class="predefined-constant">false</span>)
- .orderDesc(<span class="string"><span class="delimiter">"</span><span class="content">p.age</span><span class="delimiter">"</span></span>, <span class="predefined-constant">false</span>)
- .lockMode(LockModeType.WRITE)
- .hint(<span class="string"><span class="delimiter">"</span><span class="content">org.hibernate.timeout</span><span class="delimiter">"</span></span>, <span class="predefined-type">Integer</span>.valueOf(<span class="integer">10</span>))
- .getResultList();</code></pre>
-</div>
-</div>
-<div class="admonitionblock important">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-important" title="Important"></i>
-</td>
-<td class="content">
-Note that sorting is only applicable to method expressions or non-named
-queries. For named queries it might be possible, but is currently only
-supported for Hibernate, EclipseLink and OpenJPA.
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>Note that the <code>QueryResult</code> return type can also be used with method
-expressions.</p>
-</div>
-<div class="admonitionblock important">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-important" title="Important"></i>
-</td>
-<td class="content">
-<code>QueryResult</code> is based on our internal understanding of your query.
-DeltaSpike expects the alias used in your queries to refer to the entity as <code>e</code>
-You can disable this behavior by passing in false with your attribute, <code>.orderDesc("p.age", false)</code>
-which would add descending ordering to your existing query <code>select p from Person p</code>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<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>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">// Query API style</span>
-QueryResult<Person> paged = personRepository.findByAge(age)
- .maxResults(<span class="integer">10</span>)
- .firstResult(<span class="integer">50</span>);
-
-<span class="comment">// or paging style</span>
-QueryResult<Person> paged = personRepository.findByAge(age)
- .withPageSize(<span class="integer">10</span>) <span class="comment">// equivalent to maxResults</span>
- .toPage(<span class="integer">5</span>);
-
-<span class="type">int</span> totalPages = paged.countPages();</code></pre>
-</div>
-</div>
-</div>
-<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
-scenario for repositories. DeltaSpike supports this with a special
-marking annotation <code>@Modifying</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<Person, <span class="predefined-type">Long</span>>
-{
-
- <span class="annotation">@Modifying</span>
- <span class="annotation">@Query</span>(<span class="string"><span class="delimiter">"</span><span class="content">update Person as p set p.classifier = ?1 where p.classifier = ?2</span><span class="delimiter">"</span></span>)
- <span class="type">int</span> updateClassifier(Classifier current, Classifier next);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Bulk operation query methods can either return void or int, which counts
-the number of entities affected by the bulk operation.</p>
-</div>
-</div>
-<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
-result. This can result in tedious handling with try-catch blocks or
-have potential impact on your transaction (as the <code>RuntimeException</code>
-might roll it back).</p>
-</div>
-<div class="paragraph">
-<p>DeltaSpike Data gives the option to change this to the way it makes most
-sense for the current usecase. While the default behavior is still fully
-aligned with JPA, it is also possible to request optional query results.</p>
-</div>
-</div>
-<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
-method expressions, <code>Query</code> annotations and <code>QueryResult<E></code> calls.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span>
-{
-
- Person findOptionalBySsn(<span class="predefined-type">String</span> ssn);
-
- <span class="annotation">@Query</span>(named = Person.BY_NAME, singleResult = SingleResultType.OPTIONAL)
- Person findByName(<span class="predefined-type">String</span> firstName, <span class="predefined-type">String</span> lastName);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>For method expressions, the <code>findOptionalBy</code> prefix can be used. For
-<code>@Query</code> annotations, the <code>singleResult</code> attribute can be overridden
-with the <code>SingleResultType.OPTIONAL</code> enum.</p>
-</div>
-<div class="paragraph">
-<p>In case the query returns more than one result, a
-<code>NonUniqueResultException</code> is still thrown.</p>
-</div>
-</div>
-<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
-result, same as for optional queries <code>null</code> is returned. In case there
-is more than one result, any result is returned, or more concretely the
-first result out of the result list.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span>
-{
-
- Person findAnyByLastName(<span class="predefined-type">String</span> lastName);
-
- <span class="annotation">@Query</span>(named = Person.BY_NAME, singleResult = SingleResultType.ANY)
- Person findByName(<span class="predefined-type">String</span> firstName, <span class="predefined-type">String</span> lastName);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>For method expressions, the <code>findAnyBy</code> prefix can be used. For <code>@Query</code>
-annotations, the <code>singleResult</code> attribute can be overridden with the
-<code>SingleResultType.ANY</code> enum.</p>
-</div>
-<div class="paragraph">
-<p>This option will not throw an exception.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_java_8_semantics">Java 8 Semantics</h3>
-<div class="paragraph">
-<p>Repositories support returning instances of <code>java.util.Optional</code> and <code>java.util.stream.Stream</code> for any method.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span>
-{
-
- Optional<Person> findBySsn(<span class="predefined-type">String</span> ssn);
-
- Stream<Person> findByLocation(<span class="predefined-type">String</span> location);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Queries returning <code>Optional<T></code> will behave like <code>SingleResultType.OPTIONAL</code>, if the data is present, return the single
-result, otherwise return <code>Optional.empty()</code>. You can override this by using <code>SingleResultType.ANY</code> which takes the first
-result of the list, or else <code>empty()</code>.</p>
-</div>
-<div class="paragraph">
-<p>Queries returning <code>Stream<T></code> act as a simple wrapper for <code>query.getResultList().stream()</code> to give back the results.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_entity_graphs">Entity Graphs</h3>
-<div class="paragraph">
-<p>EntityGraphs are a feature added in JPA 2.1. The Data module supports entity graphs for query operations, where the results
-will be limited based on a defined graph. This feature is only available if you are using a JPA 2.1 implementation.</p>
-</div>
-<div class="paragraph">
-<p><code>@EntityGraph</code> can be used for either <code>fetch</code> or <code>load</code> operations, depending on the <code>EntityGraphType</code> used in the annotation. Most queries should use the <code>FETCH</code> option.</p>
-</div>
-<div class="sect3">
-<h4 id="_named_graphs">Named Graphs</h4>
-<div class="paragraph">
-<p>Entity graphs can be selected by name. A <code>@NamedEntityGraph</code> should be defined already within your persistence context to leverage this. When this graph is referenced on a repository method, it will be applied to the query.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_dyanmically_built_graphs">Dyanmically built graphs</h4>
-<div class="paragraph">
-<p>If you want to dynamically build a graph, you can do that via the <code>paths</code> attribute of the annotation. The paths specified will be added as graph nodes. Each graph node will be used in the select. The format is the full path to the property, based on the property names.</p>
-</div>
-</div>
-</div>
-</div>
-</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
-transaction is needed or not, and if so, if there is already one
-ongoing. The Data module uses the <code>TransactionStrategy</code> provided by the
-<a href="http://deltaspike.apache.org/documentation/jpa.html">JPA Module</a> for this. See the JPA
-module documentation for more details.</p>
-</div>
-<div class="admonitionblock important">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-important" title="Important"></i>
-</td>
-<td class="content">
-Some containers do not support <code>BeanManagedUserTransactionStrategy</code>! As
-JTA has still some portability issues even in Java EE 7, it might be
-required that you implement your own <code>TransactionStrategy</code>. We will
-think about providing an acceptable solution for this.
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>If you need to open a transaction on a concrete repository method, we
-currently recommend creating an extension (see next chapter) which uses
-<code>@Transactional</code> and might look like the following sample.</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">TxExtension</span><E> <span class="directive">implements</span> DelegateQueryHandler, TxRepository <span class="comment">// this is your extension interface</span>
-{
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> EntityManager em;
-
- <span class="annotation">@Override</span> <span class="annotation">@Transactional</span>
- <span class="directive">public</span> <span class="predefined-type">List</span><E> transactional(ListResultCallback callback)
- {
- <span class="keyword">return</span> callback.execute();
- }
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Repositories can then implement the <code>TxRepository</code> interface and call
-their queries in the <code>transactional</code> method (where the callback
-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="_query_delegates">Query Delegates</h3>
-<div class="paragraph">
-<p>While several base interfaces are defined for repositories, there might still be
-the odd convenience method that is missing. This is actually intentional
-- things should not get overloaded for each and every use case. That’s
-why in DeltaSpike you can define your own reusable methods.</p>
-</div>
-<div class="paragraph">
-<p>For example, you might want to use the QueryDsl library in your
-repositories:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">com.mysema.query.jpa.impl.JPAQuery</span>;
-
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">QueryDslSupport</span>
-{
- JPAQuery jpaQuery();
-}
-
-<span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> QueryDslSupport
-{
- ...
-}</code></pre>
-</div>
-</div>
-</div>
-<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>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">QueryDslSupport</span>
-{
- JPAQuery jpaQuery();
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>As a next step, you need to provide an implementation for this interface
-once. It is also important that this implementation implements the
-<code>DelegateQueryHandler</code> interface (do not worry, this is just an empty
-marker interface):</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">QueryDslRepositoryExtension</span><E> <span class="directive">implements</span> QueryDslSupport, DelegateQueryHandler
-{
-
- <span class="annotation">@Inject</span>
- <span class="directive">private</span> QueryInvocationContext context;
-
- <span class="annotation">@Override</span>
- <span class="directive">public</span> JPAQuery jpaQuery()
- {
- <span class="keyword">return</span> <span class="keyword">new</span> JPAQuery(context.getEntityManager());
- }
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>As you see in the sample, you can inject a <code>QueryInvocationContext</code>
-which contains utility methods like accessing the current
-<code>EntityManager</code> and entity class.</p>
-</div>
-<div class="paragraph">
-<p>Note that, if you define multiple extensions with equivalent method
-signatures, there is no specific order in which the implementation is
-selected.</p>
-</div>
-</div>
-</div>
-</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
-top of them, for example because the Entities are quite complex but the service
-layer needs only a limited view on it, or because the Entities are
-exposed over a remote interface and there should not be a 1:1 view on
-the domain model.</p>
-</div>
-<div class="paragraph">
-<p>DeltaSpike Data allows to directly plugin in such a mapping mechanism
-without the need to specify additional mapping methods:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="annotation">@MappingConfig</span>(PersonDtoMapper.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span>
-{
-
- PersonDto findBySsn(<span class="predefined-type">String</span> ssn);
-
- <span class="predefined-type">List</span><PersonDto> findByLastName(<span class="predefined-type">String</span> lastName);
-
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The <code>PersonDtoMapper</code> class has to implement the <code>QueryInOutMapper</code>
-interface:</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">PersonDtoMapper</span> <span class="directive">implements</span> QueryInOutMapper<Person>
-{
-
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="predefined-type">Object</span> mapResult(Person result)
- {
- ... <span class="comment">// converts Person into a PersonDto</span>
- }
- ...
-
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="predefined-type">Object</span> mapResultList(<span class="predefined-type">List</span><Person> result)
- {
- ... <span class="comment">// result lists can also be mapped into something different</span>
- <span class="comment">// than a collection.</span>
- }
-
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="type">boolean</span> mapsParameter(<span class="predefined-type">Object</span> parameter)
- {
- <span class="keyword">return</span> parameter != <span class="predefined-constant">null</span> && (
- parameter <span class="keyword">instanceof</span> PersonDto || parameter <span class="keyword">instanceof</span> PersonId);
- }
-
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="predefined-type">Object</span> mapParameter(<span class="predefined-type">Object</span> parameter)
- {
- ... <span class="comment">// converts query parameters if required</span>
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The mapper can also be used to transform query parameters. Parameters
-are converted before executing queries and calling repository
-extensions.</p>
-</div>
-<div class="paragraph">
-<p>Note that those mapper classes are treated as CDI Beans, so it is
-possible to use injection in those beans (e.g. you might inject an
-<code>EntityManager</code> or other mappers). As the <code>@MappingConfig</code> refers to the
-mapper class directly, the mapper must be uniquely identifiable by its
-class.</p>
-</div>
-<div class="paragraph">
-<p>It is also possible to combine mappings with the base Repository classes:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="annotation">@MappingConfig</span>(PersonDtoMapper.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">PersonRepository</span> <span class="directive">extends</span> EntityRepository<PersonDto, PersonId>
-{
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>In this case, the <code>forEntity</code> attribute in the <code>@Repository</code> annotation
-is mandatory. Also it is up to the mapper to convert parameters
-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="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,
-which only requires to override three methods:</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">PersonMapper</span> <span class="directive">extends</span> SimpleQueryInOutMapperBase<Person, PersonDto>
-{
-
- <span class="annotation">@Override</span>
- <span class="directive">protected</span> <span class="predefined-type">Object</span> getPrimaryKey(PersonDto dto)
- {
- <span class="keyword">return</span> dto.getId();
- }
-
- <span class="annotation">@Override</span>
- <span class="directive">protected</span> PersonDto toDto(Person entity)
- {
- ...
- }
-
- <span class="annotation">@Override</span>
- <span class="directive">protected</span> Person toEntity(Person entity, PersonDto dto) {
- ...
- return entity;
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The first method, <code>getPrimaryKey</code>, identifies the primary key of an
-incoming DTO (this might need mapping too). If there is a primary key in
-the DTO, Data tries to retrieve the Entity and feed it to the <code>toEntity</code>
-method, so the entity to be mapped is <strong>attached to the persistence
-context</strong>. If there is no primary key, a new instance of the Entity is
-created. In any case, there is no need to map the primary key to the
-entity (it either does not exist or is already populated for an existing
-entity).</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_jpa_criteria_api_support">JPA Criteria API Support</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Besides automatic query generation, the DeltaSpike Data module also
-provides a DSL-like API to create JPA 2 Criteria queries. It takes
-advantage of the JPA 2 meta model, which helps creating type safe
-queries.</p>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-The JPA meta model can easily be generated with an annotation processor.
-Hibernate or EclipseLink provide such a processor, which can be
-integrated into your compile and build cycle.
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>Note that this criteria API is not intended to replace the standard
-criteria API - it is rather a utility API that should make life easier on
-the most common cases for a custom query. The JPA criteria API’s
-strongest point is certainly its type safety - which comes at the cost
-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="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>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Repository</span>(forEntity = Person.class)
-<span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">PersonRepository</span> <span class="directive">implements</span> CriteriaSupport<Person>
-{
-
- <span class="directive">public</span> <span class="predefined-type">List</span><Person> findAdultFamilyMembers(<span class="predefined-type">String</span> name, <span class="predefined-type">Integer</span> minAge)
- {
- <span class="keyword">return</span> criteria()
- .like(Person_.name, <span class="string"><span class="delimiter">"</span><span class="content">%</span><span class="delimiter">"</span></span> + name + <span class="string"><span class="delimiter">"</span><span class="content">%</span><span class="delimiter">"</span></span>)
- .gtOrEq(Person_.age, minAge)
- .eq(Person_.validated, <span class="predefined-type">Boolean</span>.TRUE)
- .orderDesc(Person_.age)
[... 3105 lines stripped ...]