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.TYPE;
9   import static java.lang.annotation.RetentionPolicy.RUNTIME;
10  
11  import gov.nist.secauto.metaschema.core.model.IFieldInstance;
12  import gov.nist.secauto.metaschema.databind.model.IBoundModule;
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 indicates that the target class represents a Module field.
22   * <p>
23   * Classes with this annotation must have a field with the
24   * {@link BoundFieldValue} annotation.
25   */
26  @Documented
27  @Retention(RUNTIME)
28  @Target(TYPE)
29  public @interface MetaschemaField {
30    /**
31     * Get the documentary formal name of the field.
32     * <p>
33     * If the value is "##none", then the description will be considered
34     * {@code null}.
35     *
36     * @return a markdown string or {@code "##none"} if no formal name is provided
37     */
38    @NonNull
39    String formalName() default ModelUtil.NO_STRING_VALUE;
40  
41    /**
42     * Get the documentary description of the field.
43     * <p>
44     * If the value is "##none", then the description will be considered
45     * {@code null}.
46     *
47     * @return a markdown string or {@code "##none"} if no description is provided
48     */
49    @NonNull
50    String description() default ModelUtil.NO_STRING_VALUE;
51  
52    /**
53     * Name of the field.
54     *
55     * @return the name
56     */
57    @NonNull
58    String name();
59  
60    /**
61     * The binary name of the assembly.
62     * <p>
63     * The value {@link Integer#MIN_VALUE} indicates that there is no index.
64     *
65     * @return the index value
66     */
67    int index() default Integer.MIN_VALUE;
68  
69    /**
70     * Get the name to use for data instances of this field.
71     * <p>
72     * This overrides the name provided by {@link #name()}.
73     * <p>
74     * The value {@link ModelUtil#NO_STRING_VALUE} indicates that there is no use
75     * name.
76     *
77     *
78     * @return the use name or {@link ModelUtil#NO_STRING_VALUE} if no use name is
79     *         provided
80     */
81    @NonNull
82    String useName() default ModelUtil.NO_STRING_VALUE;
83  
84    /**
85     * The binary use name of the assembly.
86     * <p>
87     * The value {@link Integer#MIN_VALUE} indicates that there is no index.
88     *
89     * @return the index value or {@link Integer#MIN_VALUE} if there is no index
90     *         value
91     */
92    int useIndex() default Integer.MIN_VALUE;
93  
94    /**
95     * Get the metaschema class that "owns" this assembly, which is the concrete
96     * implementation of the metaschema containing the assembly.
97     *
98     * @return the class that extends {@link IBoundModule}
99     */
100   @NonNull
101   Class<? extends IBoundModule> moduleClass();
102 
103   /**
104    * If the data type allows it, determines if the field's value must be wrapped
105    * with an XML element whose name is the specified {@link #name()} and namespace
106    * is derived from the namespace of the instance.
107    *
108    * @return {@code true} if the field must be wrapped, or {@code false} otherwise
109    */
110   boolean inXmlWrapped() default IFieldInstance.DEFAULT_FIELD_IN_XML_WRAPPED;
111 
112   /**
113    * Get any remarks for this field.
114    *
115    * @return a markdown string or {@code "##none"} if no remarks are provided
116    */
117   @NonNull
118   String remarks() default ModelUtil.NO_STRING_VALUE;
119 
120   /**
121    * Get the value constraints defined for this Metaschema field definition.
122    *
123    * @return the value constraints
124    */
125   ValueConstraints valueConstraints() default @ValueConstraints;
126 }