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.ANNOTATION_TYPE;
009import static java.lang.annotation.ElementType.FIELD;
010import static java.lang.annotation.ElementType.METHOD;
011import static java.lang.annotation.RetentionPolicy.RUNTIME;
012
013import java.lang.annotation.Documented;
014import java.lang.annotation.Retention;
015import java.lang.annotation.Target;
016
017import dev.metaschema.core.model.IGroupable;
018import edu.umd.cs.findbugs.annotations.NonNull;
019
020/**
021 * Identifies that the annotation target is a bound property that references a
022 * Module assembly.
023 * <p>
024 * For XML serialization, the {@link #useName()} identifies the name of the
025 * element to use for this element.
026 * <p>
027 * For JSON and YAML serializations, the {@link #useName()} identifies the
028 * property/item name to use.
029 */
030@Documented
031@Retention(RUNTIME)
032@Target({ FIELD, METHOD, ANNOTATION_TYPE })
033public @interface BoundAssembly {
034  /**
035   * Get the documentary formal name of the assembly.
036   * <p>
037   * If the value is "##none", then the description will be considered
038   * {@code null}.
039   *
040   * @return a markdown string or {@code "##none"} if no formal name is provided
041   */
042  @NonNull
043  String formalName() default ModelUtil.NO_STRING_VALUE;
044
045  /**
046   * Get the documentary description of the assembly.
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 description is provided
052   */
053  @NonNull
054  String description() default ModelUtil.NO_STRING_VALUE;
055
056  /**
057   * The model name to use for singleton values. This name will be used for
058   * associated XML elements.
059   * <p>
060   * If the value is "##none", then element name is derived from the JavaBean
061   * property name.
062   *
063   * @return the name or {@code "##none"} if no use name is provided
064   */
065  @NonNull
066  String useName() default ModelUtil.NO_STRING_VALUE;
067
068  /**
069   * The binary use name of the assembly.
070   * <p>
071   * The value {@link Integer#MIN_VALUE} indicates that there is no use name.
072   *
073   * @return the index value
074   */
075  int useIndex() default Integer.MIN_VALUE;
076
077  /**
078   * A non-negative number that indicates the minimum occurrence of the model
079   * instance.
080   *
081   * @return a non-negative number
082   */
083  int minOccurs() default IGroupable.DEFAULT_GROUP_AS_MIN_OCCURS;
084
085  /**
086   * A number that indicates the maximum occurrence of the model instance.
087   *
088   * @return a positive number or {@code -1} to indicate "unbounded"
089   */
090  int maxOccurs() default IGroupable.DEFAULT_GROUP_AS_MAX_OCCURS;
091
092  /**
093   * An optional set of associated properties.
094   *
095   * @return the properties or an empty array with no properties
096   */
097  Property[] properties() default {};
098
099  /**
100   * Get any remarks for this field.
101   *
102   * @return a markdown string or {@code "##none"} if no remarks are provided
103   */
104  @NonNull
105  String remarks() default ModelUtil.NO_STRING_VALUE;
106
107  /**
108   * Used to provide grouping information.
109   * <p>
110   * This annotation is required when the value of {@link #maxOccurs()} is greater
111   * than 1.
112   *
113   * @return the configured {@link GroupAs} or the default value with a
114   *         {@code null} {@link GroupAs#name()}
115   */
116  @NonNull
117  GroupAs groupAs() default @GroupAs(name = ModelUtil.NULL_VALUE);
118}