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