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