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