01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * 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 org.apache.cocoon.components.validation;
18:
19: import org.apache.excalibur.source.SourceValidity;
20: import org.xml.sax.ErrorHandler;
21: import org.xml.sax.SAXException;
22:
23: /**
24: * <p>The {@link Schema} interface defines an abstraction of a schema usable to
25: * validate an XML document.</p>
26: *
27: * <p>This interface is not tied to any specific validation grammar language
28: * such as the <a href="http://www.w3.org/XML/Schema">W3C XML Shema</a> language
29: * or the <a href="http://www.relaxng.org/">RELAX-NG</a/> language.</p>
30: *
31: * <p>Selection and use of specific schema grammar languages is performed through
32: * the use of the {@link Validator} interface.</p>
33: *
34: * <p>Once returned by the {@link SchemaParser}, a {@link Schema} instance must be
35: * able to validate a number of XML documents: each time a document needs to be
36: * validated, a new {@link ValidationHandler} can be obtained invoking the
37: * {@link #createValidator(ErrorHandler)} method. While validating an XML document,
38: * {@link SAXException}s should be thrown back to the caller only when the specified
39: * {@link ErrorHandler} is configured to do so.</p>
40: *
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 handler)
74: throws SAXException;
75:
76: }
|