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}