1 /**
2 * Copyright (C) 2014-2018 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;
18
19 import javax.annotation.Nonnull;
20 import javax.annotation.Nullable;
21 import javax.xml.transform.Source;
22
23 import org.oclc.purl.dsdl.svrl.SchematronOutputType;
24 import org.w3c.dom.Document;
25 import org.w3c.dom.Node;
26 import org.xml.sax.EntityResolver;
27
28 import com.helger.commons.id.IHasID;
29 import com.helger.commons.io.IHasInputStream;
30 import com.helger.commons.io.resource.IReadableResource;
31 import com.helger.commons.state.EValidity;
32
33 /**
34 * Base interface for a Schematron resource. The implementation can e.g. be a
35 * SCH file that needs preprocessing to XSLT or an already precompiled XSLT
36 * file.
37 *
38 * @author Philip Helger
39 */
40 public interface ISchematronResource extends IHasID <String>
41 {
42 /**
43 * @return The non-<code>null</code> resource from which to read the
44 * Schematron rules.
45 */
46 @Nonnull
47 IReadableResource getResource ();
48
49 /**
50 * @return <code>true</code> to use caching, if applicable.
51 * @since 5.0.2 in this interface
52 */
53 boolean isUseCache ();
54
55 /**
56 * Enable or disable caching.
57 *
58 * @param bUseCache
59 * <code>true</code> to use the cache, <code>false</code> to not use
60 * it.
61 * @since 5.0.2 in this interface
62 */
63 void setUseCache (boolean bUseCache);
64
65 /**
66 * @return The XML entity resolver to be used to read the Schematron or XML to
67 * be validated. May be <code>null</code>.
68 * @since 4.1.1 in implementation
69 * @since 5.0.2 in this interface
70 */
71 @Nullable
72 EntityResolver getEntityResolver ();
73
74 /**
75 * @return <code>true</code> if this Schematron can be used to validate XML
76 * instances. If not, the Schematron is invalid and the log files must
77 * be investigated.
78 */
79 boolean isValidSchematron ();
80
81 /**
82 * A method to check if the passed XML DOM node matches the Schematron rules
83 * or not. This is the quick check method, as it breaks upon the first failed
84 * assertion or the first successful report, if the implementation supports it
85 * (as e.g. the native pure Schematron version).
86 *
87 * @param aXMLResource
88 * The source XML to read and validate against the Schematron. May not
89 * be <code>null</code>.
90 * @return {@link EValidity#VALID} if the document is valid,
91 * {@link EValidity#INVALID} if it is invalid.
92 * @throws Exception
93 * in case of a sever error validating the schema
94 */
95 @Nonnull
96 EValidity getSchematronValidity (@Nonnull IHasInputStream aXMLResource) throws Exception;
97
98 /**
99 * A method to check if the passed DOM node matches the Schematron rules or
100 * not. This is the quick check method, as it breaks upon the first failed
101 * assertion or the first successful report, if the implementation supports it
102 * (as e.g. the native pure Schematron version).
103 *
104 * @param aXMLNode
105 * The source DOM node to validate against the Schematron. May not be
106 * <code>null</code>.
107 * @param sBaseURI
108 * The Base URI of the XML document to be validated. May be
109 * <code>null</code>.
110 * @return {@link EValidity#VALID} if the document is valid,
111 * {@link EValidity#INVALID} if it is invalid.
112 * @throws Exception
113 * in case of a sever error validating the schema
114 */
115 @Nonnull
116 EValidity getSchematronValidity (@Nonnull Node aXMLNode, @Nullable String sBaseURI) throws Exception;
117
118 /**
119 * A method to check if the passed XML DOM node matches the Schematron rules
120 * or not. This is the quick check method, as it breaks upon the first failed
121 * assertion or the first successful report, if the implementation supports it
122 * (as e.g. the native pure Schematron version).
123 *
124 * @param aXMLSource
125 * The source XML to be validated against the Schematron. May not be
126 * <code>null</code>.
127 * @return {@link EValidity#VALID} if the document is valid,
128 * {@link EValidity#INVALID} if it is invalid.
129 * @throws Exception
130 * in case of a sever error validating the schema
131 */
132 @Nonnull
133 EValidity getSchematronValidity (@Nonnull Source aXMLSource) throws Exception;
134
135 /**
136 * Apply the Schematron validation on the passed XML resource and return an
137 * SVRL XML DOM Document.
138 *
139 * @param aXMLResource
140 * The XML resource to be validated via Schematron. May not be
141 * <code>null</code>.
142 * @return <code>null</code> if the passed resource does not exist or the non-
143 * <code>null</code> SVRL document otherwise.
144 * @throws Exception
145 * In case the transformation somehow goes wrong.
146 * @see com.helger.schematron.svrl.SVRLMarshaller on how to convert the
147 * document into a domain object
148 */
149 @Nullable
150 Document applySchematronValidation (@Nonnull IHasInputStream aXMLResource) throws Exception;
151
152 /**
153 * Apply the Schematron validation on the passed DOM node and return an SVRL
154 * XML DOM Document.
155 *
156 * @param aXMLNode
157 * The DOM node to be validated via Schematron. May not be
158 * <code>null</code>.
159 * @param sBaseURI
160 * The Base URI of the XML document to be validated. May be
161 * <code>null</code>.
162 * @return <code>null</code> if the passed resource does not exist or the non-
163 * <code>null</code> SVRL document otherwise.
164 * @throws Exception
165 * In case the transformation somehow goes wrong.
166 * @see com.helger.schematron.svrl.SVRLMarshaller on how to convert the
167 * document into a domain object
168 */
169 @Nullable
170 Document applySchematronValidation (@Nonnull Node aXMLNode, @Nullable String sBaseURI) throws Exception;
171
172 /**
173 * Apply the Schematron validation on the passed XML source and return an SVRL
174 * XML DOM Document.
175 *
176 * @param aXMLSource
177 * The XML source to be validated via Schematron. May not be
178 * <code>null</code>.
179 * @return The SVRL XML document containing the result. May be
180 * <code>null</code> when interpreting the Schematron failed.
181 * @throws Exception
182 * In case the transformation somehow goes wrong.
183 * @see com.helger.schematron.svrl.SVRLMarshaller on how to convert the
184 * document into a domain object
185 */
186 @Nullable
187 Document applySchematronValidation (@Nonnull Source aXMLSource) throws Exception;
188
189 /**
190 * Apply the Schematron validation on the passed XML resource and return a
191 * {@link SchematronOutputType} object.
192 *
193 * @param aXMLResource
194 * The XML resource to be validated via Schematron. May not be
195 * <code>null</code>.
196 * @return The SVRL object containing the result. May be <code>null</code>
197 * when interpreting the Schematron failed.
198 * @throws Exception
199 * In case the transformation somehow goes wrong.
200 */
201 @Nullable
202 SchematronOutputType applySchematronValidationToSVRL (@Nonnull IHasInputStream aXMLResource) throws Exception;
203
204 /**
205 * Apply the Schematron validation on the passed DOM Node and return a
206 * {@link SchematronOutputType} object.
207 *
208 * @param aXMLNode
209 * The DOM node to be validated via Schematron. May not be
210 * <code>null</code>.
211 * @param sBaseURI
212 * The Base URI of the XML document to be validated. May be
213 * <code>null</code>.
214 * @return The SVRL object containing the result. May be <code>null</code>
215 * when interpreting the Schematron failed.
216 * @throws Exception
217 * In case the transformation somehow goes wrong.
218 */
219 @Nullable
220 SchematronOutputType applySchematronValidationToSVRL (@Nonnull Node aXMLNode,
221 @Nullable String sBaseURI) throws Exception;
222
223 /**
224 * Apply the Schematron validation on the passed XML source and return a
225 * {@link SchematronOutputType} object.
226 *
227 * @param aXMLSource
228 * The XML source to be validated via Schematron. May not be
229 * <code>null</code>.
230 * @return The SVRL object containing the result. May be <code>null</code>
231 * when interpreting the Schematron failed.
232 * @throws Exception
233 * In case the transformation somehow goes wrong.
234 */
235 @Nullable
236 SchematronOutputType applySchematronValidationToSVRL (@Nonnull Source aXMLSource) throws Exception;
237 }