1 |
768 |
jeremybenn |
// 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 |
|
|
}
|