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.IDataTypeAdapter;
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.INodeItem;
13
14 import java.util.List;
15 import java.util.regex.Pattern;
16
17 import edu.umd.cs.findbugs.annotations.NonNull;
18
19 /**
20 * Provides a set of callback methods used to process the result of evaluating a
21 * constraint.
22 */
23 public interface IConstraintValidationHandler {
24
25 /**
26 * Handle a cardinality constraint minimum violation.
27 *
28 * @param constraint
29 * the constraint that was evaluated
30 * @param target
31 * the node used as the evaluation focus to determine the items to test
32 * @param testedItems
33 * the items tested
34 * @param dynamicContext
35 * the Metapath dynamic execution context to use for Metapath
36 * evaluation
37 */
38 void handleCardinalityMinimumViolation(
39 @NonNull ICardinalityConstraint constraint,
40 @NonNull INodeItem target,
41 @NonNull ISequence<? extends INodeItem> testedItems,
42 @NonNull DynamicContext dynamicContext);
43
44 /**
45 * Handle a cardinality constraint maximum violation.
46 *
47 * @param constraint
48 * the constraint that was evaluated
49 * @param target
50 * the node used as the evaluation focus to determine the items to test
51 * @param testedItems
52 * the items tested
53 * @param dynamicContext
54 * the Metapath dynamic execution context to use for Metapath
55 * evaluation
56 */
57 void handleCardinalityMaximumViolation(
58 @NonNull ICardinalityConstraint constraint,
59 @NonNull INodeItem target,
60 @NonNull ISequence<? extends INodeItem> testedItems,
61 @NonNull DynamicContext dynamicContext);
62
63 /**
64 * Handle a duplicate index violation.
65 *
66 * @param constraint
67 * the constraint that was evaluated
68 * @param node
69 * the node used as the evaluation focus to determine constraint
70 * targets
71 * @param dynamicContext
72 * the Metapath dynamic execution context to use for Metapath
73 * evaluation
74 */
75 void handleIndexDuplicateViolation(
76 @NonNull IIndexConstraint constraint,
77 @NonNull INodeItem node,
78 @NonNull DynamicContext dynamicContext);
79
80 /**
81 * Handle an index duplicate key violation.
82 * <p>
83 * This happens when two target nodes have the same key.
84 *
85 * @param constraint
86 * the constraint that was evaluated
87 * @param node
88 * the node used as the evaluation focus to determine constraint
89 * targets
90 * @param oldItem
91 * the node that exists in the index for the related key
92 * @param target
93 * the target of evaluation
94 * @param dynamicContext
95 * the Metapath dynamic execution context to use for Metapath
96 * evaluation
97 */
98 void handleIndexDuplicateKeyViolation(
99 @NonNull IIndexConstraint constraint,
100 @NonNull INodeItem node,
101 @NonNull INodeItem oldItem,
102 @NonNull INodeItem target,
103 @NonNull DynamicContext dynamicContext);
104
105 /**
106 * Handle an unique key violation.
107 * <p>
108 * This happens when two target nodes have the same key.
109 *
110 * @param constraint
111 * the constraint that was evaluated
112 * @param node
113 * the node used as the evaluation focus to determine constraint
114 * targets
115 * @param oldItem
116 * the other node with the same key
117 * @param target
118 * the target of evaluation
119 * @param dynamicContext
120 * the Metapath dynamic execution context to use for Metapath
121 * evaluation
122 */
123 void handleUniqueKeyViolation(
124 @NonNull IUniqueConstraint constraint,
125 @NonNull INodeItem node,
126 @NonNull INodeItem oldItem,
127 @NonNull INodeItem target,
128 @NonNull DynamicContext dynamicContext);
129
130 /**
131 * Handle an error that occurred while generating a key.
132 *
133 * @param constraint
134 * the constraint that was evaluated
135 * @param node
136 * the node used as the evaluation focus to determine constraint
137 * targets
138 * @param target
139 * the target of evaluation
140 * @param exception
141 * the resulting Metapath exception
142 * @param dynamicContext
143 * the Metapath dynamic execution context to use for Metapath
144 * evaluation
145 */
146 void handleKeyMatchError(
147 @NonNull IKeyConstraint constraint,
148 @NonNull INodeItem node,
149 @NonNull INodeItem target,
150 @NonNull MetapathException exception,
151 @NonNull DynamicContext dynamicContext);
152
153 /**
154 * Handle a missing index violation.
155 * <p>
156 * This happens when an index-has-key constraint references a missing index.
157 *
158 * @param constraint
159 * the constraint that was evaluated
160 * @param node
161 * the node used as the evaluation focus to determine constraint
162 * targets
163 * @param target
164 * the target of evaluation
165 * @param message
166 * the error message
167 * @param dynamicContext
168 * the Metapath dynamic execution context to use for Metapath
169 * evaluation
170 */
171 void handleMissingIndexViolation(
172 @NonNull IIndexHasKeyConstraint constraint,
173 @NonNull INodeItem node,
174 @NonNull INodeItem target,
175 @NonNull String message,
176 @NonNull DynamicContext dynamicContext);
177
178 /**
179 * Handle an index lookup key miss violation.
180 * <p>
181 * This happens when another node references an expected member of an index that
182 * does not actually exist in the index.
183 *
184 * @param constraint
185 * the constraint that was evaluated
186 * @param node
187 * the node used as the evaluation focus to determine constraint
188 * targets
189 * @param target
190 * the target of evaluation
191 * @param key
192 * the key that was used to lookup the index entry
193 * @param dynamicContext
194 * the Metapath dynamic execution context to use for Metapath
195 * evaluation
196 */
197 void handleIndexMiss(
198 @NonNull IIndexHasKeyConstraint constraint,
199 @NonNull INodeItem node,
200 @NonNull INodeItem target,
201 @NonNull List<String> key,
202 @NonNull DynamicContext dynamicContext);
203
204 /**
205 * Handle a match pattern violation.
206 * <p>
207 * This happens when the target value does not match the specified pattern.
208 *
209 * @param constraint
210 * the constraint that was evaluated
211 * @param node
212 * the node used as the evaluation focus to determine constraint
213 * targets
214 * @param target
215 * the target of evaluation
216 * @param value
217 * the value used for pattern matching
218 * @param pattern
219 * the pattern used for pattern matching
220 * @param dynamicContext
221 * the Metapath dynamic execution context to use for Metapath
222 * evaluation
223 */
224 void handleMatchPatternViolation(
225 @NonNull IMatchesConstraint constraint,
226 @NonNull INodeItem node,
227 @NonNull INodeItem target,
228 @NonNull String value,
229 @NonNull Pattern pattern,
230 @NonNull DynamicContext dynamicContext);
231
232 /**
233 * Handle a match data type violation.
234 * <p>
235 * This happens when the target value does not conform to the specified data
236 * type.
237 *
238 * @param constraint
239 * the constraint that was evaluated
240 * @param node
241 * the node used as the evaluation focus to determine constraint
242 * targets
243 * @param target
244 * the target of evaluation
245 * @param value
246 * the value used for data type matching
247 * @param adapter
248 * the data type used for data type matching
249 * @param cause
250 * the data type exception related to this violation
251 * @param dynamicContext
252 * the Metapath dynamic execution context to use for Metapath
253 * evaluation
254 */
255 void handleMatchDatatypeViolation(
256 @NonNull IMatchesConstraint constraint,
257 @NonNull INodeItem node,
258 @NonNull INodeItem target,
259 @NonNull String value,
260 @NonNull IDataTypeAdapter<?> adapter,
261 @NonNull IllegalArgumentException cause,
262 @NonNull DynamicContext dynamicContext);
263
264 /**
265 * Handle an expect test violation.
266 * <p>
267 * This happens when the test does not evaluate to true.
268 *
269 * @param constraint
270 * the constraint that was evaluated
271 * @param node
272 * the node used as the evaluation focus to determine constraint
273 * targets
274 * @param target
275 * the target of evaluation
276 * @param dynamicContext
277 * the Metapath dynamic execution context to use for Metapath
278 * evaluation
279 */
280 void handleExpectViolation(
281 @NonNull IExpectConstraint constraint,
282 @NonNull INodeItem node,
283 @NonNull INodeItem target,
284 @NonNull DynamicContext dynamicContext);
285
286 /**
287 * Handle an allowed values constraint violation.
288 *
289 * @param failedConstraints
290 * the allowed values constraints that did not match.
291 * @param target
292 * the target of evaluation
293 * @param dynamicContext
294 * the Metapath dynamic execution context to use for Metapath
295 * evaluation
296 */
297 void handleAllowedValuesViolation(
298 @NonNull List<IAllowedValuesConstraint> failedConstraints,
299 @NonNull INodeItem target,
300 @NonNull DynamicContext dynamicContext);
301
302 /**
303 * Handle a constraint that has passed validation.
304 *
305 * @param constraint
306 * the constraint that was evaluated
307 * @param node
308 * the node used as the evaluation focus to determine constraint
309 * targets
310 * @param target
311 * the target of evaluation
312 * @param dynamicContext
313 * the Metapath dynamic execution context to use for Metapath
314 * evaluation
315 */
316 void handlePass(
317 @NonNull IConstraint constraint,
318 @NonNull INodeItem node,
319 @NonNull INodeItem target,
320 @NonNull DynamicContext dynamicContext);
321
322 /**
323 * Handle a constraint that whose evaluation resulted in an unexpected error
324 * during validation.
325 *
326 * @param constraint
327 * the constraint that was evaluated
328 * @param node
329 * the node used as the evaluation focus to determine constraint
330 * targets
331 * @param message
332 * the error message
333 * @param exception
334 * the causing exception
335 * @param dynamicContext
336 * the Metapath dynamic execution context to use for Metapath
337 * evaluation
338 */
339 void handleError(
340 @NonNull IConstraint constraint,
341 @NonNull INodeItem node,
342 @NonNull String message,
343 @NonNull Throwable exception,
344 @NonNull DynamicContext dynamicContext);
345 }