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.1.2.1 2004/05/01 08:34:43 jsuttor 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 }
198
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags