Merge pull request #49 from OpenLiberty/feedback

Query annotation updates

Author: mswatosh

README.adoc

@@ -94,7 +94,7 @@ Packages.java
 include::finish/src/main/java/io/openliberty/guides/data/Packages.java[]
 ----
 
-A common pattern with respositories is to use the plural of the entity, so the repository you will be working with in this guide is called `Packages.java`. Repositories in Jakarta Data provide a simplified means for interacting with persistent data. They are annotated with the `@Repository` annotation. Jakarta Data provides several built in Repositories with common methods which can be extended with application specific queries. The [hotspot=CrudRepository file=1]`CrudRepository` interface provides methods for Create, Read, Update, and Delete (CRUD) operations.
+A common pattern with repositories is to use the plural of the entity, so the repository you will be working with in this guide is called `Packages.java`. Repositories in Jakarta Data provide a simplified means for interacting with persistent data. They are annotated with the `@Repository` annotation. Jakarta Data provides several built-in repositories with common methods which can be extended with application-specific queries. The [hotspot=CrudRepository file=1]`CrudRepository` interface provides methods for Create, Read, Update, and Delete (CRUD) operations.
 
 [hotspot=CrudRepository file=1]`CrudRepository` provides two options for persisting entities, `insert` and `save`. The first option `insert` will persist an entity only if the entity does not already exist. The `save` option will persist an entity even if it already exists, allowing it to be used for updating entities as well. [hotspot=CrudRepository file=1]`CrudRepository` provides a `delete` method for removing entities.
 
@@ -179,29 +179,19 @@ include::finish/src/main/java/io/openliberty/guides/data/Packages.java[]
 ----
 
 === Sort
-In addition to the `@OrderBy` annotation it is possible to provide sorting at runtime. This is accomplished by adding a [hotspot=Sort file=0]`Sort` parameter to your query method:
+In addition to the `@OrderBy` annotation it is possible to provide sorting at runtime. This is accomplished by adding a [hotspot=Sort file=0]`Sort` parameter to your query method like in the [hotspot=Sort file=0]`sorted` method.
 
-```java
-@Find
-List<Package> sorted(Sort<?> sortBy);
-```
-
-A `Sort` can be created and provided at runtime using the `Sort` class's static methods:
+A [hotspot=Sort file=0]`Sort` can be created and provided at runtime using the [hotspot=Sort file=0]`Sort` class's static methods:
 ```java
 Sort sort = Sort.desc("height");
 ```
 
 === Limit
-Jakarta Data queries can restrict the number of entities returned at runtime by providing a [hotspot=Limit file=0]`Limit` object to the query:
+Jakarta Data queries can restrict the number of entities returned at runtime by providing a [hotspot=Limit file=0]`Limit` object to the query as shown in the [hotspot=Limit file=0]`shortestWithLimit` method.
 
-```java
-@Find
-@OrderBy("length")
-List<Package> shortestWithLimit(Limit limit);
-```
-This method will return the shortest packages in order from shortest to longest, but limited only to only the specified number of results.
+This method will return the shortest packages in order from shortest to longest, but limited to only the specified number of results.
 
-Limits can be created and supplied using the `Limit` class's static methods:
+Limits can be created and supplied using the [hotspot=Limit file=0]`Limit` class's static methods:
 ```java
 Limit limitTen = Limit.of(10);
 ```
@@ -213,14 +203,9 @@ Limit range = Limit.range(10,20);
 
 
 === Paging
-When querying large amounts of data, paging is possible by adding a [hotspot=PageRequest file=0]`PageRequest` parameter to your query method:
+When querying large amounts of data, paging is possible by adding a [hotspot=PageRequest file=0]`PageRequest` parameter to your query method like in the [hotspot=PageRequest file=0]`all` method. This method will return all of the packages, but with the results paginated based on the provided [hotspot=PageRequest file=0]`PageRequest`.
 
-```java
-@Find
-Page<Package> all(PageRequest pageRequest);
-```
-
-A `PageRequest` can be constructed with the [hotspot=PageRequest file=0]`PageRequest` class's static methods. To request the first [hotspot=Page file=0]`Page` with a page size of 20 results:
+A [hotspot=PageRequest file=0]`PageRequest` can be constructed with the [hotspot=PageRequest file=0]`PageRequest` class's static methods. To request the first [hotspot=Page file=0]`Page` with a page size of 20 results:
 
 ```java
 Page<Package> page = packages.all(PageRequest.ofSize(20));
@@ -234,7 +219,7 @@ Page<Package> anotherPage = packages.all(page.nextPageRequest());
 ```
 
 == The Query Annotation
-The `@Query` annotation allows users to write queries using the Jakarta Data Query Language (JDQL). Complex queries can be written concisely using JDQL.  JDQL is a strict subset of the Jakarta Persistence Query Language (JPQL).
+The `@Query` annotation allows users to write queries using the Jakarta Data Query Language (JDQL). Complex queries can be written concisely using JDQL. JDQL is a strict subset of the Jakarta Persistence Query Language (JPQL).
 
 Packages.java
 [source, Java, linenums, role='code_column hide_tags=copyright']
@@ -248,26 +233,17 @@ include::finish/src/main/java/io/openliberty/guides/data/Packages.java[]
 `src/main/java/io/openliberty/guides/data/Packages.java`
 ----
 
-Here is an example of a complex query simplified using JDQL.
-
-```java
-@Query("WHERE length > :threshold OR height > :threshold OR width > :threshold")
-List<Package> withDimensionLargerThan(float threshold);
-```
+For an example of a complex query simplified using JDQL, take a look at [hotspot=withAnyDimensionLargerThan file=0]`withAnyDimensionLargerThan`.
 
 This query checks for packages where the length, height, or width are larger than a threshold, which is provided as a parameter in the function. The threshold parameter is referenced in the query using `:threshold`. Achieving the same query with Query by Method Name would result in a very long method name and additional parameters.
 
 
-JDQL supports named and ordinal parameters, as well as a number of operators.
-```java
-@Query("WHERE length + width + height > ?1")
-List<Package> withTotalDimensionOver(float threshold);
-```
+JDQL supports both named and positional parameters, as well as a number of operators. This is shown in the [hotspot=withTotalDimensionOver file=0]`withTotalDimensionOver` query, which sums the length, width, and height of each package to check if the total exceeds a provided threshold. Unlike the named parameter syntax (`:threshold`) used in the previous example, this query uses positional parameter syntax with `?1` to reference the first method parameter.
 
 See the https://jakarta.ee/specifications/data/1.0/jakarta-data-1.0#_jakarta_data_query_language[Jakarta Data specification] for a more comprehensive overview of the Jakarta Data Query Language.
 
 == Where to next?
-Experiment by creating your own queries.  Use the existing ones in the `Packages` class as a starting point and then test them out in the sample application. For example, you could add a query to find packages arriving in a specific destination, which is ordered by width:
+Experiment by creating your own queries. Use the existing ones in the `Packages` class as a starting point and then test them out in the sample application. For example, you could add a query to find packages arriving at a specific destination, which is ordered by width:
 
 ```java
     @Find

finish/src/main/java/io/openliberty/guides/data/Packages.java

@@ -97,11 +97,15 @@ public interface Packages extends CrudRepository<Package, Integer> {
     // end::sorting[]
     // tag::query-anno[]
 
+    // tag::withAnyDimensionLargerThan[]
     @Query("WHERE length > :threshold OR height > :threshold OR width > :threshold")
-    List<Package> withDimensionLargerThan(float threshold);
+    List<Package> withAnyDimensionLargerThan(float threshold);
+    // end::withAnyDimensionLargerThan[]
 
+    // tag::withTotalDimensionOver[]
     @Query("WHERE length + width + height > ?1")
     List<Package> withTotalDimensionOver(float threshold);
+    // end::withTotalDimensionOver[]
     // end::query-anno[]
 
 }