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.FIELD;
009import static java.lang.annotation.ElementType.METHOD;
010import static java.lang.annotation.RetentionPolicy.RUNTIME;
011
012import java.lang.annotation.Documented;
013import java.lang.annotation.Retention;
014import java.lang.annotation.Target;
015
016import dev.metaschema.core.datatype.IDataTypeAdapter;
017import edu.umd.cs.findbugs.annotations.NonNull;
018
019/**
020 * Identifies that the annotation target is a bound property that represents a
021 * Module flag.
022 */
023@Documented
024@Retention(RUNTIME)
025@Target({ FIELD, METHOD })
026public @interface BoundFlag {
027  /**
028   * Get the documentary formal name of the flag.
029   * <p>
030   * If the value is "##none", then the description will be considered
031   * {@code null}.
032   *
033   * @return a markdown string or {@code "##none"} if no formal name is provided
034   */
035  @NonNull
036  String formalName() default ModelUtil.NO_STRING_VALUE;
037
038  /**
039   * Get the documentary description of the flag.
040   * <p>
041   * If the value is "##none", then the description will be considered
042   * {@code null}.
043   *
044   * @return a markdown string or {@code "##none"} if no description is provided
045   */
046  @NonNull
047  String description() default ModelUtil.NO_STRING_VALUE;
048
049  /**
050   * The model name to use for singleton values. This name will be used for
051   * associated XML attributes and JSON properties.
052   * <p>
053   * If the value is "##none", then element name is derived from the JavaBean
054   * property name.
055   *
056   * @return the name
057   */
058  @NonNull
059  String name() default ModelUtil.NO_STRING_VALUE;
060
061  /**
062   * The binary use name of the flag.
063   * <p>
064   * The value {@link Integer#MIN_VALUE} indicates that there is no use name.
065   *
066   * @return the index value
067   */
068  int useIndex() default Integer.MIN_VALUE;
069
070  /**
071   * The default value of the flag represented as a string.
072   * <p>
073   * The value {@link ModelUtil#NULL_VALUE} is used to indicate if no default
074   * value is provided.
075   *
076   * @return the default value
077   */
078  @NonNull
079  String defaultValue() default ModelUtil.NULL_VALUE;
080
081  /**
082   * Specifies if the XML Schema attribute is optional or required. If true, then
083   * the JavaBean property is mapped to a XML Schema attribute that is required.
084   * Otherwise it is mapped to a XML Schema attribute that is optional.
085   *
086   * @return {@code true} if the flag must occur, or {@code false} otherwise
087   */
088  boolean required() default false;
089
090  /**
091   * The Module data type adapter for the field's value.
092   *
093   * @return the data type adapter
094   */
095  @NonNull
096  Class<? extends IDataTypeAdapter<?>> typeAdapter() default NullJavaTypeAdapter.class;
097
098  /**
099   * An optional set of associated properties.
100   *
101   * @return the properties or an empty array with no properties
102   */
103  Property[] properties() default {};
104
105  /**
106   * Get any remarks for this flag.
107   *
108   * @return a markdown string or {@code "##none"} if no remarks are provided
109   */
110  @NonNull
111  String remarks() default ModelUtil.NO_STRING_VALUE;
112
113  /**
114   * Get the value constraints defined for this Metaschema flag inline definition.
115   *
116   * @return the value constraints
117   */
118  ValueConstraints valueConstraints() default @ValueConstraints;
119}