001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package gov.nist.secauto.metaschema.databind.model.annotations;
007
008import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
009import static java.lang.annotation.RetentionPolicy.RUNTIME;
010
011import gov.nist.secauto.metaschema.core.model.constraint.IAllowedValuesConstraint;
012import gov.nist.secauto.metaschema.core.model.constraint.IConstraint;
013import gov.nist.secauto.metaschema.core.model.constraint.IConstraint.Level;
014
015import java.lang.annotation.Documented;
016import java.lang.annotation.Retention;
017import java.lang.annotation.Target;
018
019import edu.umd.cs.findbugs.annotations.NonNull;
020
021/**
022 * This annotation defines a set of values permitted to be used in the context
023 * of the containing annotation.
024 */
025@Documented
026@Retention(RUNTIME)
027@Target(ANNOTATION_TYPE)
028public @interface AllowedValues {
029  /**
030   * An optional identifier for the constraint, which must be unique to only this
031   * constraint.
032   *
033   * @return the identifier if provided or an empty string otherwise
034   */
035  @SuppressWarnings("PMD.ShortMethodName")
036  @NonNull
037  String id() default "";
038
039  /**
040   * An optional formal name for the constraint.
041   *
042   * @return the formal name if provided or an empty string otherwise
043   */
044  @NonNull
045  String formalName() default "";
046
047  /**
048   * An optional description of the constraint.
049   *
050   * @return the description if provided or an empty string otherwise
051   */
052  @NonNull
053  String description() default "";
054
055  /**
056   * The significance of a violation of this constraint.
057   *
058   * @return the level
059   */
060  @NonNull
061  Level level() default IConstraint.Level.ERROR;
062
063  /**
064   * An optional metapath that points to the target flag or field value that the
065   * constraint applies to. If omitted the target will be ".", which means the
066   * target is the value of the {@link BoundFlag}, {@link BoundField} or
067   * {@link BoundFieldValue} annotation the constraint appears on. In the prior
068   * case, this annotation may only appear on a {@link BoundField} if the field
069   * has no flags, which results in a {@link BoundField} annotation on a field
070   * instance with a scalar, data type value.
071   *
072   * @return the target metapath
073   */
074  @NonNull
075  String target() default IConstraint.DEFAULT_TARGET_METAPATH;
076
077  /**
078   * An optional set of properties associated with these allowed values.
079   *
080   * @return the properties or an empty array with no properties
081   */
082  Property[] properties() default {};
083
084  /**
085   * Get any allowed values for this constraint.
086   *
087   * @return an array of allowed value enumerations
088   */
089  @NonNull
090  AllowedValue[] values();
091
092  /**
093   * Indicates if the constraint allows other values not included in the
094   * enumerated list.
095   *
096   * @return {@code true} if other values are allowed or {@code false} otherwise
097   */
098  boolean allowOthers() default IAllowedValuesConstraint.ALLOW_OTHER_DEFAULT;
099
100  /**
101   * Indicates if the constraint can be extended by other constraints.
102   *
103   * @return the extension mode
104   */
105  @NonNull
106  IAllowedValuesConstraint.Extensible extensible() default IAllowedValuesConstraint.Extensible.EXTERNAL;
107
108  /**
109   * The message to emit when the constraint is violated.
110   *
111   * @return the message or an empty string otherwise
112   */
113  @NonNull
114  String message() default "";
115
116  /**
117   * Any remarks about the constraint, encoded as an escaped Markdown string.
118   *
119   * @return an encoded markdown string or an empty string if no remarks are
120   *         provided
121   */
122  @NonNull
123  String remarks() default "";
124}