1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.metaschema.core.model.constraint;
7   
8   import gov.nist.secauto.metaschema.core.datatype.markup.MarkupMultiline;
9   import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
10  import gov.nist.secauto.metaschema.core.metapath.ISequence;
11  import gov.nist.secauto.metaschema.core.metapath.MetapathException;
12  import gov.nist.secauto.metaschema.core.metapath.item.node.IDefinitionNodeItem;
13  import gov.nist.secauto.metaschema.core.model.IAttributable;
14  import gov.nist.secauto.metaschema.core.model.IDescribable;
15  import gov.nist.secauto.metaschema.core.model.ISource;
16  import gov.nist.secauto.metaschema.core.util.ObjectUtils;
17  
18  import edu.umd.cs.findbugs.annotations.NonNull;
19  import edu.umd.cs.findbugs.annotations.Nullable;
20  
21  /**
22   * Represents a rule constraining the model of a Metaschema assembly, field or
23   * flag. Provides a common interface for all constraint definitions.
24   */
25  public interface IConstraint extends IAttributable, IDescribable {
26    /**
27     * The degree to which a constraint violation is significant.
28     * <p>
29     * These values are ordered from least significant to most significant.
30     */
31    enum Level {
32      /**
33       * No violation.
34       */
35      NONE,
36      /**
37       * A violation of the constraint represents a point of interest.
38       */
39      INFORMATIONAL,
40      /**
41       * A violation of the constraint represents a fault in the content that may
42       * warrant review by a developer when performing model or tool development.
43       */
44      DEBUG,
45      /**
46       * A violation of the constraint represents a potential issue with the content.
47       */
48      WARNING,
49      /**
50       * A violation of the constraint represents a fault in the content. This may
51       * include issues around compatibility, integrity, consistency, etc.
52       */
53      ERROR,
54      /**
55       * A violation of the constraint represents a serious fault in the content that
56       * will prevent typical use of the content.
57       */
58      CRITICAL;
59    }
60  
61    /**
62     * The default level to use if no level is provided.
63     */
64    @NonNull
65    Level DEFAULT_LEVEL = Level.ERROR;
66  
67    /**
68     * The default target Metapath expression to use if no target is provided.
69     */
70    @NonNull
71    String DEFAULT_TARGET_METAPATH = ".";
72  
73    /**
74     * Get a string that identifies the provided constraint using the most specific
75     * information available.
76     *
77     * @param constraint
78     *          the constraint to identify
79     * @return the constraint identification statement
80     */
81    @NonNull
82    static String getConstraintIdentity(@NonNull IConstraint constraint) {
83      String identity;
84      if (constraint.getId() != null) {
85        identity = String.format("with id '%s'", constraint.getId());
86      } else if (constraint.getFormalName() != null) {
87        identity = String.format("with the formal name '%s'", constraint.getFormalName());
88      } else {
89        identity = String.format("targeting '%s'", constraint.getTarget());
90      }
91      return ObjectUtils.notNull(identity);
92    }
93  
94    /**
95     * Retrieve the unique identifier for the constraint.
96     *
97     * @return the identifier or {@code null} if no identifier is defined
98     */
99    @Nullable
100   String getId();
101 
102   /**
103    * Get information about the source of the constraint.
104    *
105    * @return the source information
106    */
107   @NonNull
108   ISource getSource();
109 
110   /**
111    * The significance of a violation of this constraint.
112    *
113    * @return the level
114    */
115   @NonNull
116   Level getLevel();
117 
118   /**
119    * Retrieve the Metapath expression to use to query the targets of the
120    * constraint.
121    *
122    * @return a Metapath expression
123    */
124   @NonNull
125   String getTarget();
126 
127   /**
128    * Based on the provided {@code contextNodeItem}, find all nodes matching the
129    * target expression.
130    *
131    * @param item
132    *          the node item to evaluate the target expression against
133    * @param dynamicContext
134    *          the Metapath evaluation context to use
135    * @return the matching nodes as a sequence
136    * @throws MetapathException
137    *           if an error occurred during evaluation
138    * @see #getTarget()
139    */
140   @NonNull
141   ISequence<? extends IDefinitionNodeItem<?, ?>> matchTargets(
142       @NonNull IDefinitionNodeItem<?, ?> item,
143       @NonNull DynamicContext dynamicContext);
144 
145   /**
146    * Retrieve the remarks associated with the constraint.
147    *
148    * @return the remarks or {@code null} if no remarks are defined
149    */
150   MarkupMultiline getRemarks();
151 
152   /**
153    * Used for double dispatch supporting the visitor pattern provided by
154    * implementations of {@link IConstraintVisitor}.
155    *
156    * @param <T>
157    *          the Java type of a state object passed to the visitor
158    * @param <R>
159    *          the Java type of the result returned by the visitor methods
160    * @param visitor
161    *          the visitor implementation
162    * @param state
163    *          the state object passed to the visitor
164    * @return the visitation result
165    * @see IConstraintVisitor
166    */
167   <T, R> R accept(@NonNull IConstraintVisitor<T, R> visitor, T state);
168 }