1 /*
2 * Copyright (c) 2004, 2019, 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
120 * that attributes are handled consistently.
121 * For example, an XPath processor needs to know which attibutes have
122 * type "ID" before it can process a widely used type of reference.
123 *
124 * <p><strong>Warning:</strong> Returning an external subset modifies
125 * the input document. By providing definitions for general entities,
126 * it can make a malformed document appear to be well formed.
127 *
128 * @param name Identifies the document root element. This name comes
129 * from a DOCTYPE declaration (where available) or from the actual
130 * root element.
131 * @param baseURI The document's base URI, serving as an additional
132 * hint for selecting the external subset. This is always an absolute
133 * URI, unless it is null because the XMLReader was given an InputSource
134 * without one.
135 *
136 * @return An InputSource object describing the new external subset
137 * to be used by the parser, or null to indicate that no external
138 * subset is provided.
139 *
140 * @exception SAXException Any SAX exception, possibly wrapping
141 * another exception.
142 * @exception IOException Probably indicating a failure to create
143 * a new InputStream or Reader, or an illegal URL.
144 */
145 public InputSource getExternalSubset (String name, String baseURI)
146 throws SAXException, IOException;
147
148 /**
149 * Allows applications to map references to external entities into input
150 * sources, or tell the parser it should use conventional URI resolution.
151 * This method is only called for external entities which have been
152 * properly declared.
153 * This method provides more flexibility than the {@link EntityResolver}
154 * interface, supporting implementations of more complex catalogue
155 * schemes such as the one defined by the <a href=
156 * "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
157 * >OASIS XML Catalogs</a> specification.
158 *
159 * <p>Parsers configured to use this resolver method will call it
160 * to determine the input source to use for any external entity
161 * being included because of a reference in the XML text.
162 * That excludes the document entity, and any external entity returned
177 * a general entity. This is never null when invoked by a SAX2
178 * parser.
179 * @param publicId The public identifier of the external entity being
180 * referenced (normalized as required by the XML specification), or
181 * null if none was supplied.
182 * @param baseURI The URI with respect to which relative systemIDs
183 * are interpreted. This is always an absolute URI, unless it is
184 * null (likely because the XMLReader was given an InputSource without
185 * one). This URI is defined by the XML specification to be the one
186 * associated with the "{@literal <}" starting the relevant declaration.
187 * @param systemId The system identifier of the external entity
188 * being referenced; either a relative or absolute URI.
189 * This is never null when invoked by a SAX2 parser; only declared
190 * entities, and any external subset, are resolved by such parsers.
191 *
192 * @return An InputSource object describing the new input source to
193 * be used by the parser. Returning null directs the parser to
194 * resolve the system ID against the base URI and open a connection
195 * to resulting URI.
196 *
197 * @exception SAXException Any SAX exception, possibly wrapping
198 * another exception.
199 * @exception IOException Probably indicating a failure to create
200 * a new InputStream or Reader, or an illegal URL.
201 */
202 public InputSource resolveEntity (
203 String name,
204 String publicId,
205 String baseURI,
206 String systemId
207 ) throws SAXException, IOException;
208 }
|
1 /*
2 * Copyright (c) 2004, 2020, 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
120 * that attributes are handled consistently.
121 * For example, an XPath processor needs to know which attibutes have
122 * type "ID" before it can process a widely used type of reference.
123 *
124 * <p><strong>Warning:</strong> Returning an external subset modifies
125 * the input document. By providing definitions for general entities,
126 * it can make a malformed document appear to be well formed.
127 *
128 * @param name Identifies the document root element. This name comes
129 * from a DOCTYPE declaration (where available) or from the actual
130 * root element.
131 * @param baseURI The document's base URI, serving as an additional
132 * hint for selecting the external subset. This is always an absolute
133 * URI, unless it is null because the XMLReader was given an InputSource
134 * without one.
135 *
136 * @return An InputSource object describing the new external subset
137 * to be used by the parser, or null to indicate that no external
138 * subset is provided.
139 *
140 * @throws SAXException Any SAX exception, possibly wrapping
141 * another exception.
142 * @throws IOException Probably indicating a failure to create
143 * a new InputStream or Reader, or an illegal URL.
144 */
145 public InputSource getExternalSubset (String name, String baseURI)
146 throws SAXException, IOException;
147
148 /**
149 * Allows applications to map references to external entities into input
150 * sources, or tell the parser it should use conventional URI resolution.
151 * This method is only called for external entities which have been
152 * properly declared.
153 * This method provides more flexibility than the {@link EntityResolver}
154 * interface, supporting implementations of more complex catalogue
155 * schemes such as the one defined by the <a href=
156 * "http://www.oasis-open.org/committees/entity/spec-2001-08-06.html"
157 * >OASIS XML Catalogs</a> specification.
158 *
159 * <p>Parsers configured to use this resolver method will call it
160 * to determine the input source to use for any external entity
161 * being included because of a reference in the XML text.
162 * That excludes the document entity, and any external entity returned
177 * a general entity. This is never null when invoked by a SAX2
178 * parser.
179 * @param publicId The public identifier of the external entity being
180 * referenced (normalized as required by the XML specification), or
181 * null if none was supplied.
182 * @param baseURI The URI with respect to which relative systemIDs
183 * are interpreted. This is always an absolute URI, unless it is
184 * null (likely because the XMLReader was given an InputSource without
185 * one). This URI is defined by the XML specification to be the one
186 * associated with the "{@literal <}" starting the relevant declaration.
187 * @param systemId The system identifier of the external entity
188 * being referenced; either a relative or absolute URI.
189 * This is never null when invoked by a SAX2 parser; only declared
190 * entities, and any external subset, are resolved by such parsers.
191 *
192 * @return An InputSource object describing the new input source to
193 * be used by the parser. Returning null directs the parser to
194 * resolve the system ID against the base URI and open a connection
195 * to resulting URI.
196 *
197 * @throws SAXException Any SAX exception, possibly wrapping
198 * another exception.
199 * @throws IOException Probably indicating a failure to create
200 * a new InputStream or Reader, or an illegal URL.
201 */
202 public InputSource resolveEntity (
203 String name,
204 String publicId,
205 String baseURI,
206 String systemId
207 ) throws SAXException, IOException;
208 }
|