feat: pagination

modules/cloudant/src/main/java/com/ibm/cloud/cloudant/features/pagination/AllDocsBasePageIterator.java

@@ -0,0 +1,59 @@
+/**
+ * © Copyright IBM Corporation 2025. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.cloudant.features.pagination;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import com.ibm.cloud.cloudant.v1.Cloudant;
+import com.ibm.cloud.cloudant.v1.model.AllDocsResult;
+import com.ibm.cloud.cloudant.v1.model.DocsResultRow;
+
+abstract class AllDocsBasePageIterator<B, O> extends KeyPageIterator<String, B, O, AllDocsResult, DocsResultRow> {
+
+  AllDocsBasePageIterator(Cloudant client, O options, OptionsHandler<B, O> optsHandler) {
+    super(client, options, optsHandler);
+  }
+
+  @Override
+  final Function<AllDocsResult, List<DocsResultRow>> itemsGetter() {
+    return AllDocsResult::getRows;
+  }
+
+  @Override
+  final Function<DocsResultRow, String> nextKeyGetter() {
+    return DocsResultRow::getKey;
+  }
+
+  @Override
+  final Function<DocsResultRow, String> nextKeyIdGetter() {
+    return DocsResultRow::getId;
+  }
+
+  /**
+   * Setting start key doc ID is a no-op for all_docs based paging where
+   * key is the same as id.
+   */
+  @Override
+  final Optional<BiFunction<B, String, B>> nextKeyIdSetter() {
+    return Optional.empty();
+  }
+
+  @Override
+  final Optional<String> checkBoundary(DocsResultRow penultimateItem, DocsResultRow lastItem) {
+    // AllDocs and DesignDocs pagers always have unique keys (because they are document IDs)
+    return Optional.empty();
+  }
+}

modules/cloudant/src/main/java/com/ibm/cloud/cloudant/features/pagination/AllDocsPageIterator.java

@@ -0,0 +1,55 @@
+/**
+ * © Copyright IBM Corporation 2025. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.cloudant.features.pagination;
+
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import com.ibm.cloud.cloudant.v1.Cloudant;
+import com.ibm.cloud.cloudant.v1.model.AllDocsResult;
+import com.ibm.cloud.cloudant.v1.model.PostAllDocsOptions;
+import com.ibm.cloud.cloudant.v1.model.PostAllDocsOptions.Builder;
+import com.ibm.cloud.sdk.core.http.ServiceCall;
+
+final class AllDocsPageIterator extends AllDocsBasePageIterator<Builder, PostAllDocsOptions> {
+
+  AllDocsPageIterator(Cloudant client, PostAllDocsOptions options) {
+     super(client, options, OptionsHandler.POST_ALL_DOCS);
+  }
+
+  @Override
+  Function<PostAllDocsOptions, Builder> optionsToBuilderFunction() {
+    return PostAllDocsOptions::newBuilder;
+  }
+
+  @Override
+  Function<Builder, PostAllDocsOptions> builderToOptionsFunction() {
+    return Builder::build;
+  }
+
+  @Override
+  BiFunction<Cloudant, PostAllDocsOptions, ServiceCall<AllDocsResult>> nextRequestFunction() {
+    return Cloudant::postAllDocs;
+  }
+
+  @Override
+  BiFunction<Builder, String, Builder> nextKeySetter() {
+    return Builder::startKey;
+  }
+
+  @Override
+  Function<PostAllDocsOptions, Long> limitGetter() {
+    return PostAllDocsOptions::limit;
+  }
+
+}

modules/cloudant/src/main/java/com/ibm/cloud/cloudant/features/pagination/AllDocsPartitionPageIterator.java

@@ -0,0 +1,56 @@
+/**
+ * © Copyright IBM Corporation 2025. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.cloudant.features.pagination;
+
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import com.ibm.cloud.cloudant.v1.Cloudant;
+import com.ibm.cloud.cloudant.v1.model.AllDocsResult;
+import com.ibm.cloud.cloudant.v1.model.PostPartitionAllDocsOptions;
+import com.ibm.cloud.cloudant.v1.model.PostPartitionAllDocsOptions.Builder;
+import com.ibm.cloud.sdk.core.http.ServiceCall;
+
+final class AllDocsPartitionPageIterator extends AllDocsBasePageIterator<PostPartitionAllDocsOptions.Builder, PostPartitionAllDocsOptions> {
+
+  AllDocsPartitionPageIterator(Cloudant client, PostPartitionAllDocsOptions options) {
+    super(client, options, OptionsHandler.POST_PARTITION_ALL_DOCS);
+  }
+
+  @Override
+  Function<PostPartitionAllDocsOptions, Builder> optionsToBuilderFunction() {
+    return PostPartitionAllDocsOptions::newBuilder;
+  }
+
+  @Override
+  Function<Builder, PostPartitionAllDocsOptions> builderToOptionsFunction() {
+    return Builder::build;
+  }
+
+  @Override
+  BiFunction<Cloudant, PostPartitionAllDocsOptions, ServiceCall<AllDocsResult>> nextRequestFunction() {
+    return Cloudant::postPartitionAllDocs;
+  }
+
+
+  @Override
+  BiFunction<Builder, String, Builder> nextKeySetter() {
+    return Builder::startKey;
+  }
+
+  @Override
+  Function<PostPartitionAllDocsOptions, Long> limitGetter() {
+    return PostPartitionAllDocsOptions::limit;
+  }
+
+}

modules/cloudant/src/main/java/com/ibm/cloud/cloudant/features/pagination/BasePageIterator.java

@@ -0,0 +1,92 @@
+/**
+ * © Copyright IBM Corporation 2025. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.cloudant.features.pagination;
+
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+import java.util.NoSuchElementException;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import com.ibm.cloud.cloudant.v1.Cloudant;
+import com.ibm.cloud.sdk.core.http.ServiceCall;
+
+abstract class BasePageIterator<B, O, R, I> implements Iterator<List<I>> {
+
+  protected final Cloudant client;
+  protected final long pageSize;
+  protected final OptionsHandler<B, O> optsHandler;
+  protected final AtomicReference<O> nextPageOptionsRef = new AtomicReference<>();
+  protected volatile boolean hasNext = true;
+
+  BasePageIterator(Cloudant client, O options, OptionsHandler<B, O> optsHandler) {
+    this.client = client;
+    this.optsHandler = optsHandler;
+    // Set the page size from the supplied options limit
+    this.pageSize = getPageSizeFromOptionsLimit(options);
+    // Set the first page options
+    buildAndSetOptions(optsHandler.builderFromOptions(options));
+  }
+
+  @Override
+  public final boolean hasNext() {
+    return this.hasNext;
+  }
+
+  @Override
+  public List<I> next() {
+    if (this.hasNext()) {
+      return Collections.unmodifiableList(this.nextRequest());
+    } else {
+      throw new NoSuchElementException();
+    }
+  }
+
+  List<I> nextRequest() {
+    ServiceCall<R> request = nextRequestFunction().apply(this.client, this.nextPageOptionsRef.get());
+    R result = request.execute().getResult();
+    List<I> items = itemsGetter().apply(result);
+    if (items.size() < this.pageSize) {
+      this.hasNext = false;
+    } else {
+      B optionsBuilder = optsHandler.builderFromOptions(this.nextPageOptionsRef.get());
+      setNextPageOptions(optionsBuilder, result);
+      buildAndSetOptions(optionsBuilder);
+    }
+    return items;
+  }
+
+  private void buildAndSetOptions(B optionsBuilder) {
+    this.nextPageOptionsRef.set(optsHandler.optionsFromBuilder(optionsBuilder));
+  }
+
+  abstract Function<O, B> optionsToBuilderFunction();
+
+  abstract Function<B, O> builderToOptionsFunction();
+
+  abstract Function<R, List<I>> itemsGetter();
+
+  abstract void setNextPageOptions(B builder, R result);
+
+  abstract BiFunction<Cloudant, O, ServiceCall<R>> nextRequestFunction();
+
+  abstract Function<O, Long> limitGetter();
+
+  Long getPageSizeFromOptionsLimit(O opts) {
+    return Optional.ofNullable(limitGetter().apply(opts)).orElse(200L);
+  }
+
+}

modules/cloudant/src/main/java/com/ibm/cloud/cloudant/features/pagination/BookmarkPageIterator.java

@@ -0,0 +1,36 @@
+/**
+ * © Copyright IBM Corporation 2025. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.cloudant.features.pagination;
+
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import com.ibm.cloud.cloudant.v1.Cloudant;
+
+abstract class BookmarkPageIterator<B, O, R, I> extends BasePageIterator<B, O, R, I> {
+
+  BookmarkPageIterator(Cloudant client, O options, OptionsHandler<B, O> optsHandler) {
+    super(client, options, optsHandler);
+  }
+
+  abstract Function<R, String> bookmarkGetter();
+
+  abstract BiFunction<B, String, B> bookmarkSetter();
+
+  @Override
+  final void setNextPageOptions(B builder, R result) {
+    String bookmark = bookmarkGetter().apply(result);
+    bookmarkSetter().apply(builder, bookmark);
+  }
+
+}

modules/cloudant/src/main/java/com/ibm/cloud/cloudant/features/pagination/DesignDocsPageIterator.java

@@ -0,0 +1,55 @@
+/**
+ * © Copyright IBM Corporation 2025. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.cloudant.features.pagination;
+
+import java.util.function.BiFunction;
+import java.util.function.Function;
+import com.ibm.cloud.cloudant.v1.Cloudant;
+import com.ibm.cloud.cloudant.v1.model.AllDocsResult;
+import com.ibm.cloud.cloudant.v1.model.PostDesignDocsOptions;
+import com.ibm.cloud.cloudant.v1.model.PostDesignDocsOptions.Builder;
+import com.ibm.cloud.sdk.core.http.ServiceCall;
+
+public class DesignDocsPageIterator extends AllDocsBasePageIterator<Builder, PostDesignDocsOptions> {
+
+  DesignDocsPageIterator(Cloudant client, PostDesignDocsOptions options) {
+      super(client, options, OptionsHandler.POST_DESIGN_DOCS);
+    }
+
+    @Override
+  BiFunction<Builder, String, Builder> nextKeySetter() {
+    return Builder::key;
+  }
+
+  @Override
+  Function<PostDesignDocsOptions, Builder> optionsToBuilderFunction() {
+    return PostDesignDocsOptions::newBuilder;
+  }
+
+  @Override
+  Function<Builder, PostDesignDocsOptions> builderToOptionsFunction() {
+    return Builder::build;
+  }
+
+  @Override
+  BiFunction<Cloudant, PostDesignDocsOptions, ServiceCall<AllDocsResult>> nextRequestFunction() {
+    return Cloudant::postDesignDocs;
+  }
+
+  @Override
+  Function<PostDesignDocsOptions, Long> limitGetter() {
+    return PostDesignDocsOptions::limit;
+  }
+
+}

modules/cloudant/src/main/java/com/ibm/cloud/cloudant/features/pagination/FindBasePageIterator.java

@@ -0,0 +1,38 @@
+/**
+ * © Copyright IBM Corporation 2025. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ */
+
+package com.ibm.cloud.cloudant.features.pagination;
+
+import java.util.List;
+import java.util.function.Function;
+import com.ibm.cloud.cloudant.v1.Cloudant;
+import com.ibm.cloud.cloudant.v1.model.Document;
+import com.ibm.cloud.cloudant.v1.model.FindResult;
+
+abstract class FindBasePageIterator<B, O> extends BookmarkPageIterator<B, O, FindResult, Document> {
+
+  FindBasePageIterator(Cloudant client, O options, OptionsHandler<B, O> optsHandler) {
+    super(client, options, optsHandler);
+  }
+
+  @Override
+  final Function<FindResult, List<Document>> itemsGetter() {
+    return FindResult::getDocs;
+  }
+
+  @Override
+  final Function<FindResult, String> bookmarkGetter() {
+    return FindResult::getBookmark;
+  }
+
+}