1 /**
2 * Copyright (C) 2014-2015 Philip Helger (www.helger.com)
3 * philip[at]helger[dot]com
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package com.helger.schematron.pure.validation;
18
19 import javax.annotation.Nonnull;
20 import javax.annotation.Nullable;
21
22 import org.w3c.dom.Node;
23
24 import com.helger.commons.state.EContinue;
25 import com.helger.schematron.pure.model.PSAssertReport;
26 import com.helger.schematron.pure.model.PSPattern;
27 import com.helger.schematron.pure.model.PSPhase;
28 import com.helger.schematron.pure.model.PSRule;
29 import com.helger.schematron.pure.model.PSSchema;
30
31 /**
32 * Base interface for a Schematron validation callback handler. It is only
33 * invoked when validating an XML against a Schematron file.
34 *
35 * @see com.helger.schematron.pure.bound.IPSBoundSchema#validate(Node,
36 * IPSValidationHandler)
37 * @author Philip Helger
38 */
39 public interface IPSValidationHandler
40 {
41 /**
42 * This is the first method called.
43 *
44 * @param aSchema
45 * The Schematron to be validated. Never <code>null</code>.
46 * @param aActivePhase
47 * The selected phase, if any special phase was selected. May be
48 * <code>null</code>.
49 * @see #onEnd(PSSchema, PSPhase)
50 * @throws SchematronValidationException
51 * In case of validation errors
52 */
53 void onStart (@Nonnull PSSchema aSchema, @Nullable PSPhase aActivePhase) throws SchematronValidationException;
54
55 /**
56 * This method is called for every pattern inside the schema.
57 *
58 * @param aPattern
59 * The current pattern. Never <code>null</code>.
60 * @throws SchematronValidationException
61 * In case of validation errors
62 */
63 void onPattern (@Nonnull PSPattern aPattern) throws SchematronValidationException;
64
65 /**
66 * This method is called for every rule inside the current pattern.
67 *
68 * @param aRule
69 * The current rule. Never <code>null</code>.
70 * @param sContext
71 * The real context to be used in validation. May differ from the
72 * result of {@link PSRule#getContext()} because of replaced variables
73 * from <let> elements.
74 * @throws SchematronValidationException
75 * In case of validation errors
76 */
77 void onRule (@Nonnull PSRule aRule, @Nonnull String sContext) throws SchematronValidationException;
78
79 /**
80 * This method is called for every failed assert.
81 *
82 * @param aAssertReport
83 * The current assert element. Never <code>null</code>.
84 * @param sTestExpression
85 * The source XPath expression that was evaluated for this node. It may
86 * be different from the test expression contained in the passed
87 * assert/report element because of replaced <let> elements.
88 * Never <code>null</code>.
89 * @param aRuleMatchingNode
90 * The XML node of the document to be validated.
91 * @param nNodeIndex
92 * The index of the matched node, relative to the current rule.
93 * @param aContext
94 * A context object - implementation dependent. For the default query
95 * binding this is e.g. an
96 * {@link com.helger.schematron.pure.bound.xpath.PSXPathBoundAssertReport}
97 * object.
98 * @return {@link EContinue#BREAK} to stop validating immediately.
99 * @throws SchematronValidationException
100 * In case of validation errors
101 */
102 @Nonnull
103 EContinue onFailedAssert (@Nonnull PSAssertReport aAssertReport,
104 @Nonnull String sTestExpression,
105 @Nonnull Node aRuleMatchingNode,
106 int nNodeIndex,
107 @Nullable Object aContext) throws SchematronValidationException;
108
109 /**
110 * This method is called for every failed assert.
111 *
112 * @param aAssertReport
113 * The current assert element. Never <code>null</code>.
114 * @param sTestExpression
115 * The source XPath expression that was evaluated for this node. It may
116 * be different from the test expression contained in the passed
117 * assert/report element because of replaced <let> elements.
118 * Never <code>null</code>.
119 * @param aRuleMatchingNode
120 * The XML node of the document to be validated.
121 * @param nNodeIndex
122 * The index of the matched node, relative to the current rule.
123 * @param aContext
124 * A context object - implementation dependent. For the default query
125 * binding this is e.g. an
126 * {@link com.helger.schematron.pure.bound.xpath.PSXPathBoundAssertReport}
127 * object.
128 * @return {@link EContinue#BREAK} to stop validating immediately.
129 * @throws SchematronValidationException
130 * In case of validation errors
131 */
132 @Nonnull
133 EContinue onSuccessfulReport (@Nonnull PSAssertReport aAssertReport,
134 @Nonnull String sTestExpression,
135 @Nonnull Node aRuleMatchingNode,
136 int nNodeIndex,
137 @Nullable Object aContext) throws SchematronValidationException;
138
139 /**
140 * This is the last method called. It indicates that the validation for the
141 * current scheme ended.
142 *
143 * @param aSchema
144 * The Schematron that was be validated. Never <code>null</code>.
145 * @param aActivePhase
146 * The selected phase, if any special phase was selected. May be
147 * <code>null</code>.
148 * @see #onStart(PSSchema, PSPhase)
149 * @throws SchematronValidationException
150 * In case of validation errors
151 */
152 void onEnd (@Nonnull PSSchema aSchema, @Nullable PSPhase aActivePhase) throws SchematronValidationException;
153 }