Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Reference documentation formatting of XMLEditor.

  • Loading branch information...
commit 0b737586c858f5dbe1305391fbe08afb40ae3082 1 parent c6045de
Oliver Gierke olivergierke authored
Showing with 69 additions and 61 deletions.
  1. +69 −61 src/docbkx/reference/jpa.xml
130 src/docbkx/reference/jpa.xml
View
@@ -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>
Please sign in to comment.
Something went wrong with that request. Please try again.