Spring/spring-data-jpa
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reference documentation formatting of XMLEditor.

Browse Source
This commit is contained in:
Oliver Gierke
2011-09-05 13:12:29 +02:00
parent c6045de7ad
commit 0b737586c8
1 changed files with 69 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
src/docbkx/reference/jpa.xml
View File

@@ -113,8 +113,8 @@
named queries through a naming convention (see <xref
linkend="jpa.query-methods.named-queries" /> for more information) or
rather annotate your query method with
<interfacename>@Query</interfacename> (see
<xref linkend="jpa.query-methods.at-query" /> for details).</para>
<interfacename>@Query</interfacename> (see <xref
linkend="jpa.query-methods.at-query" /> for details).</para>
</simplesect>
</section>
@@ -288,8 +288,8 @@
element and <code>@NamedQuery</code> annotation. The queries for these
configuration elements have to be defined in JPA query language. Of
course you can use <code>&lt;named-native-query /&gt;</code> or
<code>@NamedNativeQuery</code> too. These elements allow you to
define the query in native SQL by losing the database platform
<code>@NamedNativeQuery</code> too. These elements allow you to define
the query in native SQL by losing the database platform
independence.</para>
</note>
@@ -318,10 +318,10 @@
<simplesect>
<title>Annotation configuration</title>
<para>Annotation configuration has the advantage of not needing another
configuration file to be edited, probably lowering maintenance costs. You pay
for that benefit by the need to recompile your domain class for every
new query declaration.</para>
<para>Annotation configuration has the advantage of not needing
another configuration file to be edited, probably lowering maintenance
costs. You pay for that benefit by the need to recompile your domain
class for every new query declaration.</para>
<example>
<title>Annotation based named query configuration</title>
@@ -338,8 +338,8 @@ public class User {
<simplesect>
<title>Declaring interfaces</title>
<para>To allow execution of these named queries all you need to do is to
specify the <interfacename>UserRepository</interfacename> as
<para>To allow execution of these named queries all you need to do is
to specify the <interfacename>UserRepository</interfacename> as
follows:</para>
<example>
@@ -353,11 +353,11 @@ public class User {
}</programlisting>
</example>
<para>Spring Data will try to resolve a call to these
methods to a named query, starting with the simple name of the
configured domain class, followed by the method name separated by a
dot. So the example here would use the named queries defined above
instead of trying to create a query from the method name.</para>
<para>Spring Data will try to resolve a call to these methods to a
named query, starting with the simple name of the configured domain
class, followed by the method name separated by a dot. So the example
here would use the named queries defined above instead of trying to
create a query from the method name.</para>
</simplesect>
</section>
@@ -365,16 +365,16 @@ public class User {
<title>Using @Query</title>
<para>Using named queries to declare queries for entities is a valid
approach and works fine for a small number of queries. As the
queries themselves are tied to the Java method that executes them you
actually can bind them directly using the Spring Data
JPA <code>@Query</code> annotation rather than annotating them to the
domain class. This will free the domain class from persistence specific
information and co-locate the query to the repository interface.</para>
approach and works fine for a small number of queries. As the queries
themselves are tied to the Java method that executes them you actually
can bind them directly using the Spring Data JPA <code>@Query</code>
annotation rather than annotating them to the domain class. This will
free the domain class from persistence specific information and
co-locate the query to the repository interface.</para>
<para>Queries annotated to the query method will take precedence over queries defined
using <code>@NamedQuery</code> or named queries declared in
<filename>orm.xml</filename>.</para>
<para>Queries annotated to the query method will take precedence over
queries defined using <code>@NamedQuery</code> or named queries declared
in <filename>orm.xml</filename>.</para>
<example>
<title>Declare query at the query method using @Query</title>
@@ -392,8 +392,8 @@ public class User {
<para>By default Spring Data JPA will use position based parameter
binding as described in all the samples above. This makes query methods
a little error prone to refactoring regarding the parameter position.
To solve this issue you can use <code>@Param</code> annotation to give a
a little error prone to refactoring regarding the parameter position. To
solve this issue you can use <code>@Param</code> annotation to give a
method parameter a concrete name and bind the name in the query:</para>
<example>
@@ -414,8 +414,8 @@ public class User {
<section id="jpa.modifying-queries">
<title>Modifying queries</title>
<para>All the sections above describe how to declare queries to access
a given entity or collection of entities. Of course you can add custom
<para>All the sections above describe how to declare queries to access a
given entity or collection of entities. Of course you can add custom
modifying behaviour by using facilities described in <xref
linkend="custom-implementations" />. As this approach is feasible for
comprehensive custom functionality, you can achieve the execution of
@@ -450,31 +450,36 @@ int setFixedFirstnameFor(String firstname, String lastname);</programlisting>
<title>Specifications</title>
<para>JPA 2 introduces a criteria API that can be used to build queries
programmatically. Writing a <code>criteria</code> you actually define the where-clause
of a query for a domain class. Taking another step
back these criteria can be regarded as predicate over the entity that is
described by the JPA criteria API constraints.</para>
programmatically. Writing a <code>criteria</code> you actually define the
where-clause of a query for a domain class. Taking another step back these
criteria can be regarded as predicate over the entity that is described by
the JPA criteria API constraints.</para>
<para>Spring Data JPA takes the concept of a specification from Eric
Evans' book "Domain Driven Design", following the same semantics and
providing an API to define such
<interfacename>Specification</interfacename>s using the JPA criteria API.
To support specifications you can extend your repository interface with the
<interfacename>JpaSpecificationExecutor</interfacename> interface:</para>
To support specifications you can extend your repository interface with
the <interfacename>JpaSpecificationExecutor</interfacename>
interface:</para>
<programlisting language="java">public interface CustomerRepository extends CrudRepository&lt;Customer, Long&gt;, JpaSpecificationExecutor {
…
}</programlisting>
<para>The additional interface carries methods that allow
you to execute <interfacename>Specification</interfacename>s in a variety
of ways.</para> For example, the <code>readAll</code> method will return
all entities that match the specification:
<para>The additional interface carries methods that allow you to execute
<interfacename>Specification</interfacename>s in a variety of ways.</para>
For example, the
<code>readAll</code>
method will return all entities that match the specification:
<programlisting language="java">List&lt;T&gt; readAll(Specification&lt;T&gt; spec);</programlisting>
<para>The <interfacename>Specification</interfacename> interface is
as follows:</para>
<para>The <interfacename>Specification</interfacename> interface is as
follows:</para>
<programlisting language="java">public interface Specification&lt;T&gt; {
Predicate toPredicate(Root&lt;T&gt; root, CriteriaQuery&lt;?&gt; query,
@@ -485,8 +490,8 @@ int setFixedFirstnameFor(String firstname, String lastname);</programlisting>
<interfacename>Specification</interfacename>s can easily be used to build
an extensible set of predicates on top of an entity that then can be
combined and used with <interfacename>JpaRepository</interfacename>
without the need to declare a query (method) for every needed
combination. Here's an example:</para>
without the need to declare a query (method) for every needed combination.
Here's an example:</para>
<example>
<title>Specifications for a Customer</title>
@@ -625,8 +630,8 @@ class UserManagementImpl implements UserManagement {
will be neglected then as the outer transaction configuration determines
the actual one used. Note that you will have to activate
<code>&lt;tx:annotation-driven /&gt;</code> explicitly to get annotation
based configuration at facades working. The example above assumes you are
using component scanning.</para>
based configuration at facades working. The example above assumes you
are using component scanning.</para>
</example>
<section id="transactional-query-methods">
@@ -661,15 +666,17 @@ public interface UserRepository extends JpaRepository&lt;User, Long&gt; {
<note>
<para>It's definitely reasonable to use transactions for read only
queries and we can mark them as such by setting the
<code>readOnly</code> flag. This will not, however, act as check that you do not
trigger a manipulating query (although some databases
<code>readOnly</code> flag. This will not, however, act as check that
you do not trigger a manipulating query (although some databases
reject <literal>INSERT</literal> and <literal>UPDATE</literal>
statements inside a read only transaction). The <code>readOnly</code> flag instead is
propagated as hint to the underlying JDBC driver for performance
optimizations. Furthermore, Spring will perform some optimizations on the
underlying JPA provider. E.g. when used with Hibernate the flush mode
is set to <code>NEVER</code> when you configure a transaction as <code>readOnly</code> which
causes Hibernate to skip dirty checks (a noticeable improvement on large object trees).</para>
statements inside a read only transaction). The <code>readOnly</code>
flag instead is propagated as hint to the underlying JDBC driver for
performance optimizations. Furthermore, Spring will perform some
optimizations on the underlying JPA provider. E.g. when used with
Hibernate the flush mode is set to <code>NEVER</code> when you
configure a transaction as <code>readOnly</code> which causes
Hibernate to skip dirty checks (a noticeable improvement on large
object trees).</para>
</note>
</section>
</section>
@@ -677,11 +684,11 @@ public interface UserRepository extends JpaRepository&lt;User, Long&gt; {
<section id="jpa.auditing">
<title>Auditing</title>
<para>Most applications will require some form of auditability to track when
an entity was created or modified and by whom.
Spring Data JPA provides facilities to add this audit information to
an entity transparently by AOP means. To take part in this functionality your
domain classes must implement a more advanced interface:</para>
<para>Most applications will require some form of auditability to track
when an entity was created or modified and by whom. Spring Data JPA
provides facilities to add this audit information to an entity
transparently by AOP means. To take part in this functionality your domain
classes must implement a more advanced interface:</para>
<example>
<title><interfacename>Auditable</interfacename> interface</title>
@@ -778,10 +785,11 @@ public interface UserRepository extends JpaRepository&lt;User, Long&gt; {
<title>Merging persistence units</title>
<para>Spring supports having multiple persistence units out of the box.
Sometimes, however, you might want to modularize your application but still make sure
that all these modules run inside a single persistence unit at runtime.
To do so Spring Data JPA offers a <code>PersistenceUnitManager</code> implementation
that automatically merges persistence units based on their name.</para>
Sometimes, however, you might want to modularize your application but
still make sure that all these modules run inside a single persistence
unit at runtime. To do so Spring Data JPA offers a
<code>PersistenceUnitManager</code> implementation that automatically
merges persistence units based on their name.</para>
<example>
<title>Using MergingPersistenceUnitmanager</title>