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