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