001: // EntityResolver2.java - Extended SAX entity resolver.
002: // http://www.saxproject.org
003: // No warranty; no copyright -- use this as you will.
004: // $Id: EntityResolver2.java,v 1.3 2002/02/01 20:06:20 db Exp $
005:
006: package org.xml.sax.ext;
007:
008: import java.io.IOException;
009:
010: import org.xml.sax.EntityResolver;
011: import org.xml.sax.InputSource;
012: import org.xml.sax.XMLReader;
013: import org.xml.sax.SAXException;
014:
015: /**
016: * Extended interface for mapping external entity references to input
017: * sources, or providing a missing external subset. The
018: * {@link XMLReader#setEntityResolver XMLReader.setEntityResolver()} method
019: * is used to provide implementations of this interface to parsers.
020: * When a parser uses the methods in this interface, the
021: * {@link EntityResolver2#resolveEntity EntityResolver2.resolveEntity()}
022: * method (in this interface) is used <em>instead of</em> the older (SAX 1.0)
023: * {@link EntityResolver#resolveEntity EntityResolver.resolveEntity()} method.
024: *
025: * <blockquote>
026: * <em>This module, both source code and documentation, is in the
027: * Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
028: * </blockquote>
029: *
030: * <p>If a SAX application requires the customized handling which this
031: * interface defines for external entities, it must ensure that it uses
032: * an XMLReader with the
033: * <em>http://xml.org/sax/features/use-entity-resolver2</em> feature flag
034: * set to <em>true</em> (which is its default value when the feature is
035: * recognized). If that flag is unrecognized, or its value is false,
036: * or the resolver does not implement this interface, then only the
037: * {@link EntityResolver} method will be used.
038: * </p>
039: *
040: * <p>That supports three categories of application that modify entity
041: * resolution. <em>Old Style</em> applications won't know about this interface;
042: * they will provide an EntityResolver.
043: * <em>Transitional Mode</em> provide an EntityResolver2 and automatically
044: * get the benefit of its methods in any systems (parsers or other tools)
045: * supporting it, due to polymorphism.
046: * Both <em>Old Style</em> and <em>Transitional Mode</em> applications will
047: * work with any SAX2 parser.
048: * <em>New style</em> applications will fail to run except on SAX2 parsers
049: * that support this particular feature.
050: * They will insist that feature flag have a value of "true", and the
051: * EntityResolver2 implementation they provide might throw an exception
052: * if the original SAX 1.0 style entity resolution method is invoked.
053: * </p>
054: *
055: * @see org.xml.sax.XMLReader#setEntityResolver
056: *
057: * @since SAX 2.0 (extensions 1.1 alpha)
058: * @author David Brownell
059: * @version TBD
060: */
061: public interface EntityResolver2 extends EntityResolver {
062: /**
063: * Allows applications to provide an external subset for documents
064: * that don't explicitly define one. Documents with DOCTYPE declarations
065: * that omit an external subset can thus augment the declarations
066: * available for validation, entity processing, and attribute processing
067: * (normalization, defaulting, and reporting types including ID).
068: * This augmentation is reported
069: * through the {@link LexicalHandler#startDTD startDTD()} method as if
070: * the document text had originally included the external subset;
071: * this callback is made before any internal subset data or errors
072: * are reported.</p>
073: *
074: * <p>This method can also be used with documents that have no DOCTYPE
075: * declaration. When the root element is encountered,
076: * but no DOCTYPE declaration has been seen, this method is
077: * invoked. If it returns a value for the external subset, that root
078: * element is declared to be the root element, giving the effect of
079: * splicing a DOCTYPE declaration at the end the prolog of a document
080: * that could not otherwise be valid. The sequence of parser callbacks
081: * in that case logically resembles this:</p>
082: *
083: * <pre>
084: * ... comments and PIs from the prolog (as usual)
085: * startDTD ("rootName", source.getPublicId (), source.getSystemId ());
086: * startEntity ("[dtd]");
087: * ... declarations, comments, and PIs from the external subset
088: * endEntity ("[dtd]");
089: * endDTD ();
090: * ... then the rest of the document (as usual)
091: * startElement (..., "rootName", ...);
092: * </pre>
093: *
094: * <p>Note that the InputSource gets no further resolution.
095: * Implementations of this method may wish to invoke
096: * {@link #resolveEntity resolveEntity()} to gain benefits such as use
097: * of local caches of DTD entities. Also, this method will never be
098: * used by a (non-validating) processor that is not including external
099: * parameter entities. </p>
100: *
101: * <p>Uses for this method include facilitating data validation when
102: * interoperating with XML processors that would always require
103: * undesirable network accesses for external entities, or which for
104: * other reasons adopt a "no DTDs" policy.
105: * Non-validation motives include forcing documents to include DTDs so
106: * that attributes are handled consistently.
107: * For example, an XPath processor needs to know which attibutes have
108: * type "ID" before it can process a widely used type of reference.</p>
109: *
110: * <p><strong>Warning:</strong> Returning an external subset modifies
111: * the input document. By providing definitions for general entities,
112: * it can make a malformed document appear to be well formed.
113: * </p>
114: *
115: * @param name Identifies the document root element. This name comes
116: * from a DOCTYPE declaration (where available) or from the actual
117: * root element.
118: * @param baseURI The document's base URI, serving as an additional
119: * hint for selecting the external subset. This is always an absolute
120: * URI, unless it is null because the XMLReader was given an InputSource
121: * without one.
122: *
123: * @return An InputSource object describing the new external subset
124: * to be used by the parser, or null to indicate that no external
125: * subset is provided.
126: *
127: * @exception SAXException Any SAX exception, possibly wrapping
128: * another exception.
129: * @exception IOException Probably indicating a failure to create
130: * a new InputStream or Reader, or an illegal URL.
131: */
132: public InputSource getExternalSubset(String name, String baseURI)
133: throws SAXException, IOException;
134:
135: /**
136: * Allows applications to map references to external entities into input
137: * sources, or tell the parser it should use conventional URI resolution.
138: * This method is only called for external entities which have been
139: * properly declared.
140: * This method provides more flexibility than the {@link EntityResolver}
141: * interface, supporting implementations of more complex catalogue
142: * schemes such as the one defined by the <a href=
143: "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
144: >OASIS XML Catalogs</a> specification.</p>
145: *
146: * <p>Parsers configured to use this resolver method will call it
147: * to determine the input source to use for any external entity
148: * being included because of a reference in the XML text.
149: * That excludes the document entity, and any external entity returned
150: * by {@link #getExternalSubset getExternalSubset()}.
151: * When a (non-validating) processor is configured not to include
152: * a class of entities (parameter or general) through use of feature
153: * flags, this method is not invoked for such entities. </p>
154: *
155: * <p>Note that the entity naming scheme used here is the same one
156: * used in the {@link LexicalHandler}, or in the {@link
157: org.xml.sax.ContentHandler#skippedEntity
158: ContentHandler.skippedEntity()}
159: * method. </p>
160: *
161: * @param name Identifies the external entity being resolved.
162: * Either "[dtd]" for the external subset, or a name starting
163: * with "%" to indicate a parameter entity, or else the name of
164: * a general entity. This is never null when invoked by a SAX2
165: * parser.
166: * @param publicId The public identifier of the external entity being
167: * referenced (normalized as required by the XML specification), or
168: * null if none was supplied.
169: * @param baseURI The URI with respect to which relative systemIDs
170: * are interpreted. This is always an absolute URI, unless it is
171: * null (likely because the XMLReader was given an InputSource without
172: * one). This URI is defined by the XML specification to be the one
173: * associated with the "<" starting the relevant declaration.
174: * @param systemId The system identifier of the external entity
175: * being referenced; either a relative or absolute URI.
176: * This is never null when invoked by a SAX2 parser; only declared
177: * entities, and any external subset, are resolved by such parsers.
178: *
179: * @return An InputSource object describing the new input source to
180: * be used by the parser. Returning null directs the parser to
181: * resolve the system ID against the base URI and open a connection
182: * to resulting URI.
183: *
184: * @exception SAXException Any SAX exception, possibly wrapping
185: * another exception.
186: * @exception IOException Probably indicating a failure to create
187: * a new InputStream or Reader, or an illegal URL.
188: */
189: public InputSource resolveEntity(String name, String publicId,
190: String baseURI, String systemId) throws SAXException,
191: IOException;
192: }
|