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.IConstraint;
12  import gov.nist.secauto.metaschema.core.model.constraint.IConstraint.Level;
13  
14  import java.lang.annotation.Documented;
15  import java.lang.annotation.Retention;
16  import java.lang.annotation.Target;
17  
18  import edu.umd.cs.findbugs.annotations.NonNull;
19  
20  /**
21   * This annotation defines cardinality condition(s) to be met in the context of
22   * the containing annotation.
23   */
24  @Documented
25  @Retention(RUNTIME)
26  @Target(ANNOTATION_TYPE)
27  public @interface HasCardinality {
28    /**
29     * An optional identifier for the constraint, which must be unique to only this
30     * constraint.
31     *
32     * @return the identifier if provided or an empty string otherwise
33     */
34    @SuppressWarnings("PMD.ShortMethodName")
35    @NonNull
36    String id() default "";
37  
38    /**
39     * An optional formal name for the constraint.
40     *
41     * @return the formal name if provided or an empty string otherwise
42     */
43    @NonNull
44    String formalName() default "";
45  
46    /**
47     * An optional description of the constraint.
48     *
49     * @return the description if provided or an empty string otherwise
50     */
51    @NonNull
52    String description() default "";
53  
54    /**
55     * The significance of a violation of this constraint.
56     *
57     * @return the level
58     */
59    @NonNull
60    Level level() default IConstraint.Level.ERROR;
61  
62    /**
63     * An optional metapath that points to the target flag or field value that the
64     * constraint applies to. If omitted the target will be ".", which means the
65     * target is the value of the {@link BoundFlag}, {@link BoundField} or
66     * {@link BoundFieldValue} annotation the constraint appears on. In the prior
67     * case, this annotation may only appear on a {@link BoundField} if the field
68     * has no flags, which results in a {@link BoundField} annotation on a field
69     * instance with a scalar, data type value.
70     *
71     * @return the target metapath
72     */
73    @NonNull
74    String target() default ".";
75  
76    /**
77     * An optional set of properties associated with these allowed values.
78     *
79     * @return the properties or an empty array with no properties
80     */
81    Property[] properties() default {};
82  
83    /**
84     * The minimum occurrence of the target. This value cannot be less than or equal
85     * to the corresponding value defined on the target. The value must be greater
86     * than {@code 0}.
87     *
88     * @return a non-negative integer or {@code -1} if not defined
89     */
90    int minOccurs() default -1;
91  
92    /**
93     * The maximum occurrence of the target. This value must be greater than or
94     * equal to the {@link #minOccurs()} if both are provided. This value must be
95     * less than the corresponding value defined on the target.
96     *
97     * @return a non-negative integer or {@code -1} if not defined
98     */
99    int maxOccurs() default -1;
100 
101   /**
102    * The message to emit when the constraint is violated.
103    *
104    * @return the message or an empty string otherwise
105    */
106   @NonNull
107   String message() default "";
108 
109   /**
110    * Any remarks about the constraint, encoded as an escaped Markdown string.
111    *
112    * @return an encoded markdown string or an empty string if no remarks are
113    *         provided
114    */
115   @NonNull
116   String remarks() default "";
117 }