1 /*
2 * Copyright (c) 2000, 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
110 *
111 * // register event handlers
112 * r.setContentHandler(new MyContentHandler());
113 * r.setErrorHandler(new MyErrorHandler());
114 *
115 * // parse the first document
116 * try {
117 * r.parse("http://www.foo.com/mydoc.xml");
118 * } catch (IOException e) {
119 * System.err.println("I/O exception reading XML document");
120 * } catch (SAXException e) {
121 * System.err.println("XML exception reading document.");
122 * }
123 * </pre>
124 *
125 * <p>Implementors are free (and encouraged) to invent their own features,
126 * using names built on their own URIs.</p>
127 *
128 * @param name The feature name, which is a fully-qualified URI.
129 * @return The current value of the feature (true or false).
130 * @exception org.xml.sax.SAXNotRecognizedException If the feature
131 * value can't be assigned or retrieved.
132 * @exception org.xml.sax.SAXNotSupportedException When the
133 * XMLReader recognizes the feature name but
134 * cannot determine its value at this time.
135 * @see #setFeature
136 */
137 public boolean getFeature (String name)
138 throws SAXNotRecognizedException, SAXNotSupportedException;
139
140
141 /**
142 * Set the value of a feature flag.
143 *
144 * <p>The feature name is any fully-qualified URI. It is
145 * possible for an XMLReader to expose a feature value but
146 * to be unable to change the current value.
147 * Some feature values may be immutable or mutable only
148 * in specific contexts, such as before, during, or after
149 * a parse.</p>
150 *
151 * <p>All XMLReaders are required to support setting
152 * http://xml.org/sax/features/namespaces to true and
153 * http://xml.org/sax/features/namespace-prefixes to false.</p>
154 *
155 * @param name The feature name, which is a fully-qualified URI.
156 * @param value The requested value of the feature (true or false).
157 * @exception org.xml.sax.SAXNotRecognizedException If the feature
158 * value can't be assigned or retrieved.
159 * @exception org.xml.sax.SAXNotSupportedException When the
160 * XMLReader recognizes the feature name but
161 * cannot set the requested value.
162 * @see #getFeature
163 */
164 public void setFeature (String name, boolean value)
165 throws SAXNotRecognizedException, SAXNotSupportedException;
166
167
168 /**
169 * Look up the value of a property.
170 *
171 * <p>The property name is any fully-qualified URI. It is
172 * possible for an XMLReader to recognize a property name but
173 * temporarily be unable to return its value.
174 * Some property values may be available only in specific
175 * contexts, such as before, during, or after a parse.</p>
176 *
177 * <p>XMLReaders are not required to recognize any specific
178 * property names, though an initial core set is documented for
179 * SAX2.</p>
180 *
181 * <p>Implementors are free (and encouraged) to invent their own properties,
182 * using names built on their own URIs.</p>
183 *
184 * @param name The property name, which is a fully-qualified URI.
185 * @return The current value of the property.
186 * @exception org.xml.sax.SAXNotRecognizedException If the property
187 * value can't be assigned or retrieved.
188 * @exception org.xml.sax.SAXNotSupportedException When the
189 * XMLReader recognizes the property name but
190 * cannot determine its value at this time.
191 * @see #setProperty
192 */
193 public Object getProperty (String name)
194 throws SAXNotRecognizedException, SAXNotSupportedException;
195
196
197 /**
198 * Set the value of a property.
199 *
200 * <p>The property name is any fully-qualified URI. It is
201 * possible for an XMLReader to recognize a property name but
202 * to be unable to change the current value.
203 * Some property values may be immutable or mutable only
204 * in specific contexts, such as before, during, or after
205 * a parse.</p>
206 *
207 * <p>XMLReaders are not required to recognize setting
208 * any specific property names, though a core set is defined by
209 * SAX2.</p>
210 *
211 * <p>This method is also the standard mechanism for setting
212 * extended handlers.</p>
213 *
214 * @param name The property name, which is a fully-qualified URI.
215 * @param value The requested value for the property.
216 * @exception org.xml.sax.SAXNotRecognizedException If the property
217 * value can't be assigned or retrieved.
218 * @exception org.xml.sax.SAXNotSupportedException When the
219 * XMLReader recognizes the property name but
220 * cannot set the requested value.
221 */
222 public void setProperty (String name, Object value)
223 throws SAXNotRecognizedException, SAXNotSupportedException;
224
225
226
227 ////////////////////////////////////////////////////////////////////
228 // Event handlers.
229 ////////////////////////////////////////////////////////////////////
230
231
232 /**
233 * Allow an application to register an entity resolver.
234 *
235 * <p>If the application does not register an entity resolver,
236 * the XMLReader will perform its own default resolution.</p>
237 *
238 * <p>Applications may register a new or different resolver in the
355 * application may reuse the same XMLReader object, possibly with a
356 * different input source.
357 * Configuration of the XMLReader object (such as handler bindings and
358 * values established for feature flags and properties) is unchanged
359 * by completion of a parse, unless the definition of that aspect of
360 * the configuration explicitly specifies other behavior.
361 * (For example, feature flags or properties exposing
362 * characteristics of the document being parsed.)
363 * </p>
364 *
365 * <p>During the parse, the XMLReader will provide information
366 * about the XML document through the registered event
367 * handlers.</p>
368 *
369 * <p>This method is synchronous: it will not return until parsing
370 * has ended. If a client application wants to terminate
371 * parsing early, it should throw an exception.</p>
372 *
373 * @param input The input source for the top-level of the
374 * XML document.
375 * @exception org.xml.sax.SAXException Any SAX exception, possibly
376 * wrapping another exception.
377 * @exception java.io.IOException An IO exception from the parser,
378 * possibly from a byte stream or character stream
379 * supplied by the application.
380 * @see org.xml.sax.InputSource
381 * @see #parse(java.lang.String)
382 * @see #setEntityResolver
383 * @see #setDTDHandler
384 * @see #setContentHandler
385 * @see #setErrorHandler
386 */
387 public void parse (InputSource input)
388 throws IOException, SAXException;
389
390
391 /**
392 * Parse an XML document from a system identifier (URI).
393 *
394 * <p>This method is a shortcut for the common case of reading a
395 * document from a system identifier. It is the exact
396 * equivalent of the following:</p>
397 *
398 * <pre>
399 * parse(new InputSource(systemId));
400 * </pre>
401 *
402 * <p>If the system identifier is a URL, it must be fully resolved
403 * by the application before it is passed to the parser.</p>
404 *
405 * @param systemId The system identifier (URI).
406 * @exception org.xml.sax.SAXException Any SAX exception, possibly
407 * wrapping another exception.
408 * @exception java.io.IOException An IO exception from the parser,
409 * possibly from a byte stream or character stream
410 * supplied by the application.
411 * @see #parse(org.xml.sax.InputSource)
412 */
413 public void parse (String systemId)
414 throws IOException, SAXException;
415
416 }
|
1 /*
2 * Copyright (c) 2000, 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
110 *
111 * // register event handlers
112 * r.setContentHandler(new MyContentHandler());
113 * r.setErrorHandler(new MyErrorHandler());
114 *
115 * // parse the first document
116 * try {
117 * r.parse("http://www.foo.com/mydoc.xml");
118 * } catch (IOException e) {
119 * System.err.println("I/O exception reading XML document");
120 * } catch (SAXException e) {
121 * System.err.println("XML exception reading document.");
122 * }
123 * </pre>
124 *
125 * <p>Implementors are free (and encouraged) to invent their own features,
126 * using names built on their own URIs.</p>
127 *
128 * @param name The feature name, which is a fully-qualified URI.
129 * @return The current value of the feature (true or false).
130 * @throws org.xml.sax.SAXNotRecognizedException If the feature
131 * value can't be assigned or retrieved.
132 * @throws org.xml.sax.SAXNotSupportedException When the
133 * XMLReader recognizes the feature name but
134 * cannot determine its value at this time.
135 * @see #setFeature
136 */
137 public boolean getFeature (String name)
138 throws SAXNotRecognizedException, SAXNotSupportedException;
139
140
141 /**
142 * Set the value of a feature flag.
143 *
144 * <p>The feature name is any fully-qualified URI. It is
145 * possible for an XMLReader to expose a feature value but
146 * to be unable to change the current value.
147 * Some feature values may be immutable or mutable only
148 * in specific contexts, such as before, during, or after
149 * a parse.</p>
150 *
151 * <p>All XMLReaders are required to support setting
152 * http://xml.org/sax/features/namespaces to true and
153 * http://xml.org/sax/features/namespace-prefixes to false.</p>
154 *
155 * @param name The feature name, which is a fully-qualified URI.
156 * @param value The requested value of the feature (true or false).
157 * @throws org.xml.sax.SAXNotRecognizedException If the feature
158 * value can't be assigned or retrieved.
159 * @throws org.xml.sax.SAXNotSupportedException When the
160 * XMLReader recognizes the feature name but
161 * cannot set the requested value.
162 * @see #getFeature
163 */
164 public void setFeature (String name, boolean value)
165 throws SAXNotRecognizedException, SAXNotSupportedException;
166
167
168 /**
169 * Look up the value of a property.
170 *
171 * <p>The property name is any fully-qualified URI. It is
172 * possible for an XMLReader to recognize a property name but
173 * temporarily be unable to return its value.
174 * Some property values may be available only in specific
175 * contexts, such as before, during, or after a parse.</p>
176 *
177 * <p>XMLReaders are not required to recognize any specific
178 * property names, though an initial core set is documented for
179 * SAX2.</p>
180 *
181 * <p>Implementors are free (and encouraged) to invent their own properties,
182 * using names built on their own URIs.</p>
183 *
184 * @param name The property name, which is a fully-qualified URI.
185 * @return The current value of the property.
186 * @throws org.xml.sax.SAXNotRecognizedException If the property
187 * value can't be assigned or retrieved.
188 * @throws org.xml.sax.SAXNotSupportedException When the
189 * XMLReader recognizes the property name but
190 * cannot determine its value at this time.
191 * @see #setProperty
192 */
193 public Object getProperty (String name)
194 throws SAXNotRecognizedException, SAXNotSupportedException;
195
196
197 /**
198 * Set the value of a property.
199 *
200 * <p>The property name is any fully-qualified URI. It is
201 * possible for an XMLReader to recognize a property name but
202 * to be unable to change the current value.
203 * Some property values may be immutable or mutable only
204 * in specific contexts, such as before, during, or after
205 * a parse.</p>
206 *
207 * <p>XMLReaders are not required to recognize setting
208 * any specific property names, though a core set is defined by
209 * SAX2.</p>
210 *
211 * <p>This method is also the standard mechanism for setting
212 * extended handlers.</p>
213 *
214 * @param name The property name, which is a fully-qualified URI.
215 * @param value The requested value for the property.
216 * @throws org.xml.sax.SAXNotRecognizedException If the property
217 * value can't be assigned or retrieved.
218 * @throws org.xml.sax.SAXNotSupportedException When the
219 * XMLReader recognizes the property name but
220 * cannot set the requested value.
221 */
222 public void setProperty (String name, Object value)
223 throws SAXNotRecognizedException, SAXNotSupportedException;
224
225
226
227 ////////////////////////////////////////////////////////////////////
228 // Event handlers.
229 ////////////////////////////////////////////////////////////////////
230
231
232 /**
233 * Allow an application to register an entity resolver.
234 *
235 * <p>If the application does not register an entity resolver,
236 * the XMLReader will perform its own default resolution.</p>
237 *
238 * <p>Applications may register a new or different resolver in the
355 * application may reuse the same XMLReader object, possibly with a
356 * different input source.
357 * Configuration of the XMLReader object (such as handler bindings and
358 * values established for feature flags and properties) is unchanged
359 * by completion of a parse, unless the definition of that aspect of
360 * the configuration explicitly specifies other behavior.
361 * (For example, feature flags or properties exposing
362 * characteristics of the document being parsed.)
363 * </p>
364 *
365 * <p>During the parse, the XMLReader will provide information
366 * about the XML document through the registered event
367 * handlers.</p>
368 *
369 * <p>This method is synchronous: it will not return until parsing
370 * has ended. If a client application wants to terminate
371 * parsing early, it should throw an exception.</p>
372 *
373 * @param input The input source for the top-level of the
374 * XML document.
375 * @throws org.xml.sax.SAXException Any SAX exception, possibly
376 * wrapping another exception.
377 * @throws java.io.IOException An IO exception from the parser,
378 * possibly from a byte stream or character stream
379 * supplied by the application.
380 * @see org.xml.sax.InputSource
381 * @see #parse(java.lang.String)
382 * @see #setEntityResolver
383 * @see #setDTDHandler
384 * @see #setContentHandler
385 * @see #setErrorHandler
386 */
387 public void parse (InputSource input)
388 throws IOException, SAXException;
389
390
391 /**
392 * Parse an XML document from a system identifier (URI).
393 *
394 * <p>This method is a shortcut for the common case of reading a
395 * document from a system identifier. It is the exact
396 * equivalent of the following:</p>
397 *
398 * <pre>
399 * parse(new InputSource(systemId));
400 * </pre>
401 *
402 * <p>If the system identifier is a URL, it must be fully resolved
403 * by the application before it is passed to the parser.</p>
404 *
405 * @param systemId The system identifier (URI).
406 * @throws org.xml.sax.SAXException Any SAX exception, possibly
407 * wrapping another exception.
408 * @throws java.io.IOException An IO exception from the parser,
409 * possibly from a byte stream or character stream
410 * supplied by the application.
411 * @see #parse(org.xml.sax.InputSource)
412 */
413 public void parse (String systemId)
414 throws IOException, SAXException;
415
416 }
|