org.apache.xerces.xni.parser

## Interface XMLParserConfiguration

- All Superinterfaces:
    XMLComponentManager
  All Known Subinterfaces:
    XMLPullParserConfiguration

      public interface XMLParserConfiguration
      extends XMLComponentManager

  Represents a parser configuration. The parser configuration maintains a table of recognized features and properties, assembles components for the parsing pipeline, and is responsible for initiating parsing of an XML document.

  By separating the configuration of a parser from the specific parser instance, applications can create new configurations and re-use the existing parser components and external API generators (e.g. the DOMParser and SAXParser).

  The internals of any specific parser configuration instance are hidden. Therefore, each configuration may implement the parsing mechanism any way necessary. However, the parser configuration should follow these guidelines:

  - Call the `reset` method on each component before parsing. This is only required if the configuration is re-using existing components that conform to the `XMLComponent` interface. If the configuration uses all custom parts, then it is free to implement everything as it sees fit as long as it follows the other guidelines.
  - Call the `setFeature` and `setProperty` method on each component during parsing to propagate features and properties that have changed. This is only required if the configuration is re-using existing components that conform to the `XMLComponent` interface. If the configuration uses all custom parts, then it is free to implement everything as it sees fit as long as it follows the other guidelines.
  - Pass the same unique String references for all symbols that are propagated to the registered handlers. Symbols include, but may not be limited to, the names of elements and attributes (including their uri, prefix, and localpart). This is suggested but not an absolute must. However, the standard parser components may require access to the same symbol table for creation of unique symbol references to be propagated in the XNI pipeline.
  Version:
    $Id: XMLParserConfiguration.java 699902 2008-09-28 21:40:49Z mrglavas $
  Author:
    Arnaud Le Hors, IBM, Andy Clark, IBM

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRecognizedFeatures(java.lang.String[] featureIds)` Allows a parser to add parser specific features to be recognized and managed by the parser configuration.
    `void` | `addRecognizedProperties(java.lang.String[] propertyIds)` Allows a parser to add parser specific properties to be recognized and managed by the parser configuration.
    `XMLDocumentHandler` | `getDocumentHandler()` Returns the registered document handler.
    `XMLDTDContentModelHandler` | `getDTDContentModelHandler()` Returns the registered DTD content model handler.
    `XMLDTDHandler` | `getDTDHandler()` Returns the registered DTD handler.
    `XMLEntityResolver` | `getEntityResolver()` Returns the registered entity resolver.
    `XMLErrorHandler` | `getErrorHandler()` Returns the registered error handler.
    `boolean` | `getFeature(java.lang.String featureId)` Returns the state of a feature.
    `java.util.Locale` | `getLocale()` Returns the locale.
    `java.lang.Object` | `getProperty(java.lang.String propertyId)` Returns the value of a property.
    `void` | `parse(XMLInputSource inputSource)` Parse an XML document.
    `void` | `setDocumentHandler(XMLDocumentHandler documentHandler)` Sets the document handler to receive information about the document.
    `void` | `setDTDContentModelHandler(XMLDTDContentModelHandler dtdContentModelHandler)` Sets the DTD content model handler.
    `void` | `setDTDHandler(XMLDTDHandler dtdHandler)` Sets the DTD handler.
    `void` | `setEntityResolver(XMLEntityResolver entityResolver)` Sets the entity resolver.
    `void` | `setErrorHandler(XMLErrorHandler errorHandler)` Sets the error handler.
    `void` | `setFeature(java.lang.String featureId, boolean state)` Sets the state of a feature.
    `void` | `setLocale(java.util.Locale locale)` Set the locale to use for messages.
    `void` | `setProperty(java.lang.String propertyId, java.lang.Object value)` Sets the value of a property.

- - ### Method Detail

    - #### parse

          void parse(XMLInputSource inputSource)
                     throws XNIException,
                            java.io.IOException

      Parse an XML document.

      The parser can use this method to instruct this configuration to begin parsing an XML document from any valid input source (a character stream, a byte stream, or a URI).

      Parsers may not invoke this method while a parse is in progress. Once a parse is complete, the parser may then parse another XML document.

      This method is synchronous: it will not return until parsing has ended. If a client application wants to terminate parsing early, it should throw an exception.

      When this method returns, all characters streams and byte streams opened by the parser are closed.

      Parameters:
        `inputSource` - The input source for the top-level of the XML document.
      Throws:
        `XNIException` - Any XNI exception, possibly wrapping another exception.
        `java.io.IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the parser.

    - #### addRecognizedFeatures

          void addRecognizedFeatures(java.lang.String[] featureIds)

      Allows a parser to add parser specific features to be recognized and managed by the parser configuration.
      Parameters:
        `featureIds` - An array of the additional feature identifiers to be recognized.

    - #### setFeature

          void setFeature(java.lang.String featureId,
                        boolean state)
                          throws XMLConfigurationException

      Sets the state of a feature. This method is called by the parser and gets propagated to components in this parser configuration.
      Parameters:
        `featureId` - The feature identifier.
        `state` - The state of the feature.
      Throws:
        `XMLConfigurationException` - Thrown if there is a configuration error.

    - #### getFeature

          boolean getFeature(java.lang.String featureId)
                             throws XMLConfigurationException

      Returns the state of a feature.
      Specified by:
        `getFeature` in interface `XMLComponentManager`
      Parameters:
        `featureId` - The feature identifier.
      Throws:
        `XMLConfigurationException` - Thrown if there is a configuration error.

    - #### addRecognizedProperties

          void addRecognizedProperties(java.lang.String[] propertyIds)

      Allows a parser to add parser specific properties to be recognized and managed by the parser configuration.
      Parameters:
        `propertyIds` - An array of the additional property identifiers to be recognized.

    - #### setProperty

          void setProperty(java.lang.String propertyId,
                         java.lang.Object value)
                           throws XMLConfigurationException

      Sets the value of a property. This method is called by the parser and gets propagated to components in this parser configuration.
      Parameters:
        `propertyId` - The property identifier.
        `value` - The value of the property.
      Throws:
        `XMLConfigurationException` - Thrown if there is a configuration error.

    - #### getProperty

          java.lang.Object getProperty(java.lang.String propertyId)
                                       throws XMLConfigurationException

      Returns the value of a property.
      Specified by:
        `getProperty` in interface `XMLComponentManager`
      Parameters:
        `propertyId` - The property identifier.
      Throws:
        `XMLConfigurationException` - Thrown if there is a configuration error.

    - #### setErrorHandler

          void setErrorHandler(XMLErrorHandler errorHandler)

      Sets the error handler.
      Parameters:
        `errorHandler` - The error resolver.

    - #### getErrorHandler

          XMLErrorHandler getErrorHandler()

      Returns the registered error handler.

    - #### setDocumentHandler

          void setDocumentHandler(XMLDocumentHandler documentHandler)

      Sets the document handler to receive information about the document.
      Parameters:
        `documentHandler` - The document handler.

    - #### getDocumentHandler

          XMLDocumentHandler getDocumentHandler()

      Returns the registered document handler.

    - #### setDTDHandler

          void setDTDHandler(XMLDTDHandler dtdHandler)

      Sets the DTD handler.
      Parameters:
        `dtdHandler` - The DTD handler.

    - #### getDTDHandler

          XMLDTDHandler getDTDHandler()

      Returns the registered DTD handler.

    - #### setDTDContentModelHandler

          void setDTDContentModelHandler(XMLDTDContentModelHandler dtdContentModelHandler)

      Sets the DTD content model handler.
      Parameters:
        `dtdContentModelHandler` - The DTD content model handler.

    - #### getDTDContentModelHandler

          XMLDTDContentModelHandler getDTDContentModelHandler()

      Returns the registered DTD content model handler.

    - #### setEntityResolver

          void setEntityResolver(XMLEntityResolver entityResolver)

      Sets the entity resolver.
      Parameters:
        `entityResolver` - The new entity resolver.

    - #### getEntityResolver

          XMLEntityResolver getEntityResolver()

      Returns the registered entity resolver.

    - #### setLocale

          void setLocale(java.util.Locale locale)
                         throws XNIException

      Set the locale to use for messages.
      Parameters:
        `locale` - The locale object to use for localization of messages.
      Throws:
        `XNIException` - Thrown if the parser does not support the specified locale.

    - #### getLocale

          java.util.Locale getLocale()

      Returns the locale.

Copyright © 1999-2022 The Apache Software Foundation. All Rights Reserved.