Source for org.xml.sax.ext.EntityResolver2

   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 "&lt;" 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: }