Interface XMLParserConfiguration
-
- All Superinterfaces:
XMLComponentManager
- All Known Implementing Classes:
HTMLConfiguration
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 theXMLComponent
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
andsetProperty
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 theXMLComponent
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.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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.void
cleanup()
If the application decides to terminate parsing before the xml document is fully parsed, the application should call this method to free any resource allocated during parsing.XMLDocumentHandler
getDocumentHandler()
XMLErrorHandler
getErrorHandler()
boolean
getFeature(java.lang.String featureId)
java.lang.Object
getProperty(java.lang.String propertyId)
boolean
parse(boolean complete)
Parses the document in a pull parsing fashion.void
parse(XMLInputSource inputSource)
Parse an XML document.void
setDocumentHandler(XMLDocumentHandler documentHandler)
Sets the document handler to receive information about the document.void
setErrorHandler(XMLErrorHandler errorHandler)
Sets the error handler.void
setFeature(java.lang.String featureId, boolean state)
Sets the state of a feature.void
setInputSource(XMLInputSource inputSource)
Sets the input source for the document to parse.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
- Specified by:
getFeature
in interfaceXMLComponentManager
- Parameters:
featureId
- The feature identifier.- Returns:
- the state of a feature.
- 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
- Specified by:
getProperty
in interfaceXMLComponentManager
- Parameters:
propertyId
- The property identifier.- Returns:
- the value of a property.
- 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.
-
setInputSource
void setInputSource(XMLInputSource inputSource) throws XMLConfigurationException, java.io.IOException
Sets the input source for the document to parse.- Parameters:
inputSource
- The document's input source.- Throws:
XMLConfigurationException
- Thrown if there is a configuration error when initializing the parser.java.io.IOException
- Thrown on I/O error.- See Also:
parse(boolean)
-
parse
boolean parse(boolean complete) throws XNIException, java.io.IOException
Parses the document in a pull parsing fashion.- Parameters:
complete
- True if the pull parser should parse the remaining document completely.- Returns:
- True if there is more document to parse.
- 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.- See Also:
setInputSource(org.htmlunit.cyberneko.xerces.xni.parser.XMLInputSource)
-
cleanup
void cleanup()
If the application decides to terminate parsing before the xml document is fully parsed, the application should call this method to free any resource allocated during parsing. For example, close all opened streams.
-
-