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.datatype.IDataTypeAdapter; 013import gov.nist.secauto.metaschema.core.model.IBoundObject; 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 field. 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 * <p> 031 * The field must be either: 032 * <ol> 033 * <li>A Module data type or a collection whose item value is Module data type, 034 * with a non-null {@link #typeAdapter()}. 035 * <li>A type or a collection whose item value is a type based on a class with a 036 * {@link MetaschemaField} annotation, with a property annotated with 037 * {@link BoundFieldValue}.</li> 038 * </ol> 039 */ 040@Documented 041@Retention(RUNTIME) 042@Target({ FIELD, METHOD }) 043public @interface BoundGroupedField { 044 /** 045 * Get the documentary formal name of the field. 046 * <p> 047 * If the value is "##none", then the description will be considered 048 * {@code null}. 049 * 050 * @return a markdown string or {@code "##none"} if no formal name is provided 051 */ 052 @NonNull 053 String formalName() default ModelUtil.NO_STRING_VALUE; 054 055 /** 056 * Get the documentary description of the field. 057 * <p> 058 * If the value is "##none", then the description will be considered 059 * {@code null}. 060 * 061 * @return a markdown string or {@code "##none"} if no description is provided 062 */ 063 @NonNull 064 String description() default ModelUtil.NO_STRING_VALUE; 065 066 /** 067 * The model name to use for JSON/YAML singleton values and associated XML 068 * elements. 069 * <p> 070 * If the value is "##none", then the use name will be provided by the 071 * definition or by the field name if the item value class is missing the 072 * {@link MetaschemaField} annotation. 073 * 074 * @return the name 075 */ 076 @NonNull 077 String useName() default ModelUtil.NO_STRING_VALUE; 078 079 /** 080 * The binary use name of the field. 081 * <p> 082 * The value {@link Integer#MIN_VALUE} indicates that there is no use name. 083 * 084 * @return the index value 085 */ 086 int useIndex() default Integer.MIN_VALUE; 087 088 /** 089 * The Metaschema data type adapter for the field's value. 090 * 091 * @return the data type adapter 092 */ 093 @NonNull 094 Class<? extends IDataTypeAdapter<?>> typeAdapter() default NullJavaTypeAdapter.class; 095 096 /** 097 * Get any remarks for this field. 098 * 099 * @return a markdown string or {@code "##none"} if no remarks are provided 100 */ 101 @NonNull 102 String remarks() default ModelUtil.NO_STRING_VALUE; 103 104 /** 105 * Get the value constraints defined for this Metaschema field inline 106 * definition. 107 * 108 * @return the value constraints 109 */ 110 ValueConstraints valueConstraints() default @ValueConstraints; 111 112 /** 113 * Get any remarks for this field. 114 * 115 * @return the discriminator string or {@code "##none"} if no discriminator is 116 * provided 117 */ 118 @NonNull 119 String discriminatorValue() default ModelUtil.NO_STRING_VALUE; 120 121 /** 122 * The bound class associated with this assembly. 123 * <p> 124 * This is optional when used on a field or method, and required when used with 125 * an annotation type value, i.e. {@link BoundChoiceGroup}. 126 * 127 * @return the bound class 128 */ 129 @NonNull 130 Class<? extends IBoundObject> binding(); 131}