Repository: jakartaee/data (java)

Issue:
Do we have the static factory methods for Pageable reversed?
I was looking at the [Pageable in Spring Data](https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Pageable.html) (static methods tab) and noticed that the primary pattern enabled by the static factory methods is to create `Pageable` for a particular page size `Pageable.ofSize(50)`, automatically starting on the first page, and to optionally select a different page `Pageable.ofSize(50).withPage(2)` if you didn't want the default first page.

To me, it does seem more natural to assume that more users will be interested in specifying a particular page size and defaulting to the first page than would be interested in choosing a particular page number and defaulting the page size, as we [currently have in Jakarta Data](https://github.com/jakartaee/data/blob/1f9ce811fdf51fdaa818e9ada9a2f919c149b112/api/src/main/java/jakarta/data/repository/Pageable.java#L122). We don't necessarily need to get rid of the `Pageable.page(pageNum)` method, but I'd like to add in the reverse pattern, either `Pageable.of(pageSize)` or `Pageable.ofSize(pageSize)` or `Pageable.size(pageSize)` because I expect it will be more commonly used and will make code more readable and less error-prone than the two argument `Pageable.of(long, long)` method.



Pull request description:
Pageable.size and fix 2 javadoc typos
Fixes #41 along with 2 minor JavaDoc typos that I noticed while making the updates.

Signed-off-by: Nathan Rauh <nathan.rauh@us.ibm.com>

Patch:
diff --git a/api/src/main/java/jakarta/data/repository/Pageable.java b/api/src/main/java/jakarta/data/repository/Pageable.java
index 1a17621e..b4054170 100644
--- a/api/src/main/java/jakarta/data/repository/Pageable.java
+++ b/api/src/main/java/jakarta/data/repository/Pageable.java
@@ -114,7 +114,7 @@ public class Pageable {
     }
 
     /**
-     * Creates a new Pageable at the given size with a default size of 10.
+     * Creates a new Pageable at the given page with a default size of 10.
      *
      * @param page The page
      * @return The pageable
@@ -139,4 +139,14 @@ public class Pageable {
         return new Pageable(size, page);
     }
 
+    /**
+     * Creates a new <code>Pageable</code> for requesting pages of the
+     * specified size, starting with the first page number, which is 1.
+     *
+     * @param pageSize number of query results in a full page.
+     * @return The pageable.
+     */
+    public static Pageable size(long pageSize) {
+        return of(1, pageSize);
+    }
 }
\ No newline at end of file
diff --git a/api/src/main/java/jakarta/data/repository/Repository.java b/api/src/main/java/jakarta/data/repository/Repository.java
index d5def7ef..4d0bb62f 100644
--- a/api/src/main/java/jakarta/data/repository/Repository.java
+++ b/api/src/main/java/jakarta/data/repository/Repository.java
@@ -350,7 +350,7 @@ import java.lang.annotation.Target;
  *           String pattern, Pageable pagination);
  * ...
  * page1 = products.findByNameLikeOrderByAmountSoldDescNameAsc(
- *                  "%phone%", Pageable.of(1, 20));
+ *                  "%phone%", Pageable.size(20));
  * </pre>
  *
  * <h3>Sorting</h3>
@@ -363,7 +363,7 @@ import java.lang.annotation.Target;
  * Product[] findByNameLike(String pattern, Limit max, Sort... sortBy);
  *
  * ...
- * page1 = products.findByNameLike(namePattern, Pagination.of(1, 25),
+ * page1 = products.findByNameLike(namePattern, Pageable.of(1, 25),
  *                                 Sort.desc("price"),
  *                                 Sort.desc("amountSold"),
  *                                 Sort.asc("name"));


Test patch:
diff --git a/api/src/test/java/jakarta/data/repository/PageableTest.java b/api/src/test/java/jakarta/data/repository/PageableTest.java
index 6424302e..891bebd0 100644
--- a/api/src/test/java/jakarta/data/repository/PageableTest.java
+++ b/api/src/test/java/jakarta/data/repository/PageableTest.java
@@ -29,6 +29,13 @@ class PageableTest {
         Assertions.assertEquals(2L, pageable.getPage());
     }
 
+    @Test
+    public void shouldCreatePageableWithSize() {
+        Pageable pageable = Pageable.size(50);
+        Assertions.assertEquals(50L, pageable.getSize());
+        Assertions.assertEquals(1L, pageable.getPage());
+    }
+
     @Test
     public void shouldNext(){
         Pageable pageable = Pageable.of(2, 1);
@@ -52,6 +59,12 @@ class PageableTest {
 
         Assertions.assertThrows(IllegalArgumentException.class, ()->
                 Pageable.of(1, 0));
+
+        Assertions.assertThrows(IllegalArgumentException.class, ()->
+                Pageable.size(0));
+
+        Assertions.assertThrows(IllegalArgumentException.class, ()->
+                Pageable.size(-1));
     }
 
 }
\ No newline at end of file