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;
024
025import java.util.*;
026
027import javax.annotation.concurrent.Immutable;
028
029/** Bound projection with private registration provenance; never grants access.
030 * @since 1.0.0
031 */
032@Immutable
033@CheckReturnValue
034public final class ScimAttributeSelection {
035    private final @NonNull ScimResourceType resourceType;
036    private final @NonNull Set<@NonNull ScimAttributePath> includedAttributes;
037    private final @NonNull Set<@NonNull ScimAttributePath> excludedAttributes;
038    private final boolean explicit;
039    private final @NonNull Object semanticContext;
040
041    ScimAttributeSelection(
042            @NonNull ScimResourceType type,
043            @NonNull Set<@NonNull ScimAttributePath> included,
044            @NonNull Set<@NonNull ScimAttributePath> excluded,
045            boolean explicit,
046            @NonNull Object context) {
047        resourceType = requireNonNull(type);
048        includedAttributes = Set.copyOf(included);
049        excludedAttributes = Set.copyOf(excluded);
050        this.explicit = explicit;
051        semanticContext = requireNonNull(context);
052    }
053
054    /** Returns the registered resource type.
055     * @return type
056     * @since 1.0.0
057     */
058    public @NonNull ScimResourceType getResourceType() {
059        return resourceType;
060    }
061
062    /** Returns complete inclusion paths.
063     * @return immutable paths
064     * @since 1.0.0
065     */
066    public @NonNull Set<@NonNull ScimAttributePath> getIncludedAttributes() {
067        return includedAttributes;
068    }
069
070    /** Returns complete exclusion paths.
071     * @return immutable paths
072     * @since 1.0.0
073     */
074    public @NonNull Set<@NonNull ScimAttributePath> getExcludedAttributes() {
075        return excludedAttributes;
076    }
077
078    /** Reports whether projection was supplied.
079     * @return explicit state
080     * @since 1.0.0
081     */
082    public @NonNull Boolean isExplicit() {
083        return explicit;
084    }
085
086    /** Checks raw projection membership with parent/child expansion.
087     * Returned characteristics and caller authorization are separate checks.
088     * @param path canonical path; schema and attribute spelling compare with ASCII folding
089     * @return whether the path participates in the selection
090     * @since 1.0.0
091     */
092    public @NonNull Boolean includes(@NonNull ScimAttributePath path) {
093        requireNonNull(path);
094        for (ScimAttributePath excluded : excludedAttributes)
095            if (covers(excluded, path)) return false;
096        if (includedAttributes.isEmpty()) return true;
097        for (ScimAttributePath included : includedAttributes)
098            if (covers(included, path) || covers(path, included)) return true;
099        return false;
100    }
101
102    static boolean covers(@NonNull ScimAttributePath parent, @NonNull ScimAttributePath child) {
103        return parent.getSchemaId().map(com.revetsec.internal.json.AsciiCase::fold)
104                        .equals(child.getSchemaId().map(com.revetsec.internal.json.AsciiCase::fold))
105                && com.revetsec.internal.json.AsciiCase.fold(parent.getAttributeName())
106                        .equals(com.revetsec.internal.json.AsciiCase.fold(child.getAttributeName()))
107                && (parent.getSubAttributeName().isEmpty() || parent.equals(child));
108    }
109
110    @NonNull Object getSemanticContext() {
111        return semanticContext;
112    }
113
114    /** Returns a fixed diagnostic.
115     * @return description
116     * @since 1.0.0
117     */
118    @Override
119    public @NonNull String toString() {
120        return "ScimAttributeSelection{<redacted>}";
121    }
122}