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.IBoundObject;
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 BoundGroupedAssembly {
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   * An optional set of associated properties.
079   *
080   * @return the properties or an empty array with no properties
081   */
082  Property[] properties() default {};
083
084  /**
085   * Get any remarks for this field.
086   *
087   * @return a markdown string or {@code "##none"} if no remarks are provided
088   */
089  @NonNull
090  String remarks() default ModelUtil.NO_STRING_VALUE;
091
092  /**
093   * Get any remarks for this field.
094   *
095   * @return the discriminator string or {@code "##none"} if no discriminator is
096   *         provided
097   */
098  @NonNull
099  String discriminatorValue() default ModelUtil.NO_STRING_VALUE;
100
101  /**
102   * The bound class associated with this assembly.
103   * <p>
104   * This is optional when used on a field or method, and required when used with
105   * an annotation type value, i.e. {@link BoundChoiceGroup}.
106   *
107   * @return the bound class
108   */
109  @NonNull
110  Class<? extends IBoundObject> binding();
111}