Validator


1   /*
2    * Copyright 1999-2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.cocoon.components.validation;
17  
18  import java.io.IOException  ;
19  
20  import org.apache.excalibur.source.Source;
21  import org.xml.sax.ErrorHandler  ;
22  import org.xml.sax.SAXException  ;
23  
24  /**
25   * <p>The {@link Validator} interface provides the abstraction of a component able
26   * to validate XML documents using schemas defined in different languages.</p>
27   * 
28   * <p>This is basically the main entry point of the validation API, allowing users
29   * to transparently access validators (in the form of {@link ValidationHandler}s
30   * receiving SAX events for the documents to be validated), in different grammar
31   * languages, using different implementations.</p>
32   * 
33   * <p>As more than one {@link SchemaParser} might be able to parse and create
34   * {@link Schema} instances for a particular grammar language, this interface
35   * defines a unique lookup method to allow selection of a particular
36   * {@link SchemaParser} implementation.</p>
37   * 
38   * <p>Assuming that two different {@link SchemaParser}s called <code>first</code>
39   * and <code>second</code> are both able to understand the
40   * {@link #GRAMMAR_RELAX_NG RELAX NG} grammar (identified by the
41   * <code>http://relaxng.org/ns/structure/1.0</code> identifier) one could select
42   * between the two implementation using the following two strings:</p>
43   * 
44   * <ul>
45   *   <li><code>first:http://relaxng.org/ns/structure/1.0</code></li>
46   *   <li><code>second:http://relaxng.org/ns/structure/1.0</code></li>
47   * </ul>
48   * 
49   * <p>As a rule (unless when this is impossible) the grammar identifier is
50   * equivalent to the namespace of the root element of a schema.</p>
51   *
52   * @author <a HREF="mailto:pier@betaversion.org">Pier Fumagalli</a>
53   */
54  public interface Validator {
55  
56      /** <p>Avalon Role name of {@link Validator} components.</p> */
57      public static final String   ROLE = Validator.class.getName();
58  
59      /** <p>The <a HREF="http://www.schematron.com/">ISO Schematron</a/> grammar identifer.</p> */
60      public static final String   GRAMMAR_ISO_SCHEMATRON = "http://purl.oclc.org/dsdl/schematron";
61      /** <p>The <a HREF="http://www.relaxng.org/">RELAX NG</a/> grammar identifer.</p> */
62      public static final String   GRAMMAR_RELAX_NG = "http://relaxng.org/ns/structure/1.0";
63      /** <p>The <a HREF="http://www.xml.gr.jp/relax">RELAX Core</a/> grammar identifer.</p> */
64      public static final String   GRAMMAR_RELAX_CORE = "http://www.xml.gr.jp/xmlns/relaxCore";
65      /** <p>The <a HREF="http://www.xml.gr.jp/relax">RELAX Namespace</a/> grammar identifer.</p> */
66      public static final String   GRAMMAR_RELAX_NS = "http://www.xml.gr.jp/xmlns/relaxNamespace";
67      /** <p>The <a HREF="http://xml.ascc.net/schematron/">Schematron</a/> grammar identifer.</p> */
68      public static final String   GRAMMAR_SCHEMATRON = "http://www.ascc.net/xml/schematron";
69      /** <p>The <a HREF="http://www.thaiopensource.com/trex/">Trex</a/> grammar identifer.</p> */
70      public static final String   GRAMMAR_TREX = "http://www.thaiopensource.com/trex";
71      /** <p>The <a HREF="http://www.w3.org/XML/Schema">XML Schema</a/> grammar identifer.</p> */
72      public static final String   GRAMMAR_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema";
73      /** <p>The <a HREF="http://www.w3.org/TR/REC-xml">XML DTD</a/> grammar identifer.</p> */
74      public static final String   GRAMMAR_XML_DTD = "http://www.w3.org/TR/REC-xml";
75  
76      /**
77       * <p>Return a {@link ValidationHandler} validating an XML document according to
78       * the schema found at the specified location.</p>
79       *
80       * <p>The {@link Validator} will attempt to automatically detect the grammar
81       * language of the specified schema, and each error or warning occurring while
82       * validating the document will trigger a {@link SAXException} to be thrown back
83       * to the caller.</p> 
84       *
85       * @param uri the location of the schema to use to validate the document.
86       * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
87       *         the original XML document to validate.
88       * @throws IOException if an I/O error occurred parsing the schema.
89       * @throws SAXException if a grammar error occurred parsing the schema.
90       * @throws ValidatorException if the grammar language of the specified schema
91       *                            could not be detected or was not supported.
92       * @link SchemaParser#getSchema(String, String)
93       * @link Schema#createValidator(ErrorHandler)
94       */
95      public ValidationHandler getValidationHandler(String   uri)
96      throws IOException  , SAXException  , ValidatorException;
97  
98      /**
99       * <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      * @link SchemaParser#getSchema(String, String)
113      * @link Schema#createValidator(ErrorHandler)
114      */
115     public ValidationHandler getValidationHandler(String   uri, String   grammar)
116     throws IOException  , SAXException  , ValidatorException;
117 
118     /**
119      * <p>Return a {@link ValidationHandler} validating an XML document according to
120      * the schema found at the specified location.</p>
121      *
122      * <p>The {@link Validator} will attempt to automatically detect the grammar
123      * language of the specified schema, while each validation error or warning will
124      * be passed to the specified {@link ErrorHandler} which will have the ability
125      * to generate and throw a {@link SAXException} back to the caller.</p>
126      *
127      * @param uri the location of the schema to use to validate the document.
128      * @param errorHandler the {@link ErrorHandler} notified of validation problems.
129      * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
130      *         the original XML document to validate.
131      * @throws IOException if an I/O error occurred parsing the schema.
132      * @throws SAXException if a grammar error occurred parsing the schema.
133      * @throws ValidatorException if the grammar language of the specified schema
134      *                            could not be detected or was not supported.
135      * @link SchemaParser#getSchema(String, String)
136      * @link Schema#createValidator(ErrorHandler)
137      */
138     public ValidationHandler getValidationHandler(String   uri, ErrorHandler   errorHandler)
139     throws IOException  , SAXException  , ValidatorException;
140 
141     /**
142      * <p>Return a {@link ValidationHandler} validating an XML document according to
143      * the schema found at the specified location.</p>
144      *
145      * <p>Each validation error or warning will be passed to the specified
146      * {@link ErrorHandler} which will have the ability to generate and throw a
147      * {@link SAXException} back to the caller.</p>
148      *
149      * @param uri the location of the schema to use to validate the document.
150      * @param grammar the grammar language of the schema to parse.
151      * @param errorHandler the {@link ErrorHandler} notified of validation problems.
152      * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
153      *         the original XML document to validate.
154      * @throws IOException if an I/O error occurred parsing the schema.
155      * @throws SAXException if a grammar error occurred parsing the schema.
156      * @throws ValidatorException if the specified grammar language wasn't supported.
157      * @link SchemaParser#getSchema(String, String)
158      * @link Schema#createValidator(ErrorHandler)
159      */
160     public ValidationHandler getValidationHandler(String   uri, String   grammar,
161                                                ErrorHandler   errorHandler)
162     throws IOException  , SAXException  , ValidatorException;
163 
164     /**
165      * <p>Return a {@link ValidationHandler} validating an XML document according to
166      * the schema found at the specified location.</p>
167      *
168      * <p>The {@link Validator} will attempt to automatically detect the grammar
169      * language of the specified schema, and each error or warning occurring while
170      * validating the document will trigger a {@link SAXException} to be thrown back
171      * to the caller.</p> 
172      *
173      * @param source the {@link Source} identifying the schema to use for validation.
174      * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
175      *         the original XML document to validate.
176      * @throws IOException if an I/O error occurred parsing the schema.
177      * @throws SAXException if a grammar error occurred parsing the schema.
178      * @throws ValidatorException if the grammar language of the specified schema
179      *                            could not be detected or was not supported.
180      * @link SchemaParser#getSchema(String, String)
181      * @link Schema#createValidator(ErrorHandler)
182      */
183     public ValidationHandler getValidationHandler(Source source)
184     throws IOException  , SAXException  , ValidatorException;
185 
186     /**
187      * <p>Return a {@link ValidationHandler} validating an XML document according to
188      * the schema found at the specified location.</p>
189      *
190      * <p>Each error or warning occurring while validating the document will trigger
191      * a {@link SAXException} to be thrown back to the caller.</p> 
192      *
193      * @param source the {@link Source} identifying the schema to use for validation.
194      * @param grammar the grammar language of the schema to parse.
195      * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
196      *         the original XML document to validate.
197      * @throws IOException if an I/O error occurred parsing the schema.
198      * @throws SAXException if a grammar error occurred parsing the schema.
199      * @throws ValidatorException if the specified grammar language wasn't supported.
200      * @link SchemaParser#getSchema(String, String)
201      * @link Schema#createValidator(ErrorHandler)
202      */
203     public ValidationHandler getValidationHandler(Source source, String   grammar)
204     throws IOException  , SAXException  , ValidatorException;
205 
206     /**
207      * <p>Return a {@link ValidationHandler} validating an XML document according to
208      * the schema found at the specified location.</p>
209      *
210      * <p>The {@link Validator} will attempt to automatically detect the grammar
211      * language of the specified schema, while each validation error or warning will
212      * be passed to the specified {@link ErrorHandler} which will have the ability
213      * to generate and throw a {@link SAXException} back to the caller.</p>
214      *
215      * @param source the {@link Source} identifying the schema to use for validation.
216      * @param errorHandler the {@link ErrorHandler} notified of validation problems.
217      * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
218      *         the original XML document to validate.
219      * @throws IOException if an I/O error occurred parsing the schema.
220      * @throws SAXException if a grammar error occurred parsing the schema.
221      * @throws ValidatorException if the grammar language of the specified schema
222      *                            could not be detected or was not supported.
223      * @link SchemaParser#getSchema(String, String)
224      * @link Schema#createValidator(ErrorHandler)
225      */
226     public ValidationHandler getValidationHandler(Source source,
227                                                   ErrorHandler   errorHandler)
228     throws IOException  , SAXException  , ValidatorException;
229 
230     /**
231      * <p>Return a {@link ValidationHandler} validating an XML document according to
232      * the schema found at the specified location.</p>
233      *
234      * <p>Each validation error or warning will be passed to the specified
235      * {@link ErrorHandler} which will have the ability to generate and throw a
236      * {@link SAXException} back to the caller.</p>
237      *
238      * @param source the {@link Source} identifying the schema to use for validation.
239      * @param grammar the grammar language of the schema to parse.
240      * @param errorHandler the {@link ErrorHandler} notified of validation problems.
241      * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
242      *         the original XML document to validate.
243      * @throws IOException if an I/O error occurred parsing the schema.
244      * @throws SAXException if a grammar error occurred parsing the schema.
245      * @throws ValidatorException if the specified grammar language wasn't supported.
246      * @link SchemaParser#getSchema(String, String)
247      * @link Schema#createValidator(ErrorHandler)
248      */
249     public ValidationHandler getValidationHandler(Source source, String   grammar,
250                                                ErrorHandler   errorHandler)
251     throws IOException  , SAXException  , ValidatorException;
252 
253 }
254
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags