001/* 002 * Copyright 2026 Revetware LLC. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.revetsec.scim; 018 019import com.google.errorprone.annotations.CheckReturnValue; 020import com.revetsec.internal.Limits; 021import org.jspecify.annotations.NonNull; 022import org.jspecify.annotations.Nullable; 023import javax.annotation.concurrent.Immutable; 024import javax.annotation.concurrent.NotThreadSafe; 025import java.time.Duration; 026import java.util.Objects; 027import java.util.Optional; 028 029/** 030 * Immutable advertised pagination capabilities. A cursor timeout is a minimum validity 031 * commitment the application must honor, rather than a core cursor-expiry implementation. 032 * @since 1.0.0 033 */ 034@Immutable 035@CheckReturnValue 036public final class ScimPaginationConfig { 037 private final boolean indexSupported; 038 private final boolean cursorSupported; 039 private final @NonNull ScimPaginationMethod defaultMethod; 040 private final int defaultPageSize; 041 private final int maximumPageSize; 042 private final @Nullable Duration cursorTimeout; 043 044 private ScimPaginationConfig(@NonNull Builder builder) { 045 indexSupported = builder.indexSupported == null || builder.indexSupported; 046 cursorSupported = Boolean.TRUE.equals(builder.cursorSupported); 047 defaultMethod = builder.defaultMethod == null ? ScimPaginationMethod.INDEX : builder.defaultMethod; 048 defaultPageSize = Limits.SCIM_DEFAULT_PAGE_SIZE.require(builder.defaultPageSize == null 049 ? Limits.SCIM_DEFAULT_PAGE_SIZE.getDefaultIntValue() : builder.defaultPageSize); 050 maximumPageSize = Limits.SCIM_PAGE_SIZE.require(builder.maximumPageSize == null 051 ? Limits.SCIM_PAGE_SIZE.getDefaultIntValue() : builder.maximumPageSize); 052 cursorTimeout = builder.cursorTimeout; 053 if (cursorTimeout != null) Limits.SCIM_CURSOR_TIMEOUT.require(cursorTimeout); 054 if (!indexSupported && !cursorSupported) 055 throw new IllegalArgumentException("At least one SCIM pagination method must be supported."); 056 if ((defaultMethod == ScimPaginationMethod.INDEX && !indexSupported) 057 || (defaultMethod == ScimPaginationMethod.CURSOR && !cursorSupported)) 058 throw new IllegalArgumentException("The default SCIM pagination method must be supported."); 059 if (defaultPageSize > maximumPageSize) 060 throw new IllegalArgumentException("SCIM default page size must not exceed maximum page size."); 061 if (cursorSupported && cursorTimeout == null) 062 throw new IllegalStateException("SCIM cursor support requires an explicit validity commitment."); 063 } 064 065 /** 066 * Starts pagination configuration with index enabled, cursor disabled and page size 100/1000. 067 * @return a new builder 068 * @since 1.0.0 069 */ 070 public static @NonNull Builder builder() { return new Builder(); } 071 072 /** 073 * Returns whether index pagination is supported. 074 * @return whether index pagination is supported 075 * @since 1.0.0 076 */ 077 public @NonNull Boolean isIndexSupported() { return indexSupported; } 078 079 /** 080 * Returns whether cursor pagination is supported. 081 * @return whether cursor pagination is supported 082 * @since 1.0.0 083 */ 084 public @NonNull Boolean isCursorSupported() { return cursorSupported; } 085 086 /** 087 * Returns the default pagination method. 088 * @return the default pagination method 089 * @since 1.0.0 090 */ 091 public @NonNull ScimPaginationMethod getDefaultMethod() { return defaultMethod; } 092 093 /** 094 * Returns the default page size. 095 * @return the default page size 096 * @since 1.0.0 097 */ 098 public @NonNull Integer getDefaultPageSize() { return defaultPageSize; } 099 100 /** 101 * Returns the maximum accepted page size. 102 * @return the maximum accepted page size 103 * @since 1.0.0 104 */ 105 public @NonNull Integer getMaximumPageSize() { return maximumPageSize; } 106 107 /** 108 * Returns the optional minimum cursor-validity commitment. 109 * @return the optional minimum cursor-validity commitment 110 * @since 1.0.0 111 */ 112 public @NonNull Optional<@NonNull Duration> getCursorTimeout() { return Optional.ofNullable(cursorTimeout); } 113 114 /** 115 * Compares all advertised pagination characteristics. 116 * @param other the comparison value 117 * @return whether configurations are equal 118 * @since 1.0.0 119 */ 120 @Override public boolean equals(@Nullable Object other) { 121 return this == other || (other instanceof ScimPaginationConfig value 122 && indexSupported == value.indexSupported && cursorSupported == value.cursorSupported 123 && defaultMethod == value.defaultMethod && defaultPageSize == value.defaultPageSize 124 && maximumPageSize == value.maximumPageSize && Objects.equals(cursorTimeout, value.cursorTimeout)); 125 } 126 127 /** 128 * Returns the configuration hash. 129 * @return the configuration hash 130 * @since 1.0.0 131 */ 132 @Override public int hashCode() { 133 return Objects.hash(indexSupported, cursorSupported, defaultMethod, defaultPageSize, maximumPageSize, cursorTimeout); 134 } 135 136 /** 137 * Returns a fixed configuration description. 138 * @return a fixed description 139 * @since 1.0.0 140 */ 141 @Override public @NonNull String toString() { return "ScimPaginationConfig{<redacted>}"; } 142 143 /** 144 * Mutable, non-thread-safe pagination configuration; null restores the stated default. 145 * @since 1.0.0 146 */ 147 @NotThreadSafe 148 @CheckReturnValue 149 public static final class Builder { 150 private @Nullable Boolean indexSupported; 151 private @Nullable Boolean cursorSupported; 152 private @Nullable ScimPaginationMethod defaultMethod; 153 private @Nullable Integer defaultPageSize; 154 private @Nullable Integer maximumPageSize; 155 private @Nullable Duration cursorTimeout; 156 private Builder() {} 157 158 /** 159 * Sets indexSupported; null restores true. 160 * @param value the setting, or null to restore its default 161 * @return this builder 162 * @since 1.0.0 163 */ 164 public @NonNull Builder indexSupported(@Nullable Boolean value) { indexSupported = value; return this; } 165 166 /** 167 * Sets cursorSupported; null restores false. 168 * @param value the setting, or null to restore its default 169 * @return this builder 170 * @since 1.0.0 171 */ 172 public @NonNull Builder cursorSupported(@Nullable Boolean value) { cursorSupported = value; return this; } 173 174 /** 175 * Sets defaultMethod; null restores INDEX. 176 * @param value the setting, or null to restore its default 177 * @return this builder 178 * @since 1.0.0 179 */ 180 public @NonNull Builder defaultMethod(@Nullable ScimPaginationMethod value) { defaultMethod = value; return this; } 181 182 /** 183 * Sets defaultPageSize; null restores 100. 184 * @param value the setting, or null to restore its default 185 * @return this builder 186 * @since 1.0.0 187 */ 188 public @NonNull Builder defaultPageSize(@Nullable Integer value) { defaultPageSize = value; return this; } 189 190 /** 191 * Sets maximumPageSize; null restores 1000. 192 * @param value the setting, or null to restore its default 193 * @return this builder 194 * @since 1.0.0 195 */ 196 public @NonNull Builder maximumPageSize(@Nullable Integer value) { maximumPageSize = value; return this; } 197 198 /** 199 * Sets cursorTimeout; null restores absent. 200 * @param value the setting, or null to restore its default 201 * @return this builder 202 * @since 1.0.0 203 */ 204 public @NonNull Builder cursorTimeout(@Nullable Duration value) { cursorTimeout = value; return this; } 205 206 /** 207 * Checks bounds and advertised method/timeout consistency and creates an immutable snapshot. 208 * @return pagination capabilities 209 * @since 1.0.0 210 */ 211 public @NonNull ScimPaginationConfig build() { return new ScimPaginationConfig(this); } 212 } 213}