1 /* 2 * Copyright (c) 2004, 2005, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 // EntityResolver2.java - Extended SAX entity resolver. 27 // http://www.saxproject.org 28 // No warranty; no copyright -- use this as you will. 29 // $Id: EntityResolver2.java,v 1.2 2004/11/03 22:49:08 jsuttor Exp $ 30 31 package org.xml.sax.ext; 32 33 import java.io.IOException; 34 35 import org.xml.sax.EntityResolver; 36 import org.xml.sax.InputSource; 37 import org.xml.sax.XMLReader; 38 import org.xml.sax.SAXException; 39 40 41 /** 42 * Extended interface for mapping external entity references to input 43 * sources, or providing a missing external subset. The 44 * {@link XMLReader#setEntityResolver XMLReader.setEntityResolver()} method 45 * is used to provide implementations of this interface to parsers. 46 * When a parser uses the methods in this interface, the 47 * {@link EntityResolver2#resolveEntity EntityResolver2.resolveEntity()} 48 * method (in this interface) is used <em>instead of</em> the older (SAX 1.0) 49 * {@link EntityResolver#resolveEntity EntityResolver.resolveEntity()} method. 50 * 51 * <blockquote> 52 * <em>This module, both source code and documentation, is in the 53 * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em> 54 * </blockquote> 55 * 56 * <p>If a SAX application requires the customized handling which this 57 * interface defines for external entities, it must ensure that it uses 58 * an XMLReader with the 59 * <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag 60 * set to <em>true</em> (which is its default value when the feature is 61 * recognized). If that flag is unrecognized, or its value is false, 62 * or the resolver does not implement this interface, then only the 63 * {@link EntityResolver} method will be used. 64 * </p> 65 * 66 * <p>That supports three categories of application that modify entity 67 * resolution. <em>Old Style</em> applications won't know about this interface; 68 * they will provide an EntityResolver. 69 * <em>Transitional Mode</em> provide an EntityResolver2 and automatically 70 * get the benefit of its methods in any systems (parsers or other tools) 71 * supporting it, due to polymorphism. 72 * Both <em>Old Style</em> and <em>Transitional Mode</em> applications will 73 * work with any SAX2 parser. 74 * <em>New style</em> applications will fail to run except on SAX2 parsers 75 * that support this particular feature. 76 * They will insist that feature flag have a value of "true", and the 77 * EntityResolver2 implementation they provide might throw an exception 78 * if the original SAX 1.0 style entity resolution method is invoked. 79 * </p> 80 * 81 * @see org.xml.sax.XMLReader#setEntityResolver 82 * 83 * @since SAX 2.0 (extensions 1.1 alpha) 84 * @author David Brownell 85 */ 86 public interface EntityResolver2 extends EntityResolver 87 { 88 /** 89 * Allows applications to provide an external subset for documents 90 * that don't explicitly define one. Documents with DOCTYPE declarations 91 * that omit an external subset can thus augment the declarations 92 * available for validation, entity processing, and attribute processing 93 * (normalization, defaulting, and reporting types including ID). 94 * This augmentation is reported 95 * through the {@link LexicalHandler#startDTD startDTD()} method as if 96 * the document text had originally included the external subset; 97 * this callback is made before any internal subset data or errors 98 * are reported.</p> 99 * 100 * <p>This method can also be used with documents that have no DOCTYPE 101 * declaration. When the root element is encountered, 102 * but no DOCTYPE declaration has been seen, this method is 103 * invoked. If it returns a value for the external subset, that root 104 * element is declared to be the root element, giving the effect of 105 * splicing a DOCTYPE declaration at the end the prolog of a document 106 * that could not otherwise be valid. The sequence of parser callbacks 107 * in that case logically resembles this:</p> 108 * 109 * <pre> 110 * ... comments and PIs from the prolog (as usual) 111 * startDTD ("rootName", source.getPublicId (), source.getSystemId ()); 112 * startEntity ("[dtd]"); 113 * ... declarations, comments, and PIs from the external subset 114 * endEntity ("[dtd]"); 115 * endDTD (); 116 * ... then the rest of the document (as usual) 117 * startElement (..., "rootName", ...); 118 * </pre> 119 * 120 * <p>Note that the InputSource gets no further resolution. 121 * Implementations of this method may wish to invoke 122 * {@link #resolveEntity resolveEntity()} to gain benefits such as use 123 * of local caches of DTD entities. Also, this method will never be 124 * used by a (non-validating) processor that is not including external 125 * parameter entities. </p> 126 * 127 * <p>Uses for this method include facilitating data validation when 128 * interoperating with XML processors that would always require 129 * undesirable network accesses for external entities, or which for 130 * other reasons adopt a "no DTDs" policy. 131 * Non-validation motives include forcing documents to include DTDs so 132 * that attributes are handled consistently. 133 * For example, an XPath processor needs to know which attibutes have 134 * type "ID" before it can process a widely used type of reference.</p> 135 * 136 * <p><strong>Warning:</strong> Returning an external subset modifies 137 * the input document. By providing definitions for general entities, 138 * it can make a malformed document appear to be well formed. 139 * </p> 140 * 141 * @param name Identifies the document root element. This name comes 142 * from a DOCTYPE declaration (where available) or from the actual 143 * root element. 144 * @param baseURI The document's base URI, serving as an additional 145 * hint for selecting the external subset. This is always an absolute 146 * URI, unless it is null because the XMLReader was given an InputSource 147 * without one. 148 * 149 * @return An InputSource object describing the new external subset 150 * to be used by the parser, or null to indicate that no external 151 * subset is provided. 152 * 153 * @exception SAXException Any SAX exception, possibly wrapping 154 * another exception. 155 * @exception IOException Probably indicating a failure to create 156 * a new InputStream or Reader, or an illegal URL. 157 */ getExternalSubset(String name, String baseURI)158 public InputSource getExternalSubset (String name, String baseURI) 159 throws SAXException, IOException; 160 161 /** 162 * Allows applications to map references to external entities into input 163 * sources, or tell the parser it should use conventional URI resolution. 164 * This method is only called for external entities which have been 165 * properly declared. 166 * This method provides more flexibility than the {@link EntityResolver} 167 * interface, supporting implementations of more complex catalogue 168 * schemes such as the one defined by the <a href= 169 "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html" 170 >OASIS XML Catalogs</a> specification.</p> 171 * 172 * <p>Parsers configured to use this resolver method will call it 173 * to determine the input source to use for any external entity 174 * being included because of a reference in the XML text. 175 * That excludes the document entity, and any external entity returned 176 * by {@link #getExternalSubset getExternalSubset()}. 177 * When a (non-validating) processor is configured not to include 178 * a class of entities (parameter or general) through use of feature 179 * flags, this method is not invoked for such entities. </p> 180 * 181 * <p>Note that the entity naming scheme used here is the same one 182 * used in the {@link LexicalHandler}, or in the {@link 183 org.xml.sax.ContentHandler#skippedEntity 184 ContentHandler.skippedEntity()} 185 * method. </p> 186 * 187 * @param name Identifies the external entity being resolved. 188 * Either "[dtd]" for the external subset, or a name starting 189 * with "%" to indicate a parameter entity, or else the name of 190 * a general entity. This is never null when invoked by a SAX2 191 * parser. 192 * @param publicId The public identifier of the external entity being 193 * referenced (normalized as required by the XML specification), or 194 * null if none was supplied. 195 * @param baseURI The URI with respect to which relative systemIDs 196 * are interpreted. This is always an absolute URI, unless it is 197 * null (likely because the XMLReader was given an InputSource without 198 * one). This URI is defined by the XML specification to be the one 199 * associated with the "<" starting the relevant declaration. 200 * @param systemId The system identifier of the external entity 201 * being referenced; either a relative or absolute URI. 202 * This is never null when invoked by a SAX2 parser; only declared 203 * entities, and any external subset, are resolved by such parsers. 204 * 205 * @return An InputSource object describing the new input source to 206 * be used by the parser. Returning null directs the parser to 207 * resolve the system ID against the base URI and open a connection 208 * to resulting URI. 209 * 210 * @exception SAXException Any SAX exception, possibly wrapping 211 * another exception. 212 * @exception IOException Probably indicating a failure to create 213 * a new InputStream or Reader, or an illegal URL. 214 */ resolveEntity( String name, String publicId, String baseURI, String systemId )215 public InputSource resolveEntity ( 216 String name, 217 String publicId, 218 String baseURI, 219 String systemId 220 ) throws SAXException, IOException; 221 } 222