/*
 *                 Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 *
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2003 Sun
 * Microsystems, Inc. All Rights Reserved.
 */
package org.netbeans.api.xml.parsers;  //TMP

import org.xml.sax.InputSource;

/**
 * XML processor callback interface that allows it to dynamically locate
 * XML schemas using logic provided by a client application. It
 * resembles the <code>org.xml.sax.EntityResolver</code> pattern.
 * <p>
 * SchemaResolver instances are passed to aware XML processor in form of
 * <tt>http://xml.org/sax/properties/org.xml.sax.ext.SchemaResolver</tt> SAX property
 * or
 * <tt>http://java.sun.com/xml/jaxp/properties/javax.xml.parsers.XMLSchemaResolver</tt> JAXP property
 * or
 * a parser vendor specifics property. It depends on
 * parser and this interface standartization level.
 *
 * @author Petr Kuzel
 */
public interface SchemaResolver {

    /**
     * Provide XML parser with XML schema instance located using application
     * provided resolution mechanism. It is called when XML processor
     * need to locate XML Schema:
     * <ul>
     * <li>for instance documents,
     * <li>for the XML Schema xsd:import instruction and
     * <li>for the XML Schema xsd:include instruction.
     * </ul>
     *
     * @param namespace XML schema target namespace, <code>null</code> for
     *                  "chameleon" XML schemas.
     * @param location Location hint as used in referring document. It must be
     *                 passed as absolute URI (i.e. relative URLs resolved
     *                 to the referring document).
     * @return InputSource representing XML Schema or <code>null</code>
     *         if the implementation is not able to locate the schema.
     */
    public InputSource resolveSchema(String namespace, String location);
}