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