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 org.jspecify.annotations.NonNull;
021import org.jspecify.annotations.Nullable;
022import javax.annotation.concurrent.Immutable;
023import java.util.Objects;
024
025/**
026 * Immutable registration of a required or optional application-resource schema extension.
027 * @since 1.0.0
028 */
029@Immutable
030@CheckReturnValue
031public final class ScimSchemaExtension {
032    private final @NonNull ScimSchema schema;
033    private final boolean required;
034    private ScimSchemaExtension(@NonNull ScimSchema schema, boolean required) {
035        this.schema = schema; this.required = required;
036        if (schema.isDiscovery())
037            throw new IllegalArgumentException("Discovery schemas cannot extend application resources.");
038    }
039
040    /**
041     * Registers a schema extension with an explicit required characteristic.
042     * @param schema the required extension schema
043     * @param required whether the extension is required
044     * @return the immutable registration
045     * @since 1.0.0
046     */
047    public static @NonNull ScimSchemaExtension fromSchema(@NonNull ScimSchema schema, @NonNull Boolean required) {
048        return new ScimSchemaExtension(Objects.requireNonNull(schema), Objects.requireNonNull(required));
049    }
050
051    /**
052     * Returns the registered schema.
053     * @return the registered schema
054     * @since 1.0.0
055     */
056    public @NonNull ScimSchema getSchema() { return schema; }
057
058    /**
059     * Returns whether the extension is required.
060     * @return whether the extension is required
061     * @since 1.0.0
062     */
063    public @NonNull Boolean isRequired() { return required; }
064
065    /**
066     * Compares extension schema and required characteristics.
067     * @param other the comparison value
068     * @return whether the extensions are equal
069     * @since 1.0.0
070     */
071    @Override public boolean equals(@Nullable Object other) {
072        return this == other || (other instanceof ScimSchemaExtension value
073                && required == value.required && schema.equals(value.schema));
074    }
075
076    /**
077     * Returns the semantic registration hash.
078     * @return the semantic hash
079     * @since 1.0.0
080     */
081    @Override public int hashCode() { return Objects.hash(schema, required); }
082
083    /**
084     * Returns a fixed redacted description.
085     * @return a fixed redacted description
086     * @since 1.0.0
087     */
088    @Override public @NonNull String toString() { return "ScimSchemaExtension{<redacted>}"; }
089}