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 * An optional set of associated properties.
114 *
115 * @return the properties or an empty array with no properties
116 */
117 Property[] properties() default {};
118
119 /**
120 * Get any remarks for this field.
121 *
122 * @return a markdown string or {@code "##none"} if no remarks are provided
123 */
124 @NonNull
125 String remarks() default ModelUtil.NO_STRING_VALUE;
126
127 /**
128 * Get the value constraints defined for this Metaschema field definition.
129 *
130 * @return the value constraints
131 */
132 ValueConstraints valueConstraints() default @ValueConstraints;
133 }