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