001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package gov.nist.secauto.metaschema.databind.model.annotations;
007
008import static java.lang.annotation.ElementType.FIELD;
009import static java.lang.annotation.ElementType.METHOD;
010import static java.lang.annotation.RetentionPolicy.RUNTIME;
011
012import gov.nist.secauto.metaschema.core.datatype.IDataTypeAdapter;
013import gov.nist.secauto.metaschema.core.model.IFieldInstance;
014import gov.nist.secauto.metaschema.core.model.IGroupable;
015
016import java.lang.annotation.Documented;
017import java.lang.annotation.Retention;
018import java.lang.annotation.Target;
019
020import edu.umd.cs.findbugs.annotations.NonNull;
021
022/**
023 * Identifies that the annotation target is a bound property that references a
024 * Module field.
025 * <p>
026 * For XML serialization, the {@link #useName()} identifies the name of the
027 * element to use for this element.
028 * <p>
029 * For JSON and YAML serializations, the {@link #useName()} identifies the
030 * property/item name to use.
031 * <p>
032 * The field must be either:
033 * <ol>
034 * <li>A Module data type or a collection whose item value is Module data type,
035 * with a non-null {@link #typeAdapter()}.
036 * <li>A type or a collection whose item value is a type based on a class with a
037 * {@link MetaschemaField} annotation, with a property annotated with
038 * {@link BoundFieldValue}.</li>
039 * </ol>
040 */
041@Documented
042@Retention(RUNTIME)
043@Target({ FIELD, METHOD })
044public @interface BoundField {
045  /**
046   * Get the documentary formal name of the field.
047   * <p>
048   * If the value is "##none", then the description will be considered
049   * {@code null}.
050   *
051   * @return a markdown string or {@code "##none"} if no formal name is provided
052   */
053  @NonNull
054  String formalName() default ModelUtil.NO_STRING_VALUE;
055
056  /**
057   * Get the documentary description of the field.
058   * <p>
059   * If the value is "##none", then the description will be considered
060   * {@code null}.
061   *
062   * @return a markdown string or {@code "##none"} if no description is provided
063   */
064  @NonNull
065  String description() default ModelUtil.NO_STRING_VALUE;
066
067  /**
068   * The model name to use for JSON/YAML singleton values and associated XML
069   * elements.
070   * <p>
071   * If the value is "##none", then the use name will be provided by the
072   * definition or by the field name if the item value class is missing the
073   * {@link MetaschemaField} annotation.
074   *
075   * @return the name
076   */
077  @NonNull
078  String useName() default ModelUtil.NO_STRING_VALUE;
079
080  /**
081   * The binary use name of the field.
082   * <p>
083   * The value {@link Integer#MIN_VALUE} indicates that there is no use name.
084   *
085   * @return the index value
086   */
087  int useIndex() default Integer.MIN_VALUE;
088
089  /**
090   * The Metaschema data type adapter for the field's value.
091   *
092   * @return the data type adapter
093   */
094  @NonNull
095  Class<? extends IDataTypeAdapter<?>> typeAdapter() default NullJavaTypeAdapter.class;
096
097  /**
098   * The default value of the field represented as a string.
099   * <p>
100   * The value {@link ModelUtil#NULL_VALUE} is used to indicate if no default
101   * value is provided.
102   *
103   * @return the default value
104   */
105  @NonNull
106  String defaultValue() default ModelUtil.NULL_VALUE;
107
108  /**
109   * If the data type allows it, determines if the field's value must be wrapped
110   * with an XML element.
111   *
112   * @return {@code true} if the field must be wrapped, or {@code false} otherwise
113   */
114  boolean inXmlWrapped() default IFieldInstance.DEFAULT_FIELD_IN_XML_WRAPPED;
115
116  /**
117   * A non-negative number that indicates the minimum occurrence of the model
118   * instance.
119   *
120   * @return a non-negative number
121   */
122  int minOccurs() default IGroupable.DEFAULT_GROUP_AS_MIN_OCCURS;
123
124  /**
125   * A number that indicates the maximum occurrence of the model instance.
126   *
127   * @return a positive number or {@code -1} to indicate "unbounded"
128   */
129  int maxOccurs() default IGroupable.DEFAULT_GROUP_AS_MAX_OCCURS;
130
131  /**
132   * An optional set of associated properties.
133   *
134   * @return the properties or an empty array with no properties
135   */
136  Property[] properties() default {};
137
138  /**
139   * Get any remarks for this field.
140   *
141   * @return a markdown string or {@code "##none"} if no remarks are provided
142   */
143  @NonNull
144  String remarks() default ModelUtil.NO_STRING_VALUE;
145
146  /**
147   * Used to provide grouping information.
148   * <p>
149   * This annotation is required when the value of {@link #maxOccurs()} is greater
150   * than 1.
151   *
152   * @return the configured {@link GroupAs} or the default value with a
153   *         {@code null} {@link GroupAs#name()}
154   */
155  @NonNull
156  GroupAs groupAs() default @GroupAs(name = ModelUtil.NULL_VALUE);
157
158  /**
159   * Get the value constraints defined for this Metaschema field inline
160   * definition.
161   *
162   * @return the value constraints
163   */
164  ValueConstraints valueConstraints() default @ValueConstraints;
165}