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