1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.metaschema.databind.model.annotations;
7   
8   import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
9   import static java.lang.annotation.RetentionPolicy.RUNTIME;
10  
11  import gov.nist.secauto.metaschema.core.model.constraint.IAllowedValuesConstraint;
12  import gov.nist.secauto.metaschema.core.model.constraint.IConstraint;
13  import gov.nist.secauto.metaschema.core.model.constraint.IConstraint.Level;
14  
15  import java.lang.annotation.Documented;
16  import java.lang.annotation.Retention;
17  import java.lang.annotation.Target;
18  
19  import edu.umd.cs.findbugs.annotations.NonNull;
20  
21  /**
22   * This annotation defines a set of values permitted to be used in the context
23   * of the containing annotation.
24   */
25  @Documented
26  @Retention(RUNTIME)
27  @Target(ANNOTATION_TYPE)
28  public @interface AllowedValues {
29    /**
30     * An optional identifier for the constraint, which must be unique to only this
31     * constraint.
32     *
33     * @return the identifier if provided or an empty string otherwise
34     */
35    @SuppressWarnings("PMD.ShortMethodName")
36    @NonNull
37    String id() default "";
38  
39    /**
40     * An optional formal name for the constraint.
41     *
42     * @return the formal name if provided or an empty string otherwise
43     */
44    @NonNull
45    String formalName() default "";
46  
47    /**
48     * An optional description of the constraint.
49     *
50     * @return the description if provided or an empty string otherwise
51     */
52    @NonNull
53    String description() default "";
54  
55    /**
56     * The significance of a violation of this constraint.
57     *
58     * @return the level
59     */
60    @NonNull
61    Level level() default IConstraint.Level.ERROR;
62  
63    /**
64     * An optional metapath that points to the target flag or field value that the
65     * constraint applies to. If omitted the target will be ".", which means the
66     * target is the value of the {@link BoundFlag}, {@link BoundField} or
67     * {@link BoundFieldValue} annotation the constraint appears on. In the prior
68     * case, this annotation may only appear on a {@link BoundField} if the field
69     * has no flags, which results in a {@link BoundField} annotation on a field
70     * instance with a scalar, data type value.
71     *
72     * @return the target metapath
73     */
74    @NonNull
75    String target() default IConstraint.DEFAULT_TARGET_METAPATH;
76  
77    /**
78     * An optional set of properties associated with these allowed values.
79     *
80     * @return the properties or an empty array with no properties
81     */
82    Property[] properties() default {};
83  
84    /**
85     * Get any allowed values for this constraint.
86     *
87     * @return an array of allowed value enumerations
88     */
89    @NonNull
90    AllowedValue[] values();
91  
92    /**
93     * Indicates if the constraint allows other values not included in the
94     * enumerated list.
95     *
96     * @return {@code true} if other values are allowed or {@code false} otherwise
97     */
98    boolean allowOthers() default IAllowedValuesConstraint.ALLOW_OTHER_DEFAULT;
99  
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 }