Specify whether the namespace context determined by the ancestors of the element should be
preserved. This option only applies to
OMElement instances and is disabled by
default.
When this option is enabled, the
XMLStreamReader#getNamespaceCount(),
XMLStreamReader#getNamespacePrefix(int) and
XMLStreamReader#getNamespaceURI(int) will report additional namespace declarations
for the
XMLStreamConstants#START_ELEMENT event corresponding to the element on which
this method is called, i.e. the root element of the resulting stream. These namespace
declarations correspond to namespaces declared by the ancestors of the element and that are
visible in the context of the element.
More precisely, if this option is enabled, then the namespace declarations reported for the
first
XMLStreamConstants#START_ELEMENT event in the returned stream will be the same
as the declarations that would be returned by
OMElement#getNamespacesInScope(), with
the exception that a xmlns="" declaration present on the element will be preserved.
This feature is useful for code that relies on the namespace declarations reported by the
XMLStreamReader to reconstruct the namespace context (instead of using the namespace
context provided by
XMLStreamReader#getNamespaceContext()). An example helps to
illustrate how this works. Consider the following XML message:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Body>
<ns:echo xmlns:ns="urn:test">
<in xsi:type="xsd:string">test</in>
</ns:echo>
</soapenv:Body>
</soapenv:Envelope>
When
OMContainer#getXMLStreamReader(boolean) is invoked on the
OMElementcorresponding to ns:echo, only the namespace declaration for the ns prefix
will be reported. This may cause a problem when the caller attempts to resolve the QName
value xsd:string of the xsi:type attribute. If namespace context
preservation is enabled, then the
XMLStreamReader returned by this method will
generate additional namespace declarations for the soapenv, xsd and
xsi prefixes. They are reported for the
XMLStreamConstants#START_ELEMENTevent representing the ns:echo element.