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;
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
26 import com.helger.commons.id.IHasID;
27 import com.helger.commons.io.IHasInputStream;
28 import com.helger.commons.io.resource.IReadableResource;
29 import com.helger.commons.state.EValidity;
30 import com.helger.schematron.svrl.SVRLReader;
31
32 /**
33 * Base interface for a Schematron resource. The implementation can e.g. be a
34 * SCH file that needs preprocessing to XSLT or an already precompiled XSLT
35 * file.
36 *
37 * @author Philip Helger
38 */
39 public interface ISchematronResource extends IHasID <String>
40 {
41 /**
42 * @return The non-<code>null</code> resource from which to read the
43 * Schematron rules.
44 */
45 @Nonnull
46 IReadableResource getResource ();
47
48 /**
49 * @return <code>true</code> if this Schematron can be used to validate XML
50 * instances. If not, the Schematron is invalid and the log files must
51 * be investigated.
52 */
53 boolean isValidSchematron ();
54
55 /**
56 * A method to check if the passed XML DOM node matches the Schematron rules
57 * or not. This is the quick check method, as it breaks upon the first failed
58 * assertion or the first successful report, if the implementation supports it
59 * (as e.g. the native pure Schematron version).
60 *
61 * @param aXMLResource
62 * The source XML to read and validate against the Schematron. May not
63 * be <code>null</code>.
64 * @return {@link EValidity#VALID} if the document is valid,
65 * {@link EValidity#INVALID} if it is invalid.
66 * @throws Exception
67 * in case of a sever error validating the schema
68 */
69 @Nonnull
70 EValidity getSchematronValidity (@Nonnull final IHasInputStream aXMLResource) throws Exception;
71
72 /**
73 * A method to check if the passed XML DOM node matches the Schematron rules
74 * or not. This is the quick check method, as it breaks upon the first failed
75 * assertion or the first successful report, if the implementation supports it
76 * (as e.g. the native pure Schematron version).
77 *
78 * @param aXMLSource
79 * The source XML to be validated against the Schematron. May not be
80 * <code>null</code>.
81 * @return {@link EValidity#VALID} if the document is valid,
82 * {@link EValidity#INVALID} if it is invalid.
83 * @throws Exception
84 * in case of a sever error validating the schema
85 */
86 @Nonnull
87 EValidity getSchematronValidity (@Nonnull final Source aXMLSource) throws Exception;
88
89 /**
90 * Apply the Schematron validation on the passed XML resource and return an
91 * SVRL XML DOM Document.
92 *
93 * @param aXMLResource
94 * The XML resource to validate via Schematron. May not be
95 * <code>null</code>.
96 * @return <code>null</code> if the passed resource does not exist or the non-
97 * <code>null</code> SVRL document otherwise.
98 * @throws Exception
99 * In case the transformation somehow goes wrong.
100 * @see SVRLReader#readXML(org.w3c.dom.Node) on how to convert the document
101 * into a domain object
102 */
103 @Nullable
104 Document applySchematronValidation (@Nonnull IHasInputStream aXMLResource) throws Exception;
105
106 /**
107 * Apply the Schematron validation on the passed XML source and return an SVRL
108 * XML DOM Document.
109 *
110 * @param aXMLSource
111 * The XML source to validate via Schematron. May not be
112 * <code>null</code>.
113 * @return The SVRL XML document containing the result. May be
114 * <code>null</code> when interpreting the Schematron failed.
115 * @throws Exception
116 * In case the transformation somehow goes wrong.
117 * @see SVRLReader#readXML(org.w3c.dom.Node) on how to convert the document
118 * into a domain object
119 */
120 @Nullable
121 Document applySchematronValidation (@Nonnull Source aXMLSource) throws Exception;
122
123 /**
124 * Apply the Schematron validation on the passed XML resource and return a
125 * {@link SchematronOutputType} object.
126 *
127 * @param aXMLResource
128 * The XML resource to validate via Schematron. May not be
129 * <code>null</code>.
130 * @return The SVRL object containing the result. May be <code>null</code>
131 * when interpreting the Schematron failed.
132 * @throws Exception
133 * In case the transformation somehow goes wrong.
134 */
135 @Nullable
136 SchematronOutputType applySchematronValidationToSVRL (@Nonnull IHasInputStream aXMLResource) throws Exception;
137
138 /**
139 * Apply the Schematron validation on the passed XML source and return a
140 * {@link SchematronOutputType} object.
141 *
142 * @param aXMLSource
143 * The XML source to validate via Schematron. May not be
144 * <code>null</code>.
145 * @return The SVRL object containing the result. May be <code>null</code>
146 * when interpreting the Schematron failed.
147 * @throws Exception
148 * In case the transformation somehow goes wrong.
149 */
150 @Nullable
151 SchematronOutputType applySchematronValidationToSVRL (@Nonnull Source aXMLSource) throws Exception;
152 }