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}