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 */ 016package com.revetsec.scim; 017 018import org.jspecify.annotations.NonNull; 019import org.jspecify.annotations.Nullable; 020 021import com.google.errorprone.annotations.CheckReturnValue; 022import javax.annotation.concurrent.Immutable; 023import java.util.List; 024 025import static java.util.Objects.requireNonNull; 026 027/** 028 * A bounded immutable SCIM filter syntax tree (RFC 7644 section 3.4.2.2). 029 * AND and OR are ordered, flattened n-ary nodes. NOT binds more tightly than 030 * AND, which binds more tightly than OR. ValuePath predicates describe one 031 * array element and cannot contain another ValuePath. 032 * <p> 033 * A successful syntax parse does not bind paths to schemas, validate attribute 034 * types, approve a filter policy, or authorize query execution. Applications 035 * must perform those checks before using a tree to select resources. 036 * <p> 037 * Parsed and schema-bound roots privately retain their bounded original expression for later 038 * receiving-provider checks. This text may contain personal data and grants no query permission. 039 * Equality is structural, with the path's ASCII case-insensitive equality and 040 * numeric-value literal equality. Explicit serialization contains the complete 041 * filter and may expose personal data; every diagnostic toString redacts it. 042 * <p> 043 * The six permitted node kinds are stable within a major version and may be matched exhaustively. 044 * Adding a node kind or an abstract visitor callback requires a major release. 045 * 046 * @since 1.0.0 047 */ 048@Immutable 049public sealed interface ScimFilter permits ScimFilter.And, ScimFilter.Or, ScimFilter.Not, 050 ScimFilter.Comparison, ScimFilter.Present, ScimFilter.ValuePath { 051 /** 052 * Parses filter syntax under the shared immutable default limits. 053 * 054 * @param expression untrusted filter expression 055 * @return success or a fixed rejection with a UTF-16 expression offset 056 * @throws NullPointerException if expression is null 057 * @since 1.0.0 058 */ 059 @CheckReturnValue 060 static @NonNull ScimFilterParseResult fromExpressionResult(@NonNull String expression) { 061 return fromExpressionResult(expression, ScimFilterLimits.defaultInstance()); 062 } 063 064 /** 065 * Parses filter syntax directly into a result, without exception-driven 066 * handling of malformed input. Bounds apply before recursive stack growth, 067 * AST construction and literal/number allocation. Depth covers retained AST 068 * levels as well as transient grouping/NOT/ValuePath nesting; nodes count 069 * the retained flattened tree, rather than discarded parentheses. 070 * 071 * @param expression untrusted filter expression 072 * @param limits immutable limits 073 * @return syntax success or a fixed rejection with a UTF-16 expression offset 074 * @throws NullPointerException if either argument is null 075 * @since 1.0.0 076 */ 077 @CheckReturnValue 078 static @NonNull ScimFilterParseResult fromExpressionResult( 079 @NonNull String expression, @NonNull ScimFilterLimits limits) { 080 return new ScimFilterParser(requireNonNull(expression), requireNonNull(limits)).parse(); 081 } 082 083 /** 084 * Dispatches this node to a Java 17 visitor. The visitor controls traversal. 085 * 086 * @param visitor visitor 087 * @param <R> nonnull result type 088 * @return the visitor's result 089 * @throws NullPointerException if visitor or its result is null 090 * @since 1.0.0 091 */ 092 @CheckReturnValue 093 <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor); 094 095 /** 096 * Emits a canonical filter with lowercase operators and minimal grouping. 097 * Strings use JSON escapes; numeric exponent notation remains compact and 098 * never expands an exponent into zeros. The output contains personal data and can exceed 099 * the original input-character limit after schema normalization. Rendering does not prove 100 * that this text fits a receiving parser's limits. 101 * 102 * @return canonical SCIM syntax, subject to receiving parser limits 103 * @since 1.0.0 104 */ 105 @CheckReturnValue 106 @NonNull String toScimString(); 107 108 /** An ordered flattened conjunction. 109 * @since 1.0.0 110 */ 111 @Immutable 112 final class And implements ScimFilter { 113 private final @NonNull List<@NonNull ScimFilter> operands; 114 // Root-only lexical provenance; excluded from structural equality, hashing and rendering. 115 private final @Nullable String sourceExpression; 116 @Nullable String sourceExpression() { return sourceExpression; } 117 And(@NonNull List<@NonNull ScimFilter> operands) { this(operands, null); } 118 And(@NonNull List<@NonNull ScimFilter> operands, @Nullable String sourceExpression) { 119 this.operands = List.copyOf(operands); 120 this.sourceExpression = sourceExpression; 121 } 122 123 /** Returns ordered conjunction operands. 124 * @return immutable operands 125 * @since 1.0.0 126 */ 127 @CheckReturnValue public @NonNull List<@NonNull ScimFilter> getOperands() { return this.operands; } 128 /** Dispatches this node. 129 * @param visitor visitor 130 * @param <R> result type 131 * @return result 132 * @since 1.0.0 133 */ 134 @Override @CheckReturnValue 135 public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) { 136 return requireNonNull(requireNonNull(visitor).visitAnd(this)); 137 } 138 /** Emits filter data. 139 * @return canonical syntax 140 * @since 1.0.0 141 */ 142 @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); } 143 /** Compares ordered structure. 144 * @param other candidate 145 * @return equality 146 * @since 1.0.0 147 */ 148 @Override public boolean equals(@Nullable Object other) { 149 return this == other || (other instanceof And filter && this.operands.equals(filter.operands)); 150 } 151 /** Returns the structural hash. 152 * @return hash 153 * @since 1.0.0 154 */ 155 @Override public int hashCode() { return 31 * this.operands.hashCode(); } 156 /** Redacts filter data. 157 * @return redacted description 158 * @since 1.0.0 159 */ 160 @Override public @NonNull String toString() { return "ScimFilter.And{operands=<redacted>}"; } 161 } 162 163 /** An ordered flattened disjunction. 164 * @since 1.0.0 165 */ 166 @Immutable 167 final class Or implements ScimFilter { 168 private final @NonNull List<@NonNull ScimFilter> operands; 169 // Root-only lexical provenance; excluded from structural equality, hashing and rendering. 170 private final @Nullable String sourceExpression; 171 @Nullable String sourceExpression() { return sourceExpression; } 172 Or(@NonNull List<@NonNull ScimFilter> operands) { this(operands, null); } 173 Or(@NonNull List<@NonNull ScimFilter> operands, @Nullable String sourceExpression) { 174 this.operands = List.copyOf(operands); 175 this.sourceExpression = sourceExpression; 176 } 177 178 /** Returns ordered disjunction operands. 179 * @return immutable operands 180 * @since 1.0.0 181 */ 182 @CheckReturnValue public @NonNull List<@NonNull ScimFilter> getOperands() { return this.operands; } 183 /** Dispatches this node. 184 * @param visitor visitor 185 * @param <R> result type 186 * @return result 187 * @since 1.0.0 188 */ 189 @Override @CheckReturnValue 190 public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) { 191 return requireNonNull(requireNonNull(visitor).visitOr(this)); 192 } 193 /** Emits filter data. 194 * @return canonical syntax 195 * @since 1.0.0 196 */ 197 @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); } 198 /** Compares ordered structure. 199 * @param other candidate 200 * @return equality 201 * @since 1.0.0 202 */ 203 @Override public boolean equals(@Nullable Object other) { 204 return this == other || (other instanceof Or filter && this.operands.equals(filter.operands)); 205 } 206 /** Returns the structural hash. 207 * @return hash 208 * @since 1.0.0 209 */ 210 @Override public int hashCode() { return 37 * this.operands.hashCode(); } 211 /** Redacts filter data. 212 * @return redacted description 213 * @since 1.0.0 214 */ 215 @Override public @NonNull String toString() { return "ScimFilter.Or{operands=<redacted>}"; } 216 } 217 218 /** Negation of a grouped predicate. 219 * @since 1.0.0 220 */ 221 @Immutable 222 final class Not implements ScimFilter { 223 private final @NonNull ScimFilter operand; 224 // Root-only lexical provenance; excluded from structural equality, hashing and rendering. 225 private final @Nullable String sourceExpression; 226 @Nullable String sourceExpression() { return sourceExpression; } 227 Not(@NonNull ScimFilter operand) { this(operand, null); } 228 Not(@NonNull ScimFilter operand, @Nullable String sourceExpression) { 229 this.operand = requireNonNull(operand); 230 this.sourceExpression = sourceExpression; 231 } 232 233 /** Returns the operand. 234 * @return operand 235 * @since 1.0.0 236 */ 237 @CheckReturnValue public @NonNull ScimFilter getOperand() { return this.operand; } 238 239 /** Dispatches this node. 240 * @param visitor visitor 241 * @param <R> result type 242 * @return result 243 * @since 1.0.0 244 */ 245 @Override @CheckReturnValue 246 public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) { 247 return requireNonNull(requireNonNull(visitor).visitNot(this)); 248 } 249 /** Emits filter data. 250 * @return canonical syntax 251 * @since 1.0.0 252 */ 253 @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); } 254 /** Compares structure. 255 * @param other candidate 256 * @return equality 257 * @since 1.0.0 258 */ 259 @Override public boolean equals(@Nullable Object other) { 260 return this == other || (other instanceof Not filter 261 && this.operand.equals(filter.operand)); 262 } 263 /** Returns the structural hash. 264 * @return hash 265 * @since 1.0.0 266 */ 267 @Override public int hashCode() { return this.operand.hashCode(); } 268 /** Redacts filter data. 269 * @return redacted description 270 * @since 1.0.0 271 */ 272 @Override public @NonNull String toString() { return "ScimFilter.Not{filter=<redacted>}"; } 273 } 274 275 /** An attribute comparison with a JSON literal. 276 * @since 1.0.0 277 */ 278 @Immutable 279 final class Comparison implements ScimFilter { 280 private final @NonNull ScimAttributePath attributePath; 281 private final @NonNull ScimComparisonOperator operator; 282 private final @NonNull ScimFilterValue value; 283 // Root-only lexical provenance; excluded from structural equality, hashing and rendering. 284 private final @Nullable String sourceExpression; 285 @Nullable String sourceExpression() { return sourceExpression; } 286 Comparison(@NonNull ScimAttributePath attributePath, @NonNull ScimComparisonOperator operator, @NonNull ScimFilterValue value) { this(attributePath, operator, value, null); } 287 Comparison(@NonNull ScimAttributePath attributePath, @NonNull ScimComparisonOperator operator, @NonNull ScimFilterValue value, @Nullable String sourceExpression) { 288 this.attributePath = requireNonNull(attributePath); 289 this.operator = requireNonNull(operator); 290 this.value = requireNonNull(value); 291 this.sourceExpression = sourceExpression; 292 } 293 294 /** Returns the attributePath. 295 * @return attributePath 296 * @since 1.0.0 297 */ 298 @CheckReturnValue public @NonNull ScimAttributePath getAttributePath() { return this.attributePath; } 299 /** Returns the operator. 300 * @return operator 301 * @since 1.0.0 302 */ 303 @CheckReturnValue public @NonNull ScimComparisonOperator getOperator() { return this.operator; } 304 /** Returns the value. 305 * @return value 306 * @since 1.0.0 307 */ 308 @CheckReturnValue public @NonNull ScimFilterValue getValue() { return this.value; } 309 310 /** Dispatches this node. 311 * @param visitor visitor 312 * @param <R> result type 313 * @return result 314 * @since 1.0.0 315 */ 316 @Override @CheckReturnValue 317 public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) { 318 return requireNonNull(requireNonNull(visitor).visitComparison(this)); 319 } 320 /** Emits filter data. 321 * @return canonical syntax 322 * @since 1.0.0 323 */ 324 @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); } 325 /** Compares structure. 326 * @param other candidate 327 * @return equality 328 * @since 1.0.0 329 */ 330 @Override public boolean equals(@Nullable Object other) { 331 return this == other || (other instanceof Comparison filter 332 && this.attributePath.equals(filter.attributePath) && this.operator.equals(filter.operator) && this.value.equals(filter.value)); 333 } 334 /** Returns the structural hash. 335 * @return hash 336 * @since 1.0.0 337 */ 338 @Override public int hashCode() { return (31 * (31 * this.attributePath.hashCode() + this.operator.hashCode()) + this.value.hashCode()); } 339 /** Redacts filter data. 340 * @return redacted description 341 * @since 1.0.0 342 */ 343 @Override public @NonNull String toString() { return "ScimFilter.Comparison{filter=<redacted>}"; } 344 } 345 346 /** An attribute presence test. 347 * @since 1.0.0 348 */ 349 @Immutable 350 final class Present implements ScimFilter { 351 private final @NonNull ScimAttributePath attributePath; 352 // Root-only lexical provenance; excluded from structural equality, hashing and rendering. 353 private final @Nullable String sourceExpression; 354 @Nullable String sourceExpression() { return sourceExpression; } 355 Present(@NonNull ScimAttributePath attributePath) { this(attributePath, null); } 356 Present(@NonNull ScimAttributePath attributePath, @Nullable String sourceExpression) { 357 this.attributePath = requireNonNull(attributePath); 358 this.sourceExpression = sourceExpression; 359 } 360 361 /** Returns the attributePath. 362 * @return attributePath 363 * @since 1.0.0 364 */ 365 @CheckReturnValue public @NonNull ScimAttributePath getAttributePath() { return this.attributePath; } 366 367 /** Dispatches this node. 368 * @param visitor visitor 369 * @param <R> result type 370 * @return result 371 * @since 1.0.0 372 */ 373 @Override @CheckReturnValue 374 public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) { 375 return requireNonNull(requireNonNull(visitor).visitPresent(this)); 376 } 377 /** Emits filter data. 378 * @return canonical syntax 379 * @since 1.0.0 380 */ 381 @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); } 382 /** Compares structure. 383 * @param other candidate 384 * @return equality 385 * @since 1.0.0 386 */ 387 @Override public boolean equals(@Nullable Object other) { 388 return this == other || (other instanceof Present filter 389 && this.attributePath.equals(filter.attributePath)); 390 } 391 /** Returns the structural hash. 392 * @return hash 393 * @since 1.0.0 394 */ 395 @Override public int hashCode() { return this.attributePath.hashCode(); } 396 /** Redacts filter data. 397 * @return redacted description 398 * @since 1.0.0 399 */ 400 @Override public @NonNull String toString() { return "ScimFilter.Present{filter=<redacted>}"; } 401 } 402 403 /** A predicate whose relative paths refer to the same array element. 404 * @since 1.0.0 405 */ 406 @Immutable 407 final class ValuePath implements ScimFilter { 408 private final @NonNull ScimAttributePath attributePath; 409 private final @NonNull ScimFilter filter; 410 // Root-only lexical provenance; excluded from structural equality, hashing and rendering. 411 private final @Nullable String sourceExpression; 412 @Nullable String sourceExpression() { return sourceExpression; } 413 ValuePath(@NonNull ScimAttributePath attributePath, @NonNull ScimFilter filter) { this(attributePath, filter, null); } 414 ValuePath(@NonNull ScimAttributePath attributePath, @NonNull ScimFilter filter, @Nullable String sourceExpression) { 415 this.attributePath = requireNonNull(attributePath); 416 this.filter = requireNonNull(filter); 417 this.sourceExpression = sourceExpression; 418 } 419 420 /** Returns the attributePath. 421 * @return attributePath 422 * @since 1.0.0 423 */ 424 @CheckReturnValue public @NonNull ScimAttributePath getAttributePath() { return this.attributePath; } 425 /** Returns the filter. 426 * @return filter 427 * @since 1.0.0 428 */ 429 @CheckReturnValue public @NonNull ScimFilter getFilter() { return this.filter; } 430 431 /** Dispatches this node. 432 * @param visitor visitor 433 * @param <R> result type 434 * @return result 435 * @since 1.0.0 436 */ 437 @Override @CheckReturnValue 438 public <R extends @NonNull Object> @NonNull R accept(@NonNull ScimFilterVisitor<@NonNull R> visitor) { 439 return requireNonNull(requireNonNull(visitor).visitValuePath(this)); 440 } 441 /** Emits filter data. 442 * @return canonical syntax 443 * @since 1.0.0 444 */ 445 @Override @CheckReturnValue public @NonNull String toScimString() { return ScimFilterRendering.render(this); } 446 /** Compares structure. 447 * @param other candidate 448 * @return equality 449 * @since 1.0.0 450 */ 451 @Override public boolean equals(@Nullable Object other) { 452 return this == other || (other instanceof ValuePath filter 453 && this.attributePath.equals(filter.attributePath) && this.filter.equals(filter.filter)); 454 } 455 /** Returns the structural hash. 456 * @return hash 457 * @since 1.0.0 458 */ 459 @Override public int hashCode() { return (31 * this.attributePath.hashCode() + this.filter.hashCode()); } 460 /** Redacts filter data. 461 * @return redacted description 462 * @since 1.0.0 463 */ 464 @Override public @NonNull String toString() { return "ScimFilter.ValuePath{filter=<redacted>}"; } 465 } 466}