001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.components.validation;
018:
019: import java.io.IOException;
020:
021: import org.apache.excalibur.source.Source;
022: import org.xml.sax.ErrorHandler;
023: import org.xml.sax.SAXException;
024:
025: /**
026: * <p>The {@link Validator} interface provides the abstraction of a component able
027: * to validate XML documents using schemas defined in different languages.</p>
028: *
029: * <p>This is basically the main entry point of the validation API, allowing users
030: * to transparently access validators (in the form of {@link ValidationHandler}s
031: * receiving SAX events for the documents to be validated), in different grammar
032: * languages, using different implementations.</p>
033: *
034: * <p>As more than one {@link SchemaParser} might be able to parse and create
035: * {@link Schema} instances for a particular grammar language, this interface
036: * defines a unique lookup method to allow selection of a particular
037: * {@link SchemaParser} implementation.</p>
038: *
039: * <p>Assuming that two different {@link SchemaParser}s called <code>first</code>
040: * and <code>second</code> are both able to understand the
041: * {@link #GRAMMAR_RELAX_NG RELAX NG} grammar (identified by the
042: * <code>http://relaxng.org/ns/structure/1.0</code> identifier) one could select
043: * between the two implementation using the following two strings:</p>
044: *
045: * <ul>
046: * <li><code>first:http://relaxng.org/ns/structure/1.0</code></li>
047: * <li><code>second:http://relaxng.org/ns/structure/1.0</code></li>
048: * </ul>
049: *
050: * <p>As a rule (unless when this is impossible) the grammar identifier is
051: * equivalent to the namespace of the root element of a schema.</p>
052: *
053: */
054: public interface Validator {
055:
056: /** <p>Avalon Role name of {@link Validator} components.</p> */
057: public static final String ROLE = Validator.class.getName();
058:
059: /** <p>The <a href="http://www.schematron.com/">ISO Schematron</a/> grammar identifer.</p> */
060: public static final String GRAMMAR_ISO_SCHEMATRON = "http://purl.oclc.org/dsdl/schematron";
061: /** <p>The <a href="http://www.relaxng.org/">RELAX NG</a/> grammar identifer.</p> */
062: public static final String GRAMMAR_RELAX_NG = "http://relaxng.org/ns/structure/1.0";
063: /** <p>The <a href="http://www.xml.gr.jp/relax">RELAX Core</a/> grammar identifer.</p> */
064: public static final String GRAMMAR_RELAX_CORE = "http://www.xml.gr.jp/xmlns/relaxCore";
065: /** <p>The <a href="http://www.xml.gr.jp/relax">RELAX Namespace</a/> grammar identifer.</p> */
066: public static final String GRAMMAR_RELAX_NS = "http://www.xml.gr.jp/xmlns/relaxNamespace";
067: /** <p>The <a href="http://xml.ascc.net/schematron/">Schematron</a/> grammar identifer.</p> */
068: public static final String GRAMMAR_SCHEMATRON = "http://www.ascc.net/xml/schematron";
069: /** <p>The <a href="http://www.thaiopensource.com/trex/">Trex</a/> grammar identifer.</p> */
070: public static final String GRAMMAR_TREX = "http://www.thaiopensource.com/trex";
071: /** <p>The <a href="http://www.w3.org/XML/Schema">XML Schema</a/> grammar identifer.</p> */
072: public static final String GRAMMAR_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema";
073: /** <p>The <a href="http://www.w3.org/TR/REC-xml">XML DTD</a/> grammar identifer.</p> */
074: public static final String GRAMMAR_XML_DTD = "http://www.w3.org/TR/REC-xml";
075:
076: /**
077: * <p>Return a {@link ValidationHandler} validating an XML document according to
078: * the schema found at the specified location.</p>
079: *
080: * <p>The {@link Validator} will attempt to automatically detect the grammar
081: * language of the specified schema, and each error or warning occurring while
082: * validating the document will trigger a {@link SAXException} to be thrown back
083: * to the caller.</p>
084: *
085: * @param uri the location of the schema to use to validate the document.
086: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
087: * the original XML document to validate.
088: * @throws IOException if an I/O error occurred parsing the schema.
089: * @throws SAXException if a grammar error occurred parsing the schema.
090: * @throws ValidatorException if the grammar language of the specified schema
091: * could not be detected or was not supported.
092: * @see SchemaParser#parseSchema(Source, String)
093: * @see Schema#createValidator(ErrorHandler)
094: */
095: public ValidationHandler getValidationHandler(String uri)
096: throws IOException, SAXException, ValidatorException;
097:
098: /**
099: * <p>Return a {@link ValidationHandler} validating an XML document according to
100: * the schema found at the specified location.</p>
101: *
102: * <p>Each error or warning occurring while validating the document will trigger
103: * a {@link SAXException} to be thrown back to the caller.</p>
104: *
105: * @param uri the location of the schema to use to validate the document.
106: * @param grammar the grammar language of the schema to parse.
107: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
108: * the original XML document to validate.
109: * @throws IOException if an I/O error occurred parsing the schema.
110: * @throws SAXException if a grammar error occurred parsing the schema.
111: * @throws ValidatorException if the specified grammar language wasn't supported.
112: * @see SchemaParser#parseSchema(Source, String)
113: * @see Schema#createValidator(ErrorHandler)
114: */
115: public ValidationHandler getValidationHandler(String uri,
116: String grammar) throws IOException, SAXException,
117: ValidatorException;
118:
119: /**
120: * <p>Return a {@link ValidationHandler} validating an XML document according to
121: * the schema found at the specified location.</p>
122: *
123: * <p>The {@link Validator} will attempt to automatically detect the grammar
124: * language of the specified schema, while each validation error or warning will
125: * be passed to the specified {@link ErrorHandler} which will have the ability
126: * to generate and throw a {@link SAXException} back to the caller.</p>
127: *
128: * @param uri the location of the schema to use to validate the document.
129: * @param errorHandler the {@link ErrorHandler} notified of validation problems.
130: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
131: * the original XML document to validate.
132: * @throws IOException if an I/O error occurred parsing the schema.
133: * @throws SAXException if a grammar error occurred parsing the schema.
134: * @throws ValidatorException if the grammar language of the specified schema
135: * could not be detected or was not supported.
136: * @see SchemaParser#parseSchema(Source, String)
137: * @see Schema#createValidator(ErrorHandler)
138: */
139: public ValidationHandler getValidationHandler(String uri,
140: ErrorHandler errorHandler) throws IOException,
141: SAXException, ValidatorException;
142:
143: /**
144: * <p>Return a {@link ValidationHandler} validating an XML document according to
145: * the schema found at the specified location.</p>
146: *
147: * <p>Each validation error or warning will be passed to the specified
148: * {@link ErrorHandler} which will have the ability to generate and throw a
149: * {@link SAXException} back to the caller.</p>
150: *
151: * @param uri the location of the schema to use to validate the document.
152: * @param grammar the grammar language of the schema to parse.
153: * @param errorHandler the {@link ErrorHandler} notified of validation problems.
154: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
155: * the original XML document to validate.
156: * @throws IOException if an I/O error occurred parsing the schema.
157: * @throws SAXException if a grammar error occurred parsing the schema.
158: * @throws ValidatorException if the specified grammar language wasn't supported.
159: * @see SchemaParser#parseSchema(Source, String)
160: * @see Schema#createValidator(ErrorHandler)
161: */
162: public ValidationHandler getValidationHandler(String uri,
163: String grammar, ErrorHandler errorHandler)
164: throws IOException, SAXException, ValidatorException;
165:
166: /**
167: * <p>Return a {@link ValidationHandler} validating an XML document according to
168: * the schema found at the specified location.</p>
169: *
170: * <p>The {@link Validator} will attempt to automatically detect the grammar
171: * language of the specified schema, and each error or warning occurring while
172: * validating the document will trigger a {@link SAXException} to be thrown back
173: * to the caller.</p>
174: *
175: * @param source the {@link Source} identifying the schema to use for validation.
176: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
177: * the original XML document to validate.
178: * @throws IOException if an I/O error occurred parsing the schema.
179: * @throws SAXException if a grammar error occurred parsing the schema.
180: * @throws ValidatorException if the grammar language of the specified schema
181: * could not be detected or was not supported.
182: * @see SchemaParser#parseSchema(Source, String)
183: * @see Schema#createValidator(ErrorHandler)
184: */
185: public ValidationHandler getValidationHandler(Source source)
186: throws IOException, SAXException, ValidatorException;
187:
188: /**
189: * <p>Return a {@link ValidationHandler} validating an XML document according to
190: * the schema found at the specified location.</p>
191: *
192: * <p>Each error or warning occurring while validating the document will trigger
193: * a {@link SAXException} to be thrown back to the caller.</p>
194: *
195: * @param source the {@link Source} identifying the schema to use for validation.
196: * @param grammar the grammar language of the schema to parse.
197: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
198: * the original XML document to validate.
199: * @throws IOException if an I/O error occurred parsing the schema.
200: * @throws SAXException if a grammar error occurred parsing the schema.
201: * @throws ValidatorException if the specified grammar language wasn't supported.
202: * @see SchemaParser#parseSchema(Source, String)
203: * @see Schema#createValidator(ErrorHandler)
204: */
205: public ValidationHandler getValidationHandler(Source source,
206: String grammar) throws IOException, SAXException,
207: ValidatorException;
208:
209: /**
210: * <p>Return a {@link ValidationHandler} validating an XML document according to
211: * the schema found at the specified location.</p>
212: *
213: * <p>The {@link Validator} will attempt to automatically detect the grammar
214: * language of the specified schema, while each validation error or warning will
215: * be passed to the specified {@link ErrorHandler} which will have the ability
216: * to generate and throw a {@link SAXException} back to the caller.</p>
217: *
218: * @param source the {@link Source} identifying the schema to use for validation.
219: * @param errorHandler the {@link ErrorHandler} notified of validation problems.
220: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
221: * the original XML document to validate.
222: * @throws IOException if an I/O error occurred parsing the schema.
223: * @throws SAXException if a grammar error occurred parsing the schema.
224: * @throws ValidatorException if the grammar language of the specified schema
225: * could not be detected or was not supported.
226: * @see SchemaParser#parseSchema(Source, String)
227: * @see Schema#createValidator(ErrorHandler)
228: */
229: public ValidationHandler getValidationHandler(Source source,
230: ErrorHandler errorHandler) throws IOException,
231: SAXException, ValidatorException;
232:
233: /**
234: * <p>Return a {@link ValidationHandler} validating an XML document according to
235: * the schema found at the specified location.</p>
236: *
237: * <p>Each validation error or warning will be passed to the specified
238: * {@link ErrorHandler} which will have the ability to generate and throw a
239: * {@link SAXException} back to the caller.</p>
240: *
241: * @param source the {@link Source} identifying the schema to use for validation.
242: * @param grammar the grammar language of the schema to parse.
243: * @param errorHandler the {@link ErrorHandler} notified of validation problems.
244: * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
245: * the original XML document to validate.
246: * @throws IOException if an I/O error occurred parsing the schema.
247: * @throws SAXException if a grammar error occurred parsing the schema.
248: * @throws ValidatorException if the specified grammar language wasn't supported.
249: * @see SchemaParser#parseSchema(Source, String)
250: * @see Schema#createValidator(ErrorHandler)
251: */
252: public ValidationHandler getValidationHandler(Source source,
253: String grammar, ErrorHandler errorHandler)
254: throws IOException, SAXException, ValidatorException;
255:
256: }
|