KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > cocoon > components > validation > Schema


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 org.apache.excalibur.source.SourceValidity;
19 import org.xml.sax.ErrorHandler JavaDoc;
20 import org.xml.sax.SAXException JavaDoc;
21
22 /**
23  * <p>The {@link Schema} interface defines an abstraction of a schema usable to
24  * validate an XML document.</p>
25  *
26  * <p>This interface is not tied to any specific validation grammar language
27  * such as the <a HREF="http://www.w3.org/XML/Schema">W3C XML Shema</a> language
28  * or the <a HREF="http://www.relaxng.org/">RELAX-NG</a/> language.</p>
29  *
30  * <p>Selection and use of specific schema grammar languages is performed through
31  * the use of the {@link Validator} interface.</p>
32  *
33  * <p>Once returned by the {@link SchemaParser}, a {@link Schema} instance must be
34  * able to validate a number of XML documents: each time a document needs to be
35  * validated, a new {@link ValidationHandler} can be obtained invoking the
36  * {@link #createValidator(ErrorHandler)} method. While validating an XML document,
37  * {@link SAXException}s should be thrown back to the caller only when the specified
38  * {@link ErrorHandler} is configured to do so.</p>
39  *
40  * @author <a HREF="mailto:pier@betaversion.org">Pier Fumagalli</a>
41  */
42 public interface Schema {
43
44     /**
45      * <p>Return the {@link SourceValidity} associated with this {@link Schema}.</p>
46      *
47      * <p>If the schema represented by this instance was parsed from several sources
48      * (through the use of inclusions or referencing to external entities, for
49      * example) the {@link SourceValidity} returned by this method <b>must</b>
50      * consider all of them when the {@link SourceValidity#isValid()} or the
51      * {@link SourceValidity#isValid(SourceValidity)} methods are called.</p>
52      *
53      * @return a {@link SourceValidity} instance or <b>null</b> if not known.
54      */
55     public SourceValidity getValidity();
56
57     /**
58      * <p>Return a new {@link ValidationHandler} instance that can be used to
59      * validate an XML document by sending SAX events to it.</p>
60      *
61      * <p>The specified {@link ErrorHandler} will be notified of all warnings or
62      * errors encountered validating the SAX events sent to the returned
63      * {@link ValidationHandler}, and <b>must not</b> be <b>null</b>.</p>
64      *
65      * <p>The returned {@link ValidationHandler} can be used to validate <b>only
66      * one</b> XML document. To validate more than one document, this method should
67      * be called once for each document to validate.</p>
68      *
69      * @param handler an {@link ErrorHandler} to notify of validation errors.
70      * @return a <b>non-null</b> {@link ValidationHandler} instance.
71      * @throws SAXException if an error occurred creating the validation handler.
72      */
73     public ValidationHandler createValidator(ErrorHandler JavaDoc handler)
74     throws SAXException JavaDoc;
75
76 }
77
Popular Tags