DATACMNS-220, DATAJPA-174 - Updated reference docs on query parsing.

Updated the repositories reference documentation section on query parsing to reflect the correct usage of method prefixes, how to use the Distinct, IgnoreCase and OrderBy clauses.

src/docbkx/repositories.xml

@@ -319,19 +319,34 @@ interface UserRepository extends MyBaseRepository<User, Long> {
 
         <para>The query builder mechanism built into Spring Data repository
         infrastructure is useful to build constraining queries over entities
-        of the repository. We will strip the prefixes <code>findBy</code>,
-        <code>find</code>, <code>readBy</code>, <code>read</code>,
-        <code>getBy</code> as well as <code>get</code> from the method and
-        start parsing the rest of it. At a very basic level you can define
-        conditions on entity properties and concatenate them with
-        <code>AND</code> and <code>OR</code>.</para>
+        of the repository. We will strip the prefixes <code>find…By</code>,
+        <code>read…By</code>, as well as <code>get…By</code> from the method
+        and start parsing the rest of it. The introducing clause can contain
+        further expressions such as a <code>Distinct</code> to set a distinct
+        flag on the query to be created. However, the first <code>By</code>
+        acts as delimiter to indicate the start of the actual criterias. At a
+        very basic level you can define conditions on entity properties and
+        concatenate them with <code>AND</code> and <code>OR</code>.</para>
 
         <example>
           <title>Query creation from method names</title>
 
           <para><programlisting language="java">public interface PersonRepository extends Repository&lt;User, Long&gt; {
 
   List&lt;Person&gt; findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);
+
+  // Enables the distinct flag for the query
+  List&lt;Person&gt; findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
+  List&lt;Person&gt; findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);
+
+  // Enabling ignoring case for an individual property
+  List&lt;Person&gt; findByLastnameIgnoreCase(String lastname);
+  // Enabling ignoring case for all suitable properties
+  List&lt;Person&gt; findByLastnameAndFirstnameAllIgnoreCase(String lastname, String firstname);
+
+  // Enabling static ORDER BY for a query
+  List&lt;Person&gt; findByLastnameOrderByFirstnameAsc(String lastname);
+  List&lt;Person&gt; findByLastnameOrderByFirstnameDesc(String lastname);
 }</programlisting></para>
         </example>
 
@@ -347,6 +362,23 @@ interface UserRepository extends MyBaseRepository&lt;User, Long&gt; {
         datastore to datastore please consult the according part of the
         reference documentation.</para>
 
+        <para>As you can see the method parser also supports setting an ignore
+        case flag for individual properties (e.g.
+        <methodname>findByLastnameIgnoreCase(…)</methodname>) or for all
+        properties of a type that support ignoring case (i.e. usually
+        <code>String</code>s, e.g.
+        <methodname>findByLastnameAndFirstnameAllIgnoreCase(…)</methodname>).
+        Whether ignoring cases is supported my differ from store to store, so
+        consult the relevant sections of the store specific query method
+        reference docs.</para>
+
+        <para>Static ordering can be applied by appending an
+        <code>OrderBy</code> clause to the query method referencing a property
+        and providing a sorting direction (<code>Asc</code> or
+        <code>Desc</code>). To create a query method that supports dynamic
+        sorting have a look at <xref
+        linkend="repositories.special-parameters"/>. </para>
+
         <section id="repositories.query-methods.property-expressions">
           <title>Property expressions</title>