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.TYPE;
009import static java.lang.annotation.RetentionPolicy.RUNTIME;
010
011import gov.nist.secauto.metaschema.core.model.IFieldInstance;
012import gov.nist.secauto.metaschema.databind.model.IBoundModule;
013
014import java.lang.annotation.Documented;
015import java.lang.annotation.Retention;
016import java.lang.annotation.Target;
017
018import edu.umd.cs.findbugs.annotations.NonNull;
019
020/**
021 * This annotation indicates that the target class represents a Module field.
022 * <p>
023 * Classes with this annotation must have a field with the
024 * {@link BoundFieldValue} annotation.
025 */
026@Documented
027@Retention(RUNTIME)
028@Target(TYPE)
029public @interface MetaschemaField {
030  /**
031   * Get the documentary formal name of the field.
032   * <p>
033   * If the value is "##none", then the description will be considered
034   * {@code null}.
035   *
036   * @return a markdown string or {@code "##none"} if no formal name is provided
037   */
038  @NonNull
039  String formalName() default ModelUtil.NO_STRING_VALUE;
040
041  /**
042   * Get the documentary description of the field.
043   * <p>
044   * If the value is "##none", then the description will be considered
045   * {@code null}.
046   *
047   * @return a markdown string or {@code "##none"} if no description is provided
048   */
049  @NonNull
050  String description() default ModelUtil.NO_STRING_VALUE;
051
052  /**
053   * Name of the field.
054   *
055   * @return the name
056   */
057  @NonNull
058  String name();
059
060  /**
061   * The binary name of the assembly.
062   * <p>
063   * The value {@link Integer#MIN_VALUE} indicates that there is no index.
064   *
065   * @return the index value
066   */
067  int index() default Integer.MIN_VALUE;
068
069  /**
070   * Get the name to use for data instances of this field.
071   * <p>
072   * This overrides the name provided by {@link #name()}.
073   * <p>
074   * The value {@link ModelUtil#NO_STRING_VALUE} indicates that there is no use
075   * name.
076   *
077   *
078   * @return the use name or {@link ModelUtil#NO_STRING_VALUE} if no use name is
079   *         provided
080   */
081  @NonNull
082  String useName() default ModelUtil.NO_STRING_VALUE;
083
084  /**
085   * The binary use name of the assembly.
086   * <p>
087   * The value {@link Integer#MIN_VALUE} indicates that there is no index.
088   *
089   * @return the index value or {@link Integer#MIN_VALUE} if there is no index
090   *         value
091   */
092  int useIndex() default Integer.MIN_VALUE;
093
094  /**
095   * Get the metaschema class that "owns" this assembly, which is the concrete
096   * implementation of the metaschema containing the assembly.
097   *
098   * @return the class that extends {@link IBoundModule}
099   */
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}