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 static java.util.Objects.requireNonNull;
020
021import com.google.errorprone.annotations.CheckReturnValue;
022
023import org.jspecify.annotations.NonNull;
024import org.jspecify.annotations.Nullable;
025
026import java.util.*;
027
028import javax.annotation.concurrent.Immutable;
029
030/** Immutable engine-created query bound to its originating provider's schema and semantic registration.
031 * Filter-policy approval and projection do not authorize a caller. Applications authenticate callers,
032 * select tenants, authorize access and execute the returned normalized filter with stable ordering.
033 * A page built from this query must be rendered by the originating provider or a base-URI-only copy.
034 * Applications own cursor authenticity, context binding and expiry; core checks only bounded framing.
035 * @since 1.0.0
036 */
037@Immutable
038@CheckReturnValue
039public final class ScimQuery {
040    private final @NonNull ScimResourceType resourceType;
041    private final @Nullable ScimFilter filter;
042    private final @NonNull ScimAttributeSelection attributeSelection;
043    private final @Nullable ScimAttributePath sortBy;
044    private final @Nullable ScimSortOrder sortOrder;
045    private final @NonNull ScimPaginationMethod paginationMethod;
046    private final @Nullable Long startIndex;
047    private final @NonNull Integer count;
048    private final @Nullable Long requestedCount;
049    private final @Nullable String cursor;
050    private final boolean firstCursorPage;
051    private final @NonNull Object semanticContext;
052    private final int maximumCursorCharacters;
053
054    ScimQuery(
055            @NonNull ScimResourceType resourceType,
056            @Nullable ScimFilter filter,
057            @NonNull ScimAttributeSelection attributeSelection,
058            @Nullable ScimAttributePath sortBy,
059            @Nullable ScimSortOrder sortOrder,
060            @NonNull ScimPaginationMethod paginationMethod,
061            @Nullable Long startIndex,
062            @NonNull Integer count,
063            @Nullable Long requestedCount,
064            @Nullable String cursor,
065            boolean firstCursorPage,
066            @NonNull Object context,
067            int maximumCursorCharacters) {
068        this.resourceType = resourceType;
069        this.filter = filter;
070        this.attributeSelection = attributeSelection;
071        this.sortBy = sortBy;
072        this.sortOrder = sortOrder;
073        this.paginationMethod = paginationMethod;
074        this.startIndex = startIndex;
075        this.count = count;
076        this.requestedCount = requestedCount;
077        this.cursor = cursor;
078        this.firstCursorPage = firstCursorPage;
079        semanticContext = requireNonNull(context);
080        this.maximumCursorCharacters = maximumCursorCharacters;
081    }
082
083    /** Returns the exact registered resource-type object targeted by this query.
084     * @return the originating registration
085     * @since 1.0.0
086     */
087    public @NonNull ScimResourceType getResourceType() {
088        return resourceType;
089    }
090
091    /** Returns the complete normalized, schema-bound, policy-approved filter, when supplied.
092     * Applications execute this returned tree rather than the original request text; policy approval
093     * does not establish caller authorization.
094     * @return the approved filter, or empty when no filter was supplied
095     * @since 1.0.0
096     */
097    public @NonNull Optional<@NonNull ScimFilter> getFilter() {
098        return Optional.ofNullable(filter);
099    }
100
101    /** Returns this query's bound projection, separately from attribute authorization.
102     * The selection retains the originating provider's semantic registration.
103     * @return the bound projection
104     * @since 1.0.0
105     */
106    public @NonNull ScimAttributeSelection getAttributeSelection() {
107        return attributeSelection;
108    }
109
110    /** Returns the canonical schema-bound sort path, when requested.
111     * Applications own appropriate string collation, primary-or-first multivalue selection,
112     * absent-value ordering and a stable authoritative-ID tie-break.
113     * @return the sort path, or empty when sorting was not requested
114     * @since 1.0.0
115     */
116    public @NonNull Optional<@NonNull ScimAttributePath> getSortBy() {
117        return Optional.ofNullable(sortBy);
118    }
119
120    /** Returns the selected direction when sortBy is present; otherwise returns empty.
121     * A supplied sortBy with no sortOrder selects {@link ScimSortOrder#ASCENDING}.
122     * @return the bound direction, or empty when sorting was not requested
123     * @since 1.0.0
124     */
125    public @NonNull Optional<@NonNull ScimSortOrder> getSortOrder() {
126        return Optional.ofNullable(sortOrder);
127    }
128
129    /** Returns the selected page-framing method.
130     * An explicit cursor selects CURSOR, an explicit startIndex selects INDEX, and otherwise the
131     * provider's configured default applies. Cursor and startIndex cannot both be supplied.
132     * @return the selected pagination method
133     * @since 1.0.0
134     */
135    public @NonNull ScimPaginationMethod getPaginationMethod() {
136        return paginationMethod;
137    }
138
139    /** Returns the normalized one-based start index for INDEX framing, and empty for CURSOR.
140     * The index defaults to one; explicitly supplied values below one become one.
141     * @return the effective index, or empty for cursor pagination
142     * @since 1.0.0
143     */
144    public @NonNull Optional<@NonNull Long> getStartIndex() {
145        return Optional.ofNullable(startIndex);
146    }
147
148    /** Returns the effective nonnegative page-size bound after defaults and configured caps.
149     * INDEX requests are clamped to those caps; oversized CURSOR requests reject during parsing.
150     * Zero denotes a count-only operation with no resources or traversal cursors and an accurate
151     * totalResults value in the application-authored page.
152     * @return the effective count
153     * @since 1.0.0
154     */
155    public @NonNull Integer getCount() {
156        return count;
157    }
158
159    /** Returns the original explicitly supplied signed count, before normalization or clamping.
160     * Negative values remain visible here even though the effective count becomes zero. Empty means
161     * the count field was absent. Applications can retain both this presence/original value and
162     * {@link #getCount()} when checking a cursor's page-size context.
163     * @return the original requested count, or empty when the field was absent
164     * @since 1.0.0
165     */
166    public @NonNull Optional<@NonNull Long> getRequestedCount() {
167        return Optional.ofNullable(requestedCount);
168    }
169
170    /** Returns the original decoded opaque cursor when explicitly supplied.
171     * An explicit empty string remains present and denotes the first cursor page. An absent cursor
172     * also denotes the first page when CURSOR is the configured default. Core validates grammar and
173     * framing; applications authenticate the token and bind tenant, caller, permissions, resource
174     * type, approved query, sort, projection, page size and expiry.
175     * @return the supplied cursor, including an explicit empty string, or empty when absent
176     * @since 1.0.0
177     */
178    public @NonNull Optional<@NonNull String> getCursor() {
179        return Optional.ofNullable(cursor);
180    }
181
182    /** Reports first-page framing: true exactly for CURSOR with an absent or empty cursor.
183     * This is always false for INDEX and establishes neither cursor authenticity nor storage state.
184     * @return whether this is the first cursor page
185     * @since 1.0.0
186     */
187    public @NonNull Boolean isFirstCursorPage() {
188        return firstCursorPage;
189    }
190
191    @NonNull Object getSemanticContext() {
192        return semanticContext;
193    }
194
195    int maximumCursorCharacters() {
196        return maximumCursorCharacters;
197    }
198
199    /** Returns a redacted diagnostic.
200     * @return description
201     * @since 1.0.0
202     */
203    @Override
204    public @NonNull String toString() {
205        return "ScimQuery{<redacted>}";
206    }
207}