1 /**
2 * Copyright (C) 2014-2017 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
27 import com.helger.commons.id.IHasID;
28 import com.helger.commons.io.IHasInputStream;
29 import com.helger.commons.io.resource.IReadableResource;
30 import com.helger.commons.state.EValidity;
31 import com.helger.schematron.svrl.SVRLReader;
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> if this Schematron can be used to validate XML
51 * instances. If not, the Schematron is invalid and the log files must
52 * be investigated.
53 */
54 boolean isValidSchematron ();
55
56 /**
57 * A method to check if the passed XML DOM node matches the Schematron rules
58 * or not. This is the quick check method, as it breaks upon the first failed
59 * assertion or the first successful report, if the implementation supports it
60 * (as e.g. the native pure Schematron version).
61 *
62 * @param aXMLResource
63 * The source XML to read and validate against the Schematron. May not
64 * be <code>null</code>.
65 * @return {@link EValidity#VALID} if the document is valid,
66 * {@link EValidity#INVALID} if it is invalid.
67 * @throws Exception
68 * in case of a sever error validating the schema
69 */
70 @Nonnull
71 EValidity getSchematronValidity (@Nonnull IHasInputStream aXMLResource) throws Exception;
72
73 /**
74 * A method to check if the passed DOM node matches the Schematron rules or
75 * not. This is the quick check method, as it breaks upon the first failed
76 * assertion or the first successful report, if the implementation supports it
77 * (as e.g. the native pure Schematron version).
78 *
79 * @param aXMLNode
80 * The source DOM node to validate against the Schematron. May not be
81 * <code>null</code>.
82 * @return {@link EValidity#VALID} if the document is valid,
83 * {@link EValidity#INVALID} if it is invalid.
84 * @throws Exception
85 * in case of a sever error validating the schema
86 */
87 @Nonnull
88 EValidity getSchematronValidity (@Nonnull Node aXMLNode) throws Exception;
89
90 /**
91 * A method to check if the passed XML DOM node matches the Schematron rules
92 * or not. This is the quick check method, as it breaks upon the first failed
93 * assertion or the first successful report, if the implementation supports it
94 * (as e.g. the native pure Schematron version).
95 *
96 * @param aXMLSource
97 * The source XML to be validated against the Schematron. May not be
98 * <code>null</code>.
99 * @return {@link EValidity#VALID} if the document is valid,
100 * {@link EValidity#INVALID} if it is invalid.
101 * @throws Exception
102 * in case of a sever error validating the schema
103 */
104 @Nonnull
105 EValidity getSchematronValidity (@Nonnull Source aXMLSource) throws Exception;
106
107 /**
108 * Apply the Schematron validation on the passed XML resource and return an
109 * SVRL XML DOM Document.
110 *
111 * @param aXMLResource
112 * The XML resource to be validated via Schematron. May not be
113 * <code>null</code>.
114 * @return <code>null</code> if the passed resource does not exist or the non-
115 * <code>null</code> SVRL document otherwise.
116 * @throws Exception
117 * In case the transformation somehow goes wrong.
118 * @see SVRLReader#readXML(org.w3c.dom.Node) on how to convert the document
119 * into a domain object
120 */
121 @Nullable
122 Document applySchematronValidation (@Nonnull IHasInputStream aXMLResource) throws Exception;
123
124 /**
125 * Apply the Schematron validation on the passed DOM node and return an SVRL
126 * XML DOM Document.
127 *
128 * @param aXMLNode
129 * The DOM node to be validated via Schematron. May not be
130 * <code>null</code>.
131 * @return <code>null</code> if the passed resource does not exist or the non-
132 * <code>null</code> SVRL document otherwise.
133 * @throws Exception
134 * In case the transformation somehow goes wrong.
135 * @see SVRLReader#readXML(org.w3c.dom.Node) on how to convert the document
136 * into a domain object
137 */
138 @Nullable
139 Document applySchematronValidation (@Nonnull Node aXMLNode) throws Exception;
140
141 /**
142 * Apply the Schematron validation on the passed XML source and return an SVRL
143 * XML DOM Document.
144 *
145 * @param aXMLSource
146 * The XML source to be validated via Schematron. May not be
147 * <code>null</code>.
148 * @return The SVRL XML document containing the result. May be
149 * <code>null</code> when interpreting the Schematron failed.
150 * @throws Exception
151 * In case the transformation somehow goes wrong.
152 * @see SVRLReader#readXML(org.w3c.dom.Node) on how to convert the document
153 * into a domain object
154 */
155 @Nullable
156 Document applySchematronValidation (@Nonnull Source aXMLSource) throws Exception;
157
158 /**
159 * Apply the Schematron validation on the passed XML resource and return a
160 * {@link SchematronOutputType} object.
161 *
162 * @param aXMLResource
163 * The XML resource to be validated via Schematron. May not be
164 * <code>null</code>.
165 * @return The SVRL object containing the result. May be <code>null</code>
166 * when interpreting the Schematron failed.
167 * @throws Exception
168 * In case the transformation somehow goes wrong.
169 */
170 @Nullable
171 SchematronOutputType applySchematronValidationToSVRL (@Nonnull IHasInputStream aXMLResource) throws Exception;
172
173 /**
174 * Apply the Schematron validation on the passed DOM Node and return a
175 * {@link SchematronOutputType} object.
176 *
177 * @param aXMLNode
178 * The DOM node to be validated via Schematron. May not be
179 * <code>null</code>.
180 * @return The SVRL object containing the result. May be <code>null</code>
181 * when interpreting the Schematron failed.
182 * @throws Exception
183 * In case the transformation somehow goes wrong.
184 */
185 @Nullable
186 SchematronOutputType applySchematronValidationToSVRL (@Nonnull Node aXMLNode) throws Exception;
187
188 /**
189 * Apply the Schematron validation on the passed XML source and return a
190 * {@link SchematronOutputType} object.
191 *
192 * @param aXMLSource
193 * The XML source to be validated via Schematron. May not be
194 * <code>null</code>.
195 * @return The SVRL object containing the result. May be <code>null</code>
196 * when interpreting the Schematron failed.
197 * @throws Exception
198 * In case the transformation somehow goes wrong.
199 */
200 @Nullable
201 SchematronOutputType applySchematronValidationToSVRL (@Nonnull Source aXMLSource) throws Exception;
202 }