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}