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.model.IChoiceGroupInstance;
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 * collection of model instances of varying types.
023 * <p>
024 * For JSON and YAML serializations, the {@link #discriminator()} identifies the
025 * property use to differentiate the type of object values.
026 */
027@Documented
028@Retention(RUNTIME)
029@Target({ FIELD, METHOD })
030public @interface BoundChoiceGroup {
031  /**
032   * The discriminator to use for determining the type of child elements in JSON.
033   *
034   * @return the discriminator property name
035   */
036  @NonNull
037  String discriminator() default IChoiceGroupInstance.DEFAULT_JSON_DISCRIMINATOR_PROPERTY_NAME;
038
039  /**
040   * A non-negative number that indicates the minimum occurrence of the model
041   * instance.
042   *
043   * @return a non-negative number
044   */
045  int minOccurs() default IGroupable.DEFAULT_GROUP_AS_MIN_OCCURS;
046
047  /**
048   * A number that indicates the maximum occurrence of the model instance.
049   *
050   * @return a positive number or {@code -1} to indicate "unbounded"
051   */
052  int maxOccurs() default IGroupable.DEFAULT_GROUP_AS_MAX_OCCURS;
053
054  /**
055   * Used to provide grouping information.
056   * <p>
057   * This annotation is required when the value of {@link #maxOccurs()} is greater
058   * than 1.
059   *
060   * @return the configured {@link GroupAs} or the default value with a
061   *         {@code null} {@link GroupAs#name()}
062   */
063  @NonNull
064  GroupAs groupAs() default @GroupAs(name = ModelUtil.NULL_VALUE);
065
066  /**
067   * The name of a common flag to use as the JSON key that appears on all
068   * associated {@link #assemblies()} and {@link #fields()}.
069   *
070   * @return the configured JSON key flag name or
071   *         {@link ModelUtil#NO_STRING_VALUE} if no JSON key is configured
072   */
073  @NonNull
074  String jsonKey() default ModelUtil.NO_STRING_VALUE;
075
076  /**
077   * The the assemblies that may occur within this choice group.
078   *
079   * @return an array of assembly bindings which may occur within this choice
080   *         group
081   */
082  @NonNull
083  BoundGroupedAssembly[] assemblies() default {};
084
085  /**
086   * The the fields that may occur within this choice group.
087   *
088   * @return an array of field bindings which may occur within this choice group
089   */
090  @NonNull
091  BoundGroupedField[] fields() default {};
092}