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;
020
021import org.jspecify.annotations.NonNull;
022
023import java.util.*;
024
025/** Application-owned attribute-aware matching; deterministic, bounded and non-I/O.
026 * No Unicode or username preparation default is provided.
027 * Unexpected ordinary failures, including a null return, become fixed internalError results.
028 * The facade restores a thrown InterruptedException's thread flag; fatal VM errors escape.
029 * @since 1.0.0
030 */
031@javax.annotation.concurrent.ThreadSafe
032public interface ScimStringMatching {
033    /** Compares one assigned value under the authoritative backend's rules.
034     * @param attributePath canonical attribute path
035     * @param definition bound definition
036     * @param operator requested operation
037     * @param value stored value
038     * @param literal comparison literal
039     * @return match or unsupported
040     * @since 1.0.0
041     */
042    @CheckReturnValue
043    @NonNull ScimStringMatchResult match(
044            @NonNull ScimAttributePath attributePath,
045            @NonNull ScimAttributeDefinition definition,
046            @NonNull ScimComparisonOperator operator,
047            @NonNull String value,
048            @NonNull String literal);
049}