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;
020import com.revetsec.internal.json.AsciiCase;
021import com.revetsec.internal.Limits;
022import org.jspecify.annotations.NonNull;
023import org.jspecify.annotations.Nullable;
024import javax.annotation.concurrent.Immutable;
025import javax.annotation.concurrent.NotThreadSafe;
026import java.util.List;
027import java.util.Objects;
028import java.util.Optional;
029import java.util.Set;
030
031/**
032 * Immutable SCIM attribute characteristics. Canonical values are suggested values, not an
033 * enforced whitelist. Application-resource schemas permit only one complex attribute level.
034 *
035 * @since 1.0.0
036 */
037@Immutable
038@CheckReturnValue
039public final class ScimAttributeDefinition {
040    private final @NonNull String name;
041    private final @NonNull ScimAttributeType type;
042    private final @Nullable String description;
043    private final boolean multiValued;
044    private final boolean required;
045    private final boolean caseExact;
046    private final @NonNull ScimMutability mutability;
047    private final @NonNull ScimReturned returned;
048    private final @NonNull ScimUniqueness uniqueness;
049    private final @NonNull Set<@NonNull String> canonicalValues;
050    private final @NonNull Set<@NonNull String> referenceTypes;
051    private final @NonNull List<@NonNull ScimAttributeDefinition> subAttributes;
052    private final int definitionCount;
053    private final int definitionDepth;
054
055    private ScimAttributeDefinition(@NonNull Builder builder) {
056        name = builder.name;
057        type = builder.type == null ? ScimAttributeType.STRING : builder.type;
058        description = builder.description;
059        multiValued = Boolean.TRUE.equals(builder.multiValued);
060        required = Boolean.TRUE.equals(builder.required);
061        caseExact = Boolean.TRUE.equals(builder.caseExact);
062        mutability = builder.mutability == null ? ScimMutability.READ_WRITE : builder.mutability;
063        returned = builder.returned == null ? ScimReturned.DEFAULT : builder.returned;
064        uniqueness = builder.uniqueness == null ? ScimUniqueness.NONE : builder.uniqueness;
065        canonicalValues = builder.canonicalValues;
066        referenceTypes = builder.referenceTypes;
067        subAttributes = builder.subAttributes;
068        if (type != ScimAttributeType.COMPLEX && !subAttributes.isEmpty())
069            throw new IllegalArgumentException("Only a complex SCIM attribute has subattributes.");
070        if (type != ScimAttributeType.REFERENCE && !referenceTypes.isEmpty())
071            throw new IllegalArgumentException("Only a reference SCIM attribute has reference types.");
072        if (caseExact && type != ScimAttributeType.STRING && type != ScimAttributeType.REFERENCE
073                && type != ScimAttributeType.BINARY)
074            throw new IllegalArgumentException("SCIM caseExact applies only to string-like attributes.");
075        if ((type == ScimAttributeType.COMPLEX || type == ScimAttributeType.BOOLEAN
076                || type == ScimAttributeType.DATE_TIME || type == ScimAttributeType.BINARY)
077                && uniqueness != ScimUniqueness.NONE)
078            throw new IllegalArgumentException("This SCIM attribute type has no uniqueness characteristic.");
079        if (mutability == ScimMutability.WRITE_ONLY && returned != ScimReturned.NEVER)
080            throw new IllegalArgumentException("A write-only SCIM attribute must never be returned.");
081        if (type != ScimAttributeType.STRING && !canonicalValues.isEmpty())
082            throw new IllegalArgumentException("SCIM canonical values require a string attribute.");
083        ScimSchemas.requireDistinctAttributes(subAttributes);
084        int count = 1;
085        int depth = 1;
086        for (ScimAttributeDefinition child : subAttributes) {
087            count += child.definitionCount;
088            depth = Math.max(depth, 1 + child.definitionDepth);
089        }
090        ScimSchemas.requireDefinitionCount(count);
091        if (depth > Limits.SCIM_FILTER_DEPTH.getCap())
092            throw new IllegalArgumentException("SCIM attribute definition nesting exceeds its limit.");
093        definitionCount = count;
094        definitionDepth = depth;
095    }
096
097    /**
098     * Starts a definition for a bounded attribute name. The special {@code $ref} is permitted
099     * here for subattributes, while a schema rejects it as a top-level application attribute.
100     * @param name the required name
101     * @return a new builder
102     * @since 1.0.0
103     */
104    public static @NonNull Builder withName(@NonNull String name) {
105        return new Builder(ScimSchemas.requireAttributeName(name));
106    }
107
108    /**
109     * Returns the canonical attribute name.
110     * @return the canonical attribute name
111     * @since 1.0.0
112     */
113    public @NonNull String getName() { return name; }
114
115    /**
116     * Returns the declared attribute type.
117     * @return the declared attribute type
118     * @since 1.0.0
119     */
120    public @NonNull ScimAttributeType getType() { return type; }
121
122    /**
123     * Returns the optional description.
124     * @return the optional description
125     * @since 1.0.0
126     */
127    public @NonNull Optional<@NonNull String> getDescription() { return Optional.ofNullable(description); }
128
129    /**
130     * Returns whether the attribute is multi-valued.
131     * @return whether the attribute is multi-valued
132     * @since 1.0.0
133     */
134    public @NonNull Boolean isMultiValued() { return multiValued; }
135
136    /**
137     * Returns whether assigned data is required.
138     * @return whether assigned data is required
139     * @since 1.0.0
140     */
141    public @NonNull Boolean isRequired() { return required; }
142
143    /**
144     * Returns whether string comparison is case exact.
145     * @return whether string comparison is case exact
146     * @since 1.0.0
147     */
148    public @NonNull Boolean isCaseExact() { return caseExact; }
149
150    /**
151     * Returns the write characteristic.
152     * @return the write characteristic
153     * @since 1.0.0
154     */
155    public @NonNull ScimMutability getMutability() { return mutability; }
156
157    /**
158     * Returns the response visibility characteristic.
159     * @return the response visibility characteristic
160     * @since 1.0.0
161     */
162    public @NonNull ScimReturned getReturned() { return returned; }
163
164    /**
165     * Returns the application-enforced uniqueness characteristic.
166     * @return the application-enforced uniqueness characteristic
167     * @since 1.0.0
168     */
169    public @NonNull ScimUniqueness getUniqueness() { return uniqueness; }
170
171    /**
172     * Returns the immutable suggested canonical values.
173     * @return the immutable suggested canonical values
174     * @since 1.0.0
175     */
176    public @NonNull Set<@NonNull String> getCanonicalValues() { return canonicalValues; }
177
178    /**
179     * Returns the immutable allowed reference-type descriptions.
180     * @return the immutable allowed reference-type descriptions
181     * @since 1.0.0
182     */
183    public @NonNull Set<@NonNull String> getReferenceTypes() { return referenceTypes; }
184
185    /**
186     * Returns the immutable subattribute definitions.
187     * @return the immutable subattribute definitions
188     * @since 1.0.0
189     */
190    public @NonNull List<@NonNull ScimAttributeDefinition> getSubAttributes() { return subAttributes; }
191
192    /**
193     * Compares semantic attribute characteristics, folding only the structural name.
194     * @param other the comparison value
195     * @return whether the definitions have equal characteristics
196     * @since 1.0.0
197     */
198    @Override public boolean equals(@Nullable Object other) {
199        return this == other || (other instanceof ScimAttributeDefinition value
200                && AsciiCase.fold(name).equals(AsciiCase.fold(value.name)) && type == value.type
201                && Objects.equals(description, value.description) && multiValued == value.multiValued
202                && required == value.required && caseExact == value.caseExact && mutability == value.mutability
203                && returned == value.returned && uniqueness == value.uniqueness
204                && canonicalValues.equals(value.canonicalValues) && referenceTypes.equals(value.referenceTypes)
205                && subAttributes.equals(value.subAttributes));
206    }
207
208    /**
209     * Returns the hash of semantic attribute characteristics.
210     * @return the semantic hash
211     * @since 1.0.0
212     */
213    @Override public int hashCode() {
214        return Objects.hash(AsciiCase.fold(name), type, description, multiValued, required, caseExact,
215                mutability, returned, uniqueness, canonicalValues, referenceTypes, subAttributes);
216    }
217
218    /**
219     * Returns a fixed description without configured schema data.
220     * @return a fixed redacted description
221     * @since 1.0.0
222     */
223    @Override public @NonNull String toString() { return "ScimAttributeDefinition{<redacted>}"; }
224
225    int definitionCount() { return definitionCount; }
226
227    /**
228     * Mutable, non-thread-safe definition configuration. Null restores the stated default.
229     * Collections replace the complete value and are bounded before an immutable snapshot.
230     * @since 1.0.0
231     */
232    @NotThreadSafe
233    @CheckReturnValue
234    public static final class Builder {
235        private final @NonNull String name;
236        private @Nullable ScimAttributeType type;
237        private @Nullable String description;
238        private @Nullable Boolean multiValued;
239        private @Nullable Boolean required;
240        private @Nullable Boolean caseExact;
241        private @Nullable ScimMutability mutability;
242        private @Nullable ScimReturned returned;
243        private @Nullable ScimUniqueness uniqueness;
244        private @NonNull Set<@NonNull String> canonicalValues = Set.of();
245        private @NonNull Set<@NonNull String> referenceTypes = Set.of();
246        private @NonNull List<@NonNull ScimAttributeDefinition> subAttributes = List.of();
247        private Builder(@NonNull String name) { this.name = name; }
248
249        /**
250         * Sets type; null restores STRING.
251         * @param value the replacement, or null to restore its default
252         * @return this builder
253         * @since 1.0.0
254         */
255        public @NonNull Builder type(@Nullable ScimAttributeType value) { type = value; return this; }
256
257        /**
258         * Sets description; null restores absent.
259         * @param value the replacement, or null to restore its default
260         * @return this builder
261         * @since 1.0.0
262         */
263        public @NonNull Builder description(@Nullable String value) { description = value == null ? null : ScimSchemas.requireText(value, false); return this; }
264
265        /**
266         * Sets multiValued; null restores false.
267         * @param value the replacement, or null to restore its default
268         * @return this builder
269         * @since 1.0.0
270         */
271        public @NonNull Builder multiValued(@Nullable Boolean value) { multiValued = value; return this; }
272
273        /**
274         * Sets required; null restores false.
275         * @param value the replacement, or null to restore its default
276         * @return this builder
277         * @since 1.0.0
278         */
279        public @NonNull Builder required(@Nullable Boolean value) { required = value; return this; }
280
281        /**
282         * Sets caseExact; null restores false.
283         * @param value the replacement, or null to restore its default
284         * @return this builder
285         * @since 1.0.0
286         */
287        public @NonNull Builder caseExact(@Nullable Boolean value) { caseExact = value; return this; }
288
289        /**
290         * Sets mutability; null restores READ_WRITE.
291         * @param value the replacement, or null to restore its default
292         * @return this builder
293         * @since 1.0.0
294         */
295        public @NonNull Builder mutability(@Nullable ScimMutability value) { mutability = value; return this; }
296
297        /**
298         * Sets returned; null restores DEFAULT.
299         * @param value the replacement, or null to restore its default
300         * @return this builder
301         * @since 1.0.0
302         */
303        public @NonNull Builder returned(@Nullable ScimReturned value) { returned = value; return this; }
304
305        /**
306         * Sets uniqueness; null restores NONE.
307         * @param value the replacement, or null to restore its default
308         * @return this builder
309         * @since 1.0.0
310         */
311        public @NonNull Builder uniqueness(@Nullable ScimUniqueness value) { uniqueness = value; return this; }
312
313        /**
314         * Sets canonicalValues; null restores empty.
315         * @param value the replacement, or null to restore its default
316         * @return this builder
317         * @since 1.0.0
318         */
319        public @NonNull Builder canonicalValues(@Nullable Set<@NonNull String> value) { canonicalValues = value == null ? Set.of() : ScimSchemas.stringSet(value); return this; }
320
321        /**
322         * Sets referenceTypes; null restores empty.
323         * @param value the replacement, or null to restore its default
324         * @return this builder
325         * @since 1.0.0
326         */
327        public @NonNull Builder referenceTypes(@Nullable Set<@NonNull String> value) { referenceTypes = value == null ? Set.of() : ScimSchemas.stringSet(value); return this; }
328
329        /**
330         * Sets subAttributes; null restores empty.
331         * @param value the replacement, or null to restore its default
332         * @return this builder
333         * @since 1.0.0
334         */
335        public @NonNull Builder subAttributes(@Nullable List<@NonNull ScimAttributeDefinition> value) { subAttributes = value == null ? List.of() : ScimSchemas.attributes(value); return this; }
336
337        /**
338         * Validates compatible characteristics and creates an immutable definition.
339         * @return the definition
340         * @since 1.0.0
341         */
342        public @NonNull ScimAttributeDefinition build() { return new ScimAttributeDefinition(this); }
343    }
344}