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.RetentionPolicy.RUNTIME;
010
011import gov.nist.secauto.metaschema.core.datatype.IDataTypeAdapter;
012import gov.nist.secauto.metaschema.core.model.constraint.IConstraint;
013import gov.nist.secauto.metaschema.core.model.constraint.IConstraint.Level;
014
015import java.lang.annotation.Documented;
016import java.lang.annotation.Retention;
017import java.lang.annotation.Target;
018import java.util.regex.Pattern;
019
020import edu.umd.cs.findbugs.annotations.NonNull;
021
022/**
023 * This annotation defines a rule that requires matching patterns and/or data
024 * types among the target contents of the assembly represented by the containing
025 * {@link MetaschemaAssembly} annotation.
026 */
027@Documented
028@Retention(RUNTIME)
029@Target(ANNOTATION_TYPE)
030public @interface Matches {
031  /**
032   * An optional identifier for the constraint, which must be unique to only this
033   * constraint.
034   *
035   * @return the identifier if provided or an empty string otherwise
036   */
037  @SuppressWarnings("PMD.ShortMethodName")
038  @NonNull
039  String id() default "";
040
041  /**
042   * An optional formal name for the constraint.
043   *
044   * @return the formal name if provided or an empty string otherwise
045   */
046  @NonNull
047  String formalName() default "";
048
049  /**
050   * An optional description of the constraint.
051   *
052   * @return the description if provided or an empty string otherwise
053   */
054  @NonNull
055  String description() default "";
056
057  /**
058   * The significance of a violation of this constraint.
059   *
060   * @return the level
061   */
062  @NonNull
063  Level level() default IConstraint.Level.ERROR;
064
065  /**
066   * An optional Metapath that points to the target flag or field value that the
067   * constraint applies to. If omitted the target will be ".", which means the
068   * target is the value of the {@link BoundFlag}, {@link BoundField} or
069   * {@link BoundFieldValue} annotation the constraint appears on. In the prior
070   * case, this annotation may only appear on a {@link BoundField} if the field
071   * has no flags, which results in a {@link BoundField} annotation on a field
072   * instance with a scalar, data type value.
073   *
074   * @return the target metapath
075   */
076  @NonNull
077  String target() default ".";
078
079  /**
080   * An optional set of properties associated with these allowed values.
081   *
082   * @return the properties or an empty array with no properties
083   */
084  Property[] properties() default {};
085
086  /**
087   * Retrieve an optional pattern that the associated value must match. This must
088   * be a pattern that can compile using {@link Pattern#compile(String)}.
089   *
090   * @return a pattern string or an empty string if no pattern is provided
091   */
092  @NonNull
093  String pattern() default "";
094
095  /**
096   * The Module data type adapter for the data type that the associated value must
097   * conform to.
098   *
099   * @return the data type adapter or a {@link NullJavaTypeAdapter} if none is
100   *         provided
101   */
102  @NonNull
103  Class<? extends IDataTypeAdapter<?>> typeAdapter() default NullJavaTypeAdapter.class;
104
105  /**
106   * The message to emit when the constraint is violated.
107   *
108   * @return the message or an empty string otherwise
109   */
110  @NonNull
111  String message() default "";
112
113  /**
114   * Any remarks about the constraint, encoded as an escaped Markdown string.
115   *
116   * @return an encoded markdown string or an empty string if no remarks are
117   *         provided
118   */
119  @NonNull
120  String remarks() default "";
121}