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