Correction to hasNext and hasPrevious Javadoc

api/src/main/java/jakarta/data/page/Page.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022,2024 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022,2026 Contributors to the Eclipse Foundation
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -85,22 +85,30 @@ default Stream<T> stream() {
     int numberOfElements();
 
     /**
-     * Returns {@code true} if it is known that there are more results or that
+     * Returns {@code true} if more results are known to exist, or
      * it is necessary to request a next page to determine whether there are
-     * more results, so that {@link #nextPageRequest()} will definitely not
-     * return {@code null}.
+     * more results.
      *
-     * @return {@code false} if this is the last page of results.
+     * @return {@code false} if this is known to be the last page of results.
+     *         Otherwise {@code true}, indicating that
+     *         {@link #nextPageRequest()} can be safely invoked without raising
+     *         {@code NoSuchElementException}, although the content of the
+     *         next page might be empty if no additional results are later
+     *         found when attempting to retrieve the next page.
      */
     boolean hasNext();
 
     /**
-     * Returns {@code true} if it is known that there are previous results or
-     * that it is necessary to request the previous page to determine whether
-     * there are previous results, so that {@link #previousPageRequest()} will
-     * not return {@code null}.
+     * Returns {@code true} if previous results are known to exist, or
+     * it is necessary to request the previous page to determine whether
+     * there are previous results.
      *
-     * @return {@code false} if this is the first page of results.
+     * @return {@code false} if this is known to be the first page of results.
+     *         Otherwise {@code true}, indicating that
+     *         {@link #previousPageRequest()} can be safely invoked without
+     *         raising {@code NoSuchElementException}, although the content of
+     *         the previous page might be empty if no additional results are
+     *         later found when attempting to retrieve the previous page.
      */
     boolean hasPrevious();
 

api/src/main/java/jakarta/data/page/PageRequest.java

@@ -81,7 +81,7 @@ public interface PageRequest {
      *
      * @param pageNumber The page number.
      * @return a new instance of {@code PageRequest}. This method never returns
-     * {@code null}.
+     *         {@code null}.
      * @throws IllegalArgumentException when the page number is negative or
      *                                  zero.
      */
@@ -98,7 +98,7 @@ static PageRequest ofPage(long pageNumber) {
      *                     {@linkplain Page#totalElements() total} number of
      *                     elements available across all pages.
      * @return a new instance of {@code PageRequest}. This method never returns
-     * {@code null}.
+     *         {@code null}.
      * @throws IllegalArgumentException when the page number is negative or
      *                                  zero.
      */
@@ -112,7 +112,7 @@ static PageRequest ofPage(long pageNumber, int maxPageSize, boolean requestTotal
      *
      * @param maxPageSize The number of query results in a full page.
      * @return a new instance of {@code PageRequest}. This method never returns
-     * {@code null}.
+     *         {@code null}.
      * @throws IllegalArgumentException when maximum page size is negative or
      *                                  zero.
      */
@@ -135,7 +135,7 @@ static PageRequest ofSize(int maxPageSize) {
      *                     {@linkplain Page#totalElements() total} number of
      *                     elements available across all pages.
      * @return a new instance of {@code PageRequest} with forward cursor-based
-     * pagination. This method never returns {@code null}.
+     *         pagination. This method never returns {@code null}.
      * @throws IllegalArgumentException if the cursor is null or has no values.
      */
     static PageRequest afterCursor(Cursor cursor, long pageNumber, int maxPageSize, boolean requestTotal) {
@@ -158,8 +158,8 @@ static PageRequest afterCursor(Cursor cursor, long pageNumber, int maxPageSize,
      *                     {@linkplain Page#totalElements() total} number of
      *                     elements available across all pages.
      * @return a new instance of {@code PageRequest} with cursor-based
-     * pagination in the previous page direction. This method never returns
-     * {@code null}.
+     *         pagination in the previous page direction. This method never
+     *         returns {@code null}.
      * @throws IllegalArgumentException if the cursor is null or has no values.
      */
     static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize, boolean requestTotal) {
@@ -176,24 +176,23 @@ static PageRequest beforeCursor(Cursor cursor, long pageNumber, int maxPageSize,
      *               name pattern of the repository method to which this
      *               pagination will be supplied.
      * @return a new instance of {@code PageRequest} with forward cursor-based
-     * pagination. This method never returns {@code null}.
+     *         pagination. This method never returns {@code null}.
      * @throws IllegalArgumentException if no key values are provided.
      */
     PageRequest afterCursor(Cursor cursor);
 
     /**
      * <p>Requests {@linkplain CursoredPage cursor-based pagination} in the
-     * previous page
-     * direction relative to the specified key values.</p>
+     * previous page direction relative to the specified key values.</p>
      *
      * @param cursor cursor with key values, the order and number of which must
      *               match the {@link OrderBy} annotations,
      *               {@link jakarta.data.Sort} parameters, or {@code OrderBy}
      *               name pattern of the repository method to which this
      *               pagination will be supplied.
      * @return a new instance of {@code PageRequest} with cursor-based
-     * pagination in the previous page direction. This method never returns
-     * {@code null}.
+     *         pagination in the previous page direction. This method never
+     *         returns {@code null}.
      * @throws IllegalArgumentException if no key values are provided.
      */
     PageRequest beforeCursor(Cursor cursor);