Validator.java example

Explorer
cocoon-master
- cocoon-BRANCH_2_1_X
  - src
  - tools
    - src
      - anttasks
        DocumentCache.java
        ManifestToolTask.java
        PoolSetterTask.java
        SitemapTask.java
        XConfToolTask.java
      - loader
        Loader.java
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.cocoon.components.validation;

import java.io.IOException;

import org.apache.excalibur.source.Source;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;

/**
 * <p>The {@link Validator} interface provides the abstraction of a component able
 * to validate XML documents using schemas defined in different languages.</p>
 * 
 * <p>This is basically the main entry point of the validation API, allowing users
 * to transparently access validators (in the form of {@link ValidationHandler}s
 * receiving SAX events for the documents to be validated), in different grammar
 * languages, using different implementations.</p>
 * 
 * <p>As more than one {@link SchemaParser} might be able to parse and create
 * {@link Schema} instances for a particular grammar language, this interface
 * defines a unique lookup method to allow selection of a particular
 * {@link SchemaParser} implementation.</p>
 * 
 * <p>Assuming that two different {@link SchemaParser}s called <code>first</code>
 * and <code>second</code> are both able to understand the
 * {@link #GRAMMAR_RELAX_NG RELAX NG} grammar (identified by the
 * <code>http://relaxng.org/ns/structure/1.0</code> identifier) one could select
 * between the two implementation using the following two strings:</p>
 * 
 * <ul>
 *   <li><code>first:http://relaxng.org/ns/structure/1.0</code></li>
 *   <li><code>second:http://relaxng.org/ns/structure/1.0</code></li>
 * </ul>
 * 
 * <p>As a rule (unless when this is impossible) the grammar identifier is
 * equivalent to the namespace of the root element of a schema.</p>
 *
 */
public interface Validator {

    /** <p>Avalon Role name of {@link Validator} components.</p> */
    public static final String ROLE = Validator.class.getName();

    /** <p>The <a href="http://www.schematron.com/">ISO Schematron</a/> grammar identifer.</p> */
    public static final String GRAMMAR_ISO_SCHEMATRON = "http://purl.oclc.org/dsdl/schematron";
    /** <p>The <a href="http://www.relaxng.org/">RELAX NG</a/> grammar identifer.</p> */
    public static final String GRAMMAR_RELAX_NG = "http://relaxng.org/ns/structure/1.0";
    /** <p>The <a href="http://www.xml.gr.jp/relax">RELAX Core</a/> grammar identifer.</p> */
    public static final String GRAMMAR_RELAX_CORE = "http://www.xml.gr.jp/xmlns/relaxCore";
    /** <p>The <a href="http://www.xml.gr.jp/relax">RELAX Namespace</a/> grammar identifer.</p> */
    public static final String GRAMMAR_RELAX_NS = "http://www.xml.gr.jp/xmlns/relaxNamespace";
    /** <p>The <a href="http://xml.ascc.net/schematron/">Schematron</a/> grammar identifer.</p> */
    public static final String GRAMMAR_SCHEMATRON = "http://www.ascc.net/xml/schematron";
    /** <p>The <a href="http://www.thaiopensource.com/trex/">Trex</a/> grammar identifer.</p> */
    public static final String GRAMMAR_TREX = "http://www.thaiopensource.com/trex";
    /** <p>The <a href="http://www.w3.org/XML/Schema">XML Schema</a/> grammar identifer.</p> */
    public static final String GRAMMAR_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema";
    /** <p>The <a href="http://www.w3.org/TR/REC-xml">XML DTD</a/> grammar identifer.</p> */
    public static final String GRAMMAR_XML_DTD = "http://www.w3.org/TR/REC-xml";

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>The {@link Validator} will attempt to automatically detect the grammar
     * language of the specified schema, and each error or warning occurring while
     * validating the document will trigger a {@link SAXException} to be thrown back
     * to the caller.</p> 
     *
     * @param uri the location of the schema to use to validate the document.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the grammar language of the specified schema
     *                            could not be detected or was not supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(String uri)
    throws IOException, SAXException, ValidatorException;

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>Each error or warning occurring while validating the document will trigger
     * a {@link SAXException} to be thrown back to the caller.</p> 
     *
     * @param uri the location of the schema to use to validate the document.
     * @param grammar the grammar language of the schema to parse.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the specified grammar language wasn't supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(String uri, String grammar)
    throws IOException, SAXException, ValidatorException;

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>The {@link Validator} will attempt to automatically detect the grammar
     * language of the specified schema, while each validation error or warning will
     * be passed to the specified {@link ErrorHandler} which will have the ability
     * to generate and throw a {@link SAXException} back to the caller.</p>
     *
     * @param uri the location of the schema to use to validate the document.
     * @param errorHandler the {@link ErrorHandler} notified of validation problems.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the grammar language of the specified schema
     *                            could not be detected or was not supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(String uri, ErrorHandler errorHandler)
    throws IOException, SAXException, ValidatorException;

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>Each validation error or warning will be passed to the specified
     * {@link ErrorHandler} which will have the ability to generate and throw a
     * {@link SAXException} back to the caller.</p>
     *
     * @param uri the location of the schema to use to validate the document.
     * @param grammar the grammar language of the schema to parse.
     * @param errorHandler the {@link ErrorHandler} notified of validation problems.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the specified grammar language wasn't supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(String uri, String grammar,
                                               ErrorHandler errorHandler)
    throws IOException, SAXException, ValidatorException;

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>The {@link Validator} will attempt to automatically detect the grammar
     * language of the specified schema, and each error or warning occurring while
     * validating the document will trigger a {@link SAXException} to be thrown back
     * to the caller.</p> 
     *
     * @param source the {@link Source} identifying the schema to use for validation.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the grammar language of the specified schema
     *                            could not be detected or was not supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(Source source)
    throws IOException, SAXException, ValidatorException;

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>Each error or warning occurring while validating the document will trigger
     * a {@link SAXException} to be thrown back to the caller.</p> 
     *
     * @param source the {@link Source} identifying the schema to use for validation.
     * @param grammar the grammar language of the schema to parse.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the specified grammar language wasn't supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(Source source, String grammar)
    throws IOException, SAXException, ValidatorException;

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>The {@link Validator} will attempt to automatically detect the grammar
     * language of the specified schema, while each validation error or warning will
     * be passed to the specified {@link ErrorHandler} which will have the ability
     * to generate and throw a {@link SAXException} back to the caller.</p>
     *
     * @param source the {@link Source} identifying the schema to use for validation.
     * @param errorHandler the {@link ErrorHandler} notified of validation problems.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the grammar language of the specified schema
     *                            could not be detected or was not supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(Source source,
                                                  ErrorHandler errorHandler)
    throws IOException, SAXException, ValidatorException;

    /**
     * <p>Return a {@link ValidationHandler} validating an XML document according to
     * the schema found at the specified location.</p>
     *
     * <p>Each validation error or warning will be passed to the specified
     * {@link ErrorHandler} which will have the ability to generate and throw a
     * {@link SAXException} back to the caller.</p>
     *
     * @param source the {@link Source} identifying the schema to use for validation.
     * @param grammar the grammar language of the schema to parse.
     * @param errorHandler the {@link ErrorHandler} notified of validation problems.
     * @return a <b>non null</b> {@link ValidationHandler} able to SAX events from
     *         the original XML document to validate.
     * @throws IOException if an I/O error occurred parsing the schema.
     * @throws SAXException if a grammar error occurred parsing the schema.
     * @throws ValidatorException if the specified grammar language wasn't supported.
     * @see SchemaParser#parseSchema(Source, String)
     * @see Schema#createValidator(ErrorHandler)
     */
    public ValidationHandler getValidationHandler(Source source, String grammar,
                                               ErrorHandler errorHandler)
    throws IOException, SAXException, ValidatorException;

}