lots of doc changes

extension/persistence/eclipselink/src/main/java/org/apache/polaris/extension/persistence/impl/eclipselink/PolarisEclipseLinkMetaStoreSessionImpl.java

@@ -565,6 +565,7 @@ public List<PolarisEntityActiveRecord> lookupEntityActiveBatch(
     } else {
       // In this case, we cannot push the filter down into the query. We must therefore remove
       // the page size limit from the PageToken and filter on the client side.
+      // TODO Implement a generic predicate that can be pushed down into different metastores
       PageToken unlimitedPageSizeToken = pageToken.withPageSize(Integer.MAX_VALUE);
       List<ModelEntity> rawData =
           this.store.lookupFullEntitiesActive(

polaris-core/src/main/java/org/apache/polaris/core/catalog/pagination/PageToken.java

@@ -69,7 +69,7 @@ public abstract static class PageTokenBuilder<T extends PageToken> {
      */
     public abstract int expectedComponents();
 
-    /** Deserialize a string into a `PageToken` */
+    /** Deserialize a string into a {@link PageToken} */
     public final PageToken fromString(String tokenString) {
       if (tokenString == null) {
         throw new IllegalArgumentException("Cannot build page token from null string");
@@ -90,6 +90,7 @@ public final PageToken fromString(String tokenString) {
             throw new IllegalArgumentException("Invalid token format in token: " + tokenString);
           }
 
+          // Cut off prefix and checksum
           T result = fromStringComponents(Arrays.asList(parts).subList(1, parts.length - 1));
           result.validate();
           return result;
@@ -99,7 +100,7 @@ public final PageToken fromString(String tokenString) {
       }
     }
 
-    /** Construct a `PageToken` from a plain limit */
+    /** Construct a {@link PageToken} from a plain limit */
     public final PageToken fromLimit(Integer limit) {
       if (limit == null) {
         return ReadEverythingPageToken.get();
@@ -108,41 +109,42 @@ public final PageToken fromLimit(Integer limit) {
       }
     }
 
-    /** Construct a `PageToken` from a plain limit */
+    /** Construct a {@link PageToken} from a plain limit */
     protected abstract T fromLimitImpl(int limit);
 
     /**
-     * PageTokenBuilder implementations should implement this to build a PageToken from components
-     * in a string token. These components should be the same ones returned by `getComponents` and
-     * won't include the token prefix or the checksum.
+     * {@link PageTokenBuilder} implementations should implement this to build a {@link PageToken}
+     * from components in a string token. These components should be the same ones returned by
+     * {@link #getComponents()} and won't include the token prefix or the checksum.
      */
     protected abstract T fromStringComponents(List<String> components);
   }
 
-  /** Convert this PageToken to components that the serialized token string will be built from. */
+  /** Convert this into components that the serialized token string will be built from. */
   protected abstract List<String> getComponents();
 
   /**
    * Builds a new page token to reflect new data that's been read. If the amount of data read is
-   * less than the pageSize, this will return `PageToken.DONE` (done)
+   * less than the pageSize, this will return {@link PageToken#DONE}(null)
    */
   protected abstract PageToken updated(List<?> newData);
 
   /**
-   * Builds a `PolarisPage<T>` from a `List<T>`. The `PageToken` attached to the new
-   * `PolarisPage<T>` is the same as the result of calling `updated(data)` on this `PageToken`.
+   * Builds a {@link PolarisPage<T>} from a {@link List<T>}. The {@link PageToken} attached to the
+   * new {@link PolarisPage<T>} is the same as the result of calling {@link #updated(List)} on this
+   * {@link PageToken}.
    */
   public final <T> PolarisPage<T> buildNextPage(List<T> data) {
     return new PolarisPage<T>(updated(data), data);
   }
 
   /**
-   * Return a new PageToken with an updated pageSize. If the pageSize provided is null, the existing
-   * pageSize will be preserved.
+   * Return a new {@link PageToken} with an updated page size. If the pageSize provided is null, the
+   * existing page size will be preserved.
    */
   public abstract PageToken withPageSize(Integer pageSize);
 
-  /** Serialize a PageToken into a string */
+  /** Serialize a {@link PageToken} into a string */
   @Override
   public final String toString() {
     List<String> components = getComponents();

polaris-core/src/main/java/org/apache/polaris/core/catalog/pagination/PolarisPage.java

@@ -21,8 +21,8 @@
 import java.util.List;
 
 /**
- * A wrapper for a List of data and a {@link PageToken} that can be used to continue the listing
- * operation that generated that data.
+ * A wrapper for a {@link List} of data and a {@link PageToken} that can be used to continue the
+ * listing operation that generated that data.
  */
 public class PolarisPage<T> {
   public final PageToken pageToken;
@@ -33,7 +33,7 @@ public PolarisPage(PageToken pageToken, List<T> data) {
     this.data = data;
   }
 
-  /** Used to wrap a List of data into a PolarisPage when there is no more data */
+  /** Used to wrap a {@link List<T>} of data into a {@link PolarisPage<T>} when there is no more data */
   public static <T> PolarisPage<T> fromData(List<T> data) {
     return new PolarisPage<>(PageToken.DONE, data);
   }

polaris-core/src/main/java/org/apache/polaris/core/catalog/pagination/ReadEverythingPageToken.java

@@ -31,7 +31,7 @@ private ReadEverythingPageToken() {
     validate();
   }
 
-  /** Get a ReadEverythingPageToken */
+  /** Get a {@link ReadEverythingPageToken} */
   public static ReadEverythingPageToken get() {
     return new ReadEverythingPageToken();
   }
@@ -77,11 +77,13 @@ protected List<String> getComponents() {
     return List.of();
   }
 
+  /** Any time {@link ReadEverythingPageToken} is updated, everything has been read */
   @Override
   public PageToken updated(List<?> newData) {
     return PageToken.DONE;
   }
 
+  /** {@link ReadEverythingPageToken} does not support page size */
   @Override
   public PageToken withPageSize(Integer pageSize) {
     if (pageSize == null) {

polaris-service/src/main/java/org/apache/polaris/service/catalog/BasePolarisCatalog.java

@@ -443,6 +443,7 @@ public boolean dropTable(TableIdentifier tableIdentifier, boolean purge) {
     return true;
   }
 
+  /** Check whether pagination is enabled for list operations */
   private boolean paginationEnabled() {
     return callContext
         .getPolarisCallContext()

polaris-service/src/main/java/org/apache/polaris/service/catalog/IcebergCatalogAdapter.java

@@ -22,6 +22,7 @@
 
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableMap;
+import edu.umd.cs.findbugs.annotations.Nullable;
 import jakarta.ws.rs.core.Response;
 import jakarta.ws.rs.core.SecurityContext;
 import java.net.URLEncoder;
@@ -109,8 +110,11 @@ private PolarisCatalogHandlerWrapper newHandlerWrapper(
         polarisAuthorizer);
   }
 
+  /** Build a {@link PageToken} from a string and page size. */
   private PageToken buildPageToken(
-      PolarisEntityManager entityManager, String tokenString, Integer pageSize) {
+      PolarisEntityManager entityManager,
+      @Nullable String tokenString,
+      @Nullable Integer pageSize) {
     if (tokenString != null) {
       return entityManager
           .newMetaStoreSession()

polaris-service/src/main/java/org/apache/polaris/service/types/ListNamespacesResponseWithPageToken.java

@@ -28,9 +28,9 @@
 import org.apache.polaris.core.catalog.pagination.PolarisPage;
 
 /**
- * Used in lieu of `ListNamespacesResponse` when there may be a `PageToken` associated with the
- * response. Callers can use this `PageToken` to continue the listing operation and obtain more
- * results.
+ * Used in lieu of {@link ListNamespacesResponse} when there may be a {@link PageToken}
+ * associated with the response. Callers can use this {@link PageToken} to continue the
+ * listing operation and obtain more results.
  */
 public class ListNamespacesResponseWithPageToken extends ListNamespacesResponse {
   private final PageToken pageToken;

polaris-service/src/main/java/org/apache/polaris/service/types/ListTablesResponseWithPageToken.java

@@ -23,10 +23,16 @@
 import com.google.common.base.Preconditions;
 import java.util.List;
 import org.apache.iceberg.catalog.TableIdentifier;
+import org.apache.iceberg.rest.responses.ListNamespacesResponse;
 import org.apache.iceberg.rest.responses.ListTablesResponse;
 import org.apache.polaris.core.catalog.pagination.PageToken;
 import org.apache.polaris.core.catalog.pagination.PolarisPage;
 
+/**
+ * Used in lieu of {@link ListTablesResponse} when there may be a {@link PageToken}
+ * associated with the response. Callers can use this {@link PageToken} to continue the
+ * listing operation and obtain more results.
+ */
 public class ListTablesResponseWithPageToken extends ListTablesResponse {
   private final PageToken pageToken;