Top Description Fields Constructors Methods
groovy.xml

public Class XmlParser

extends Object
implements ContentHandler
Class Inheritance
All Implemented Interfaces
org.xml.sax.ContentHandler
Imports
groovy.namespace.QName, groovy.util.Node, org.xml.sax.Attributes, .ContentHandler, .DTDHandler, .EntityResolver, .ErrorHandler, .InputSource, .Locator, .SAXException, .SAXNotRecognizedException, .SAXNotSupportedException, .XMLReader, javax.xml.XMLConstants, javax.xml.parsers.ParserConfigurationException, .SAXParser, .SAXParserFactory, java.io.File, .FileInputStream, .IOException, .InputStream, .Reader, .StringReader, java.util.ArrayList, .LinkedHashMap, .List, .Map
A helper class for parsing XML into a tree of Node instances for a simple way of processing XML. This parser does not preserve the XML InfoSet - if that's what you need try using W3C DOM, dom4j, JDOM, XOM etc. This parser ignores comments and processing instructions and converts the XML into a Node for each element in the XML with attributes and child Nodes and Strings. This simple model is sufficient for most simple use cases of processing XML.

Example usage: 

import groovy.xml.XmlParser
def xml = '<root><one a1="uno!"/><two>Some text!</two></root>'
def rootNode = new XmlParser().parseText(xml)
assert rootNode.name() == 'root'
assert rootNode.one[0].@a1 == 'uno!'
assert rootNode.two.text() == 'Some text!'
rootNode.children().each { assert it.name() in ['one','two'] }

Field Summary

Modifier and TypeField and Description
private StringBuilder
bodyText

private boolean
keepIgnorableWhitespace

private Locator
locator

private boolean
namespaceAware

private Node
parent

private final XMLReader
reader

private final List<Node>
stack

private boolean
trimWhitespace

Constructor Summary

AccessConstructor and Description
public
XmlParser()

Creates a non-validating and namespace-aware XmlParser which does not allow DOCTYPE declarations in documents.

public
XmlParser(boolean
true if the parser should validate documents as they are parsed; false otherwise.
validating, boolean
true if the parser should provide support for XML namespaces; false otherwise.
namespaceAware)

Creates a XmlParser which does not allow DOCTYPE declarations in documents.

public
XmlParser(boolean
true if the parser should validate documents as they are parsed; false otherwise.
validating, boolean
true if the parser should provide support for XML namespaces; false otherwise.
namespaceAware, boolean
true if the parser should provide support for DOCTYPE declarations; false otherwise.
allowDocTypeDeclaration)

Creates a XmlParser.

public
XmlParser(XMLReader reader)

public
XmlParser(SAXParser parser)

Method Summary

Modifier and TypeMethod and Description
protected void
addTextToNode()

public void
characters(char[]
the characters from the XML document
buffer, int
the start position in the array
start, int
the number of characters to read from the array
length)

Implements org.xml.sax.ContentHandler.characters.

Receive notification of character data.
protected Node

Returns:

a new Node instance representing the current node
createNode(Node
the parent node, or null if the node being created is the root node
parent, Object
an Object representing the name of the node (typically an instance of QName)
name, Map<K, V>
a Map of attribute names to attribute values
attributes)

Creates a new node with the given parent, name, and attributes.

public void
endDocument()

Implements org.xml.sax.ContentHandler.endDocument.

Receive notification of the end of a document.
public void
endElement(String
the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed
namespaceURI, String
the local name (without prefix), or the empty string if Namespace processing is not being performed
localName, String
the qualified XML name (with prefix), or the empty string if qualified names are not available
qName)

Implements org.xml.sax.ContentHandler.endElement.

Receive notification of the end of an element.
public void
endPrefixMapping(String
the prefix that was being mapped. This is the empty string when a default mapping scope ends.
prefix)

Implements org.xml.sax.ContentHandler.endPrefixMapping.

End the scope of a prefix-URI mapping.
public Locator
getDocumentLocator()

public DTDHandler
getDTDHandler()

protected Object

Returns:

the newly created representation of the name
getElementName(String
the namespace URI
namespaceURI, String
the local name
localName, String
the qualified name
qName)

Return a name given the namespaceURI, localName and qName.

public EntityResolver
getEntityResolver()

public ErrorHandler
getErrorHandler()

public boolean
getFeature(final String uri)

public Object
getProperty(final String uri)

protected XMLReader
getXMLReader()

public void
ignorableWhitespace(char[]
the characters from the XML document
buffer, int
the start position in the array
start, int
the number of characters to read from the array
len)

Implements org.xml.sax.ContentHandler.ignorableWhitespace.

Receive notification of ignorable whitespace in element content.
public boolean

Returns:

true if ignorable whitespace will be kept (default false)
isKeepIgnorableWhitespace()

Returns the current keep ignorable whitespace setting.

public boolean

Returns:

true if namespace handling is enabled
isNamespaceAware()

Determine if namespace handling is enabled.

public boolean

Returns:

true if whitespace will be trimmed
isTrimWhitespace()

Returns the current trim whitespace setting.

public Node

Returns:

the root node of the parsed tree of Nodes
parse(File
the File containing the XML to be parsed
file)

Parses the content of the given file as XML turning it into a tree of Nodes.

public Node

Returns:

the root node of the parsed tree of Nodes
parse(InputSource
the InputSource for the XML to parse
input)

Parse the content of the specified input source into a tree of Nodes.

public Node

Returns:

the root node of the parsed tree of Nodes
parse(InputStream
an InputStream containing the XML to be parsed
input)

Parse the content of the specified input stream into a tree of Nodes.

public Node

Returns:

the root node of the parsed tree of Nodes
parse(Reader
a Reader to read the XML to be parsed
in)

Parse the content of the specified reader into a tree of Nodes.

public Node

Returns:

the root node of the parsed tree of Nodes
parse(String
a String containing a uri pointing to the XML to be parsed
uri)

Parse the content of the specified URI into a tree of Nodes.

public Node

Returns:

the root node of the parsed tree of Nodes
parseText(String
the XML text to parse
text)

A helper method to parse the given text as XML.

public void
processingInstruction(String
the processing instruction target
target, String
the processing instruction data, or null if none was supplied. The data does not include any whitespace separating it from the target
data)

Implements org.xml.sax.ContentHandler.processingInstruction.

Receive notification of a processing instruction.
public void
setDocumentLocator(Locator
an object that can return the location of any SAX document event
locator)

Implements org.xml.sax.ContentHandler.setDocumentLocator.

Receive an object for locating the origin of SAX document events.
public void
setDTDHandler(final DTDHandler dtdHandler)

public void
setEntityResolver(final EntityResolver entityResolver)

public void
setErrorHandler(final ErrorHandler errorHandler)

public void
setFeature(final String uri, final boolean value)

public void
setKeepIgnorableWhitespace(boolean
the desired new value
keepIgnorableWhitespace)

Sets the keep ignorable whitespace setting value.

public void
setNamespaceAware(boolean
the new desired value
namespaceAware)

Enable and/or disable namespace handling.

public void
setProperty(final String uri, final Object value)

private static void
setQuietly(SAXParserFactory factory, String feature, boolean value)

public void
setTrimWhitespace(boolean
the desired setting value
trimWhitespace)

Sets the trim whitespace setting value.

public void
skippedEntity(String
the name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]"
name)

Implements org.xml.sax.ContentHandler.skippedEntity.

Receive notification of a skipped entity.
public void
startDocument()

Implements org.xml.sax.ContentHandler.startDocument.

Receive notification of the beginning of a document.
public void
startElement(String
the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed
namespaceURI, String
the local name (without prefix), or the empty string if Namespace processing is not being performed
localName, String
the qualified name (with prefix), or the empty string if qualified names are not available
qName, Attributes
the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined
list)

Implements org.xml.sax.ContentHandler.startElement.

Receive notification of the beginning of an element.
public void
startPrefixMapping(String
the Namespace prefix being declared. An empty string is used for the default element namespace, which has no prefix.
prefix, String
the Namespace URI the prefix is mapped to
namespaceURI)

Implements org.xml.sax.ContentHandler.startPrefixMapping.

Begin the scope of a prefix-URI Namespace mapping.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

bodyTextback to summary
private StringBuilder bodyText
keepIgnorableWhitespaceback to summary
private boolean keepIgnorableWhitespace
locatorback to summary
private Locator locator
namespaceAwareback to summary
private boolean namespaceAware
parentback to summary
private Node parent
readerback to summary
private final XMLReader reader
stackback to summary
private final List<Node> stack
trimWhitespaceback to summary
private boolean trimWhitespace

Constructor Detail

XmlParserback to summary
public XmlParser() throws ParserConfigurationException, SAXException

Creates a non-validating and namespace-aware XmlParser which does not allow DOCTYPE declarations in documents.

Exceptions
ParserConfigurationException:
if no parser which satisfies the requested configuration can be created.
SAXException:
for SAX errors.
XmlParserback to summary
public XmlParser(boolean validating, boolean namespaceAware) throws ParserConfigurationException, SAXException

Creates a XmlParser which does not allow DOCTYPE declarations in documents.

Parameters
validating:boolean

true if the parser should validate documents as they are parsed; false otherwise.

namespaceAware:boolean

true if the parser should provide support for XML namespaces; false otherwise.

Exceptions
ParserConfigurationException:
if no parser which satisfies the requested configuration can be created.
SAXException:
for SAX errors.
XmlParserback to summary
public XmlParser(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration) throws ParserConfigurationException, SAXException

Creates a XmlParser.

Parameters
validating:boolean

true if the parser should validate documents as they are parsed; false otherwise.

namespaceAware:boolean

true if the parser should provide support for XML namespaces; false otherwise.

allowDocTypeDeclaration:boolean

true if the parser should provide support for DOCTYPE declarations; false otherwise.

Exceptions
ParserConfigurationException:
if no parser which satisfies the requested configuration can be created.
SAXException:
for SAX errors.
XmlParserback to summary
public XmlParser(XMLReader reader)
XmlParserback to summary
public XmlParser(SAXParser parser) throws SAXException

Method Detail

addTextToNodeback to summary
protected void addTextToNode()
charactersback to summary
public void characters(char[] buffer, int start, int length) throws SAXException

Implements org.xml.sax.ContentHandler.characters.

Doc from org.xml.sax.ContentHandler.characters.

Receive notification of character data.

The Parser will call this method to report each chunk of character data. SAX parsers may return all contiguous character data in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Individual characters may consist of more than one Java char value. There are two important cases where this happens, because characters can't be represented in just sixteen bits. In one case, characters are represented in a Surrogate Pair, using two special Unicode values. Such characters are in the so-called "Astral Planes", with a code point above U+FFFF. A second case involves composite characters, such as a base character combining with one or more accent characters.

Your code should not assume that algorithms using char-at-a-time idioms will be working in character units; in some cases they will split characters. This is relevant wherever XML permits arbitrary characters, such as attribute values, processing instruction data, and comments as well as in data reported from this method. It's also generally relevant whenever Java code manipulates internationalized text; the issue isn't unique to XML.

Note that some parsers will report whitespace in element content using the ignorableWhitespace method rather than this one (validating parsers must do so).

Parameters
buffer:char[]

the characters from the XML document

start:int

the start position in the array

length:int

the number of characters to read from the array

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
createNodeback to summary
protected Node createNode(Node parent, Object name, Map<K, V> attributes)

Creates a new node with the given parent, name, and attributes. The default implementation returns an instance of groovy.util.Node.

Parameters
parent:Node

the parent node, or null if the node being created is the root node

name:Object

an Object representing the name of the node (typically an instance of QName)

attributes:Map<K, V>

a Map of attribute names to attribute values

Returns:Node

a new Node instance representing the current node

endDocumentback to summary
public void endDocument() throws SAXException

Implements org.xml.sax.ContentHandler.endDocument.

Doc from org.xml.sax.ContentHandler.endDocument.

Receive notification of the end of a document.

This method is invoked by the parser to signal it has reached the end of the document after successfully completing the parsing process. After the event, the parser will return the control to the application.

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
endElementback to summary
public void endElement(String namespaceURI, String localName, String qName) throws SAXException

Implements org.xml.sax.ContentHandler.endElement.

Doc from org.xml.sax.ContentHandler.endElement.

Receive notification of the end of an element.

The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement event for every endElement event (even when the element is empty).

For information on the names, see startElement.

Parameters
namespaceURI:String

the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName:String

the local name (without prefix), or the empty string if Namespace processing is not being performed

qName:String

the qualified XML name (with prefix), or the empty string if qualified names are not available

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
endPrefixMappingback to summary
public void endPrefixMapping(String prefix) throws SAXException

Implements org.xml.sax.ContentHandler.endPrefixMapping.

Doc from org.xml.sax.ContentHandler.endPrefixMapping.

End the scope of a prefix-URI mapping.

See startPrefixMapping for details. These events will always occur immediately after the corresponding endElement event, but the order of endPrefixMapping events is not otherwise guaranteed.

Parameters
prefix:String

the prefix that was being mapped. This is the empty string when a default mapping scope ends.

Exceptions
SAXException:
the client may throw an exception during processing
getDocumentLocatorback to summary
public Locator getDocumentLocator()
getDTDHandlerback to summary
public DTDHandler getDTDHandler()
getElementNameback to summary
protected Object getElementName(String namespaceURI, String localName, String qName)

Return a name given the namespaceURI, localName and qName.

Parameters
namespaceURI:String

the namespace URI

localName:String

the local name

qName:String

the qualified name

Returns:Object

the newly created representation of the name

getEntityResolverback to summary
public EntityResolver getEntityResolver()
getErrorHandlerback to summary
public ErrorHandler getErrorHandler()
getFeatureback to summary
public boolean getFeature(final String uri) throws SAXNotRecognizedException, SAXNotSupportedException
getPropertyback to summary
public Object getProperty(final String uri) throws SAXNotRecognizedException, SAXNotSupportedException
getXMLReaderback to summary
protected XMLReader getXMLReader()
ignorableWhitespaceback to summary
public void ignorableWhitespace(char[] buffer, int start, int len) throws SAXException

Implements org.xml.sax.ContentHandler.ignorableWhitespace.

Doc from org.xml.sax.ContentHandler.ignorableWhitespace.

Receive notification of ignorable whitespace in element content.

Validating Parsers must use this method to report each chunk of whitespace in element content (see the W3C XML 1.0 recommendation, section 2.10): non-validating parsers may also use this method if they are capable of parsing and using content models.

SAX parsers may return all contiguous whitespace in a single chunk, or they may split it into several chunks; however, all of the characters in any single event must come from the same external entity, so that the Locator provides useful information.

The application must not attempt to read from the array outside of the specified range.

Parameters
buffer:char[]

the characters from the XML document

start:int

the start position in the array

len:int

the number of characters to read from the array

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
isKeepIgnorableWhitespaceback to summary
public boolean isKeepIgnorableWhitespace()

Returns the current keep ignorable whitespace setting.

Returns:boolean

true if ignorable whitespace will be kept (default false)

isNamespaceAwareback to summary
public boolean isNamespaceAware()

Determine if namespace handling is enabled.

Returns:boolean

true if namespace handling is enabled

isTrimWhitespaceback to summary
public boolean isTrimWhitespace()

Returns the current trim whitespace setting.

Returns:boolean

true if whitespace will be trimmed

parseback to summary
public Node parse(File file) throws IOException, SAXException

Parses the content of the given file as XML turning it into a tree of Nodes.

Parameters
file:File

the File containing the XML to be parsed

Returns:Node

the root node of the parsed tree of Nodes

Exceptions
IOException:
An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
SAXException:
Any SAX exception, possibly wrapping another exception.
parseback to summary
public Node parse(InputSource input) throws IOException, SAXException

Parse the content of the specified input source into a tree of Nodes.

Parameters
input:InputSource

the InputSource for the XML to parse

Returns:Node

the root node of the parsed tree of Nodes

Exceptions
IOException:
An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
SAXException:
Any SAX exception, possibly wrapping another exception.
parseback to summary
public Node parse(InputStream input) throws IOException, SAXException

Parse the content of the specified input stream into a tree of Nodes.

Note that using this method will not provide the parser with any URI for which to find DTDs etc

Parameters
input:InputStream

an InputStream containing the XML to be parsed

Returns:Node

the root node of the parsed tree of Nodes

Exceptions
IOException:
An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
SAXException:
Any SAX exception, possibly wrapping another exception.
parseback to summary
public Node parse(Reader in) throws IOException, SAXException

Parse the content of the specified reader into a tree of Nodes.

Note that using this method will not provide the parser with any URI for which to find DTDs etc

Parameters
in:Reader

a Reader to read the XML to be parsed

Returns:Node

the root node of the parsed tree of Nodes

Exceptions
IOException:
An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
SAXException:
Any SAX exception, possibly wrapping another exception.
parseback to summary
public Node parse(String uri) throws IOException, SAXException

Parse the content of the specified URI into a tree of Nodes.

Parameters
uri:String

a String containing a uri pointing to the XML to be parsed

Returns:Node

the root node of the parsed tree of Nodes

Exceptions
IOException:
An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
SAXException:
Any SAX exception, possibly wrapping another exception.
parseTextback to summary
public Node parseText(String text) throws IOException, SAXException

A helper method to parse the given text as XML.

Parameters
text:String

the XML text to parse

Returns:Node

the root node of the parsed tree of Nodes

Exceptions
IOException:
An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
SAXException:
Any SAX exception, possibly wrapping another exception.
processingInstructionback to summary
public void processingInstruction(String target, String data) throws SAXException

Implements org.xml.sax.ContentHandler.processingInstruction.

Doc from org.xml.sax.ContentHandler.processingInstruction.

Receive notification of a processing instruction.

The Parser will invoke this method once for each processing instruction found: note that processing instructions may occur before or after the main document element.

A SAX parser must never report an XML declaration (XML 1.0, section 2.8) or a text declaration (XML 1.0, section 4.3.1) using this method.

Like characters(), processing instruction data may have characters that need more than one char value.

Parameters
target:String

the processing instruction target

data:String

the processing instruction data, or null if none was supplied. The data does not include any whitespace separating it from the target

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
setDocumentLocatorback to summary
public void setDocumentLocator(Locator locator)

Implements org.xml.sax.ContentHandler.setDocumentLocator.

Doc from org.xml.sax.ContentHandler.setDocumentLocator.

Receive an object for locating the origin of SAX document events.

SAX parsers are strongly encouraged (though not absolutely required) to supply a locator: if it does so, it must supply the locator to the application by invoking this method before invoking any of the other methods in the ContentHandler interface.

The locator allows the application to determine the end position of any document-related event, even if the parser is not reporting an error. Typically, the application will use this information for reporting its own errors (such as character content that does not match an application's business rules). The information returned by the locator is probably not sufficient for use with a search engine.

Note that the locator will return correct information only during the invocation SAX event callbacks after startDocument returns and before endDocument is called. The application should not attempt to use it at any other time.

Parameters
locator:Locator

an object that can return the location of any SAX document event

setDTDHandlerback to summary
public void setDTDHandler(final DTDHandler dtdHandler)
setEntityResolverback to summary
public void setEntityResolver(final EntityResolver entityResolver)
setErrorHandlerback to summary
public void setErrorHandler(final ErrorHandler errorHandler)
setFeatureback to summary
public void setFeature(final String uri, final boolean value) throws SAXNotRecognizedException, SAXNotSupportedException
setKeepIgnorableWhitespaceback to summary
public void setKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)

Sets the keep ignorable whitespace setting value.

Parameters
keepIgnorableWhitespace:boolean

the desired new value

setNamespaceAwareback to summary
public void setNamespaceAware(boolean namespaceAware)

Enable and/or disable namespace handling.

Parameters
namespaceAware:boolean

the new desired value

setPropertyback to summary
public void setProperty(final String uri, final Object value) throws SAXNotRecognizedException, SAXNotSupportedException
setQuietlyback to summary
private static void setQuietly(SAXParserFactory factory, String feature, boolean value)
setTrimWhitespaceback to summary
public void setTrimWhitespace(boolean trimWhitespace)

Sets the trim whitespace setting value.

Parameters
trimWhitespace:boolean

the desired setting value

skippedEntityback to summary
public void skippedEntity(String name) throws SAXException

Implements org.xml.sax.ContentHandler.skippedEntity.

Doc from org.xml.sax.ContentHandler.skippedEntity.

Receive notification of a skipped entity. This is not called for entity references within markup constructs such as element start tags or markup declarations. (The XML recommendation requires reporting skipped external entities. SAX also reports internal entity expansion/non-expansion, except within markup constructs.)

The Parser will invoke this method each time the entity is skipped. Non-validating processors may skip entities if they have not seen the declarations (because, for example, the entity was declared in an external DTD subset). All processors may skip external entities, depending on the values of the http://xml.org/sax/features/external-general-entities and the http://xml.org/sax/features/external-parameter-entities properties.

Parameters
name:String

the name of the skipped entity. If it is a parameter entity, the name will begin with '%', and if it is the external DTD subset, it will be the string "[dtd]"

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
startDocumentback to summary
public void startDocument() throws SAXException

Implements org.xml.sax.ContentHandler.startDocument.

Doc from org.xml.sax.ContentHandler.startDocument.

Receive notification of the beginning of a document.

The SAX parser will invoke this method only once, before any other event callbacks (except for setDocumentLocator).

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
startElementback to summary
public void startElement(String namespaceURI, String localName, String qName, Attributes list) throws SAXException

Implements org.xml.sax.ContentHandler.startElement.

Doc from org.xml.sax.ContentHandler.startElement.

Receive notification of the beginning of an element.

The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement event for every startElement event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement event.

This event allows up to three name components for each element:

  1. the Namespace URI;
  2. the local name; and
  3. the qualified (prefixed) name.

Any or all of these may be provided, depending on the values of the http://xml.org/sax/features/namespaces and the http://xml.org/sax/features/namespace-prefixes properties:

  • the Namespace URI and local name are required when the namespaces property is true (the default), and are optional when the namespaces property is false (if one is specified, both must be);
  • the qualified name is required when the namespace-prefixes property is true, and is optional when the namespace-prefixes property is false (the default).

Note that the attribute list provided will contain only attributes with explicit values (specified or defaulted): #IMPLIED attributes will be omitted. The attribute list will contain attributes used for Namespace declarations (xmlns* attributes) only if the http://xml.org/sax/features/namespace-prefixes property is true (it is false by default, and support for a true value is optional).

Like characters(), attribute values may have characters that need more than one char value.

Parameters
namespaceURI:String

the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed

localName:String

the local name (without prefix), or the empty string if Namespace processing is not being performed

qName:String

the qualified name (with prefix), or the empty string if qualified names are not available

list:Attributes

the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object. The value of this object after startElement returns is undefined

Exceptions
SAXException:
any SAX exception, possibly wrapping another exception
startPrefixMappingback to summary
public void startPrefixMapping(String prefix, String namespaceURI) throws SAXException

Implements org.xml.sax.ContentHandler.startPrefixMapping.

Doc from org.xml.sax.ContentHandler.startPrefixMapping.

Begin the scope of a prefix-URI Namespace mapping.

The information from this event is not necessary for normal Namespace processing: the SAX XML reader will automatically replace prefixes for element and attribute names when the http://xml.org/sax/features/namespaces feature is true (the default).

There are cases, however, when applications need to use prefixes in character data or in attribute values, where they cannot safely be expanded automatically; the start/endPrefixMapping event supplies the information to the application to expand prefixes in those contexts itself, if necessary.

Note that start/endPrefixMapping events are not guaranteed to be properly nested relative to each other: all startPrefixMapping events will occur immediately before the corresponding startElement event, and all endPrefixMapping events will occur immediately after the corresponding endElement event, but their order is not otherwise guaranteed.

There should never be start/endPrefixMapping events for the "xml" prefix, since it is predeclared and immutable.

Parameters
prefix:String

the Namespace prefix being declared. An empty string is used for the default element namespace, which has no prefix.

namespaceURI:String

the Namespace URI the prefix is mapped to

Exceptions
SAXException:
the client may throw an exception during processing