Add pagination helpers to PageRequest and javadoc to FilterResponse

PageRequest gains getZeroBasedStartIndex() and getEffectiveCount(int)
to eliminate the error-prone 1-based to 0-based conversion that every
Repository implementation must duplicate.

FilterResponse gets javadoc clarifying that totalResults must be the
total count of ALL matching resources before pagination, not the page
size. References RFC 7644 §3.4.2.4.

Generated-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bdemers

scim-spec/scim-spec-schema/src/main/java/org/apache/directory/scim/spec/filter/FilterResponse.java

@@ -21,13 +21,39 @@
 
 import java.util.Collection;
 
+/**
+ * Holds the result of a {@link org.apache.directory.scim.core.repository.Repository#find Repository.find()}
+ * query, including the paginated resources and the total count of matching resources.
+ *
+ * <p><b>Important:</b> {@code totalResults} must be the total number of resources matching
+ * the query <em>before</em> pagination is applied, not the number of resources in this page.
+ * This allows SCIM clients to calculate how many pages exist. See
+ * <a href="https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4">RFC 7644 §3.4.2.4</a>.</p>
+ *
+ * <p>Example: if 50 users match a filter and the client requests {@code startIndex=11&count=10},
+ * then {@code resources} contains 10 users and {@code totalResults} is 50.</p>
+ *
+ * @param <T> the resource type
+ */
 public class FilterResponse<T> {
-  
+
   private Collection<T> resources;
+
+  /**
+   * The total number of resources matching the query, before pagination.
+   * This is NOT the size of the {@link #resources} collection (which is the page size).
+   */
   private int totalResults;
-  
+
   public FilterResponse() {}
-  
+
+  /**
+   * Creates a filter response with the given page of resources and total count.
+   *
+   * @param resources    the resources in this page (may be a subset of all matching resources)
+   * @param totalResults the total number of matching resources <em>before</em> pagination —
+   *                     must be {@code >= resources.size()}
+   */
   public FilterResponse(Collection<T> resources, int totalResults) {
     this.resources = resources;
     this.totalResults = totalResults;

scim-spec/scim-spec-schema/src/main/java/org/apache/directory/scim/spec/filter/PageRequest.java

@@ -68,6 +68,39 @@ public int hashCode() {
     return result;
   }
 
+  /**
+   * Converts the 1-based SCIM {@code startIndex} to a 0-based offset suitable for
+   * Java stream {@code skip()} or list {@code subList()} operations.
+   *
+   * <p>SCIM uses 1-based indexing: {@code startIndex=1} means the first result.
+   * Per <a href="https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4">RFC 7644 §3.4.2.4</a>,
+   * a value less than 1 is interpreted as 1 (offset 0). Returns 0 if
+   * {@code startIndex} is null.</p>
+   *
+   * @return the 0-based offset (always {@code >= 0})
+   */
+  public long getZeroBasedStartIndex() {
+    return startIndex != null ? Math.max(0, startIndex - 1L) : 0L;
+  }
+
+  /**
+   * Returns the effective page size, defaulting to {@code totalResults} if the
+   * client did not specify a {@code count} parameter.
+   *
+   * <p>Per <a href="https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.4">RFC 7644 §3.4.2.4</a>,
+   * a {@code count} of 0 means "return no resources" (only {@code totalResults}),
+   * and a negative value is interpreted as 0.</p>
+   *
+   * @param totalResults the total number of matching resources (before pagination)
+   * @return the effective page size (always {@code >= 0})
+   */
+  public long getEffectiveCount(int totalResults) {
+    if (count == null) {
+      return (long) totalResults;
+    }
+    return Math.max(0L, count.longValue());
+  }
+
   public String toString() {
     return "PageRequest(startIndex=" + this.getStartIndex() + ", count=" + this.getCount() + ")";
   }

scim-spec/scim-spec-schema/src/test/java/org/apache/directory/scim/spec/filter/PageRequestTest.java

@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 org.apache.directory.scim.spec.filter;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class PageRequestTest {
+
+  @Test
+  void getZeroBasedStartIndex_withStartIndex1_returns0() {
+    PageRequest pageRequest = new PageRequest().setStartIndex(1);
+
+    assertThat(pageRequest.getZeroBasedStartIndex()).isEqualTo(0L);
+  }
+
+  @Test
+  void getZeroBasedStartIndex_withStartIndex5_returns4() {
+    PageRequest pageRequest = new PageRequest().setStartIndex(5);
+
+    assertThat(pageRequest.getZeroBasedStartIndex()).isEqualTo(4L);
+  }
+
+  @Test
+  void getZeroBasedStartIndex_withNullStartIndex_returns0() {
+    PageRequest pageRequest = new PageRequest();
+
+    assertThat(pageRequest.getZeroBasedStartIndex()).isEqualTo(0L);
+  }
+
+  @Test
+  void getZeroBasedStartIndex_withStartIndex0_returns0_clamped() {
+    PageRequest pageRequest = new PageRequest().setStartIndex(0);
+
+    assertThat(pageRequest.getZeroBasedStartIndex()).isEqualTo(0L);
+  }
+
+  @Test
+  void getEffectiveCount_withCount10_andTotalResults50_returns10() {
+    PageRequest pageRequest = new PageRequest().setCount(10);
+
+    assertThat(pageRequest.getEffectiveCount(50)).isEqualTo(10L);
+  }
+
+  @Test
+  void getEffectiveCount_withNullCount_andTotalResults50_returns50() {
+    PageRequest pageRequest = new PageRequest();
+
+    assertThat(pageRequest.getEffectiveCount(50)).isEqualTo(50L);
+  }
+
+  @Test
+  void getEffectiveCount_withCount0_returns0() {
+    // RFC 7644 §3.4.2.4: count=0 means "return no resources"
+    PageRequest pageRequest = new PageRequest().setCount(0);
+
+    assertThat(pageRequest.getEffectiveCount(50)).isEqualTo(0L);
+  }
+
+  @Test
+  void getEffectiveCount_withNegativeCount_returns0() {
+    // RFC 7644 §3.4.2.4: negative count interpreted as 0
+    PageRequest pageRequest = new PageRequest().setCount(-1);
+
+    assertThat(pageRequest.getEffectiveCount(50)).isEqualTo(0L);
+  }
+}