< prev index next >

src/java.xml/share/classes/org/xml/sax/XMLReader.java

Print this page


   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 }
< prev index next >