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