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