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 }