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