content: /*
   * Copyright (c) 2004, 2005, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  // EntityResolver2.java - Extended SAX entity resolver.
  // http://www.saxproject.org
  // No warranty; no copyright -- use this as you will.
  // $Id: EntityResolver2.java,v 1.2 2004/11/03 22:49:08 jsuttor Exp $
  
  package org.xml.sax.ext;
  
  import java.io.IOException;
  
  import org.xml.sax.EntityResolver;
  import org.xml.sax.InputSource;
  import org.xml.sax.XMLReader;
  import org.xml.sax.SAXException;
  
  
  /**
   * Extended interface for mapping external entity references to input
   * sources, or providing a missing external subset.  The
   * {@link XMLReader#setEntityResolver XMLReader.setEntityResolver()} method
   * is used to provide implementations of this interface to parsers.
   * When a parser uses the methods in this interface, the
   * {@link EntityResolver2#resolveEntity EntityResolver2.resolveEntity()}
   * method (in this interface) is used <em>instead of</em> the older (SAX 1.0)
   * {@link EntityResolver#resolveEntity EntityResolver.resolveEntity()} method.
   *
   * <blockquote>
   * <em>This module, both source code and documentation, is in the
   * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
   * </blockquote>
   *
   * <p>If a SAX application requires the customized handling which this
   * interface defines for external entities, it must ensure that it uses
   * an XMLReader with the
   * <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
   * set to <em>true</em> (which is its default value when the feature is
   * recognized).  If that flag is unrecognized, or its value is false,
   * or the resolver does not implement this interface, then only the
   * {@link EntityResolver} method will be used.
   * </p>
   *
   * <p>That supports three categories of application that modify entity
   * resolution.  <em>Old Style</em> applications won't know about this interface;
   * they will provide an EntityResolver.
   * <em>Transitional Mode</em> provide an EntityResolver2 and automatically
   * get the benefit of its methods in any systems (parsers or other tools)
   * supporting it, due to polymorphism.
   * Both <em>Old Style</em> and <em>Transitional Mode</em> applications will
   * work with any SAX2 parser.
   * <em>New style</em> applications will fail to run except on SAX2 parsers
   * that support this particular feature.
   * They will insist that feature flag have a value of "true", and the
   * EntityResolver2 implementation they provide  might throw an exception
   * if the original SAX 1.0 style entity resolution method is invoked.
   * </p>
   *
   * @see org.xml.sax.XMLReader#setEntityResolver
   *
   * @since SAX 2.0 (extensions 1.1 alpha)
   * @author David Brownell
   */
  public interface EntityResolver2 extends EntityResolver
  {
      /**
       * Allows applications to provide an external subset for documents
       * that don't explicitly define one.  Documents with DOCTYPE declarations
       * that omit an external subset can thus augment the declarations
       * available for validation, entity processing, and attribute processing
       * (normalization, defaulting, and reporting types including ID).
       * This augmentation is reported
       * through the {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD()} method as if
       * the document text had originally included the external subset;
       * this callback is made before any internal subset data or errors
       * are reported.</p>
       *
       * <p>This method can also be used with documents that have no DOCTYPE
       * declaration.  When the root element is encountered,
       * but no DOCTYPE declaration has been seen, this method is
       * invoked.  If it returns a value for the external subset, that root
       * element is declared to be the root element, giving the effect of
       * splicing a DOCTYPE declaration at the end the prolog of a document
       * that could not otherwise be valid.  The sequence of parser callbacks
       * in that case logically resembles this:</p>
       *
       * <pre>
       * ... comments and PIs from the prolog (as usual)
       * startDTD ("rootName", source.getPublicId (), source.getSystemId ());
       * startEntity ("[dtd]");
       * ... declarations, comments, and PIs from the external subset
       * endEntity ("[dtd]");
       * endDTD ();
       * ... then the rest of the document (as usual)
       * startElement (..., "rootName", ...);
       * </pre>
       *
       * <p>Note that the InputSource gets no further resolution.
       * Implementations of this method may wish to invoke
       * {@link #resolveEntity resolveEntity()} to gain benefits such as use
       * of local caches of DTD entities.  Also, this method will never be
       * used by a (non-validating) processor that is not including external
       * parameter entities. </p>
       *
       * <p>Uses for this method include facilitating data validation when
       * interoperating with XML processors that would always require
       * undesirable network accesses for external entities, or which for
       * other reasons adopt a "no DTDs" policy.
       * Non-validation motives include forcing documents to include DTDs so
       * that attributes are handled consistently.
       * For example, an XPath processor needs to know which attibutes have
       * type "ID" before it can process a widely used type of reference.</p>
       *
       * <p><strong>Warning:</strong> Returning an external subset modifies
       * the input document.  By providing definitions for general entities,
       * it can make a malformed document appear to be well formed.
       * </p>
       *
       * @param name Identifies the document root element.  This name comes
       *  from a DOCTYPE declaration (where available) or from the actual
       *  root element.
       * @param baseURI The document's base URI, serving as an additional
       *  hint for selecting the external subset.  This is always an absolute
       *  URI, unless it is null because the XMLReader was given an InputSource
       *  without one.
       *
       * @return An InputSource object describing the new external subset
       *  to be used by the parser, or null to indicate that no external
       *  subset is provided.
       *
       * @exception SAXException Any SAX exception, possibly wrapping
       *  another exception.
       * @exception IOException Probably indicating a failure to create
       *  a new InputStream or Reader, or an illegal URL.
       */
      public InputSource getExternalSubset (String name, String baseURI)
      throws SAXException, IOException;
  
      /**
       * Allows applications to map references to external entities into input
       * sources, or tell the parser it should use conventional URI resolution.
       * This method is only called for external entities which have been
       * properly declared.
       * This method provides more flexibility than the {@link EntityResolver}
       * interface, supporting implementations of more complex catalogue
       * schemes such as the one defined by the <a href=
          "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
          >OASIS XML Catalogs</a> specification.</p>
       *
       * <p>Parsers configured to use this resolver method will call it
       * to determine the input source to use for any external entity
       * being included because of a reference in the XML text.
       * That excludes the document entity, and any external entity returned
       * by {@link #getExternalSubset getExternalSubset()}.
       * When a (non-validating) processor is configured not to include
       * a class of entities (parameter or general) through use of feature
       * flags, this method is not invoked for such entities.  </p>
       *
       * <p>Note that the entity naming scheme used here is the same one
       * used in the {@link LexicalHandler}, or in the {@link
          org.xml.sax.ContentHandler#skippedEntity
          ContentHandler.skippedEntity()}
       * method. </p>
       *
       * @param name Identifies the external entity being resolved.
       *  Either "[dtd]" for the external subset, or a name starting
       *  with "%" to indicate a parameter entity, or else the name of
       *  a general entity.  This is never null when invoked by a SAX2
       *  parser.
       * @param publicId The public identifier of the external entity being
       *  referenced (normalized as required by the XML specification), or
       *  null if none was supplied.
       * @param baseURI The URI with respect to which relative systemIDs
       *  are interpreted.  This is always an absolute URI, unless it is
       *  null (likely because the XMLReader was given an InputSource without
       *  one).  This URI is defined by the XML specification to be the one
       *  associated with the "&lt;" starting the relevant declaration.
       * @param systemId The system identifier of the external entity
       *  being referenced; either a relative or absolute URI.
       *  This is never null when invoked by a SAX2 parser; only declared
       *  entities, and any external subset, are resolved by such parsers.
       *
       * @return An InputSource object describing the new input source to
       *  be used by the parser.  Returning null directs the parser to
       *  resolve the system ID against the base URI and open a connection
       *  to resulting URI.
       *
       * @exception SAXException Any SAX exception, possibly wrapping
       *  another exception.
       * @exception IOException Probably indicating a failure to create
       *  a new InputStream or Reader, or an illegal URL.
       */
      public InputSource resolveEntity (
              String name,
              String publicId,
              String baseURI,
              String systemId
      ) throws SAXException, IOException;
  }
  