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