Package org.apache.axiom.om

# Class OMXMLStreamReaderConfiguration

java.lang.Object
org.apache.axiom.om.OMXMLStreamReaderConfiguration

public class OMXMLStreamReaderConfiguration extends Object
Defines additional configuration options for `OMContainer.getXMLStreamReader(boolean, OMXMLStreamReaderConfiguration)`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `OMXMLStreamReaderConfiguration()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `isNamespaceURIInterning()`
  Determine whether namespace URIs returned by the `XMLStreamReader` should be interned.
  `boolean`
  `isPreserveNamespaceContext()`
  Determine whether strict namespace preservation is enabled.
  `void`
  `setNamespaceURIInterning(boolean namespaceURIInterning)`
  Specify whether namespace URIs returned by the `XMLStreamReader` should be interned.
  `void`
  `setPreserveNamespaceContext(boolean preserveNamespaceContext)`
  Specify whether the namespace context determined by the ancestors of the element should be preserved.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### OMXMLStreamReaderConfiguration

    public OMXMLStreamReaderConfiguration()

- ## Method Details

  - ### isPreserveNamespaceContext

    public boolean isPreserveNamespaceContext()
    Determine whether strict namespace preservation is enabled. See `setPreserveNamespaceContext(boolean)` for more information about this option.
    Returns:
      the current value of this option

  - ### setPreserveNamespaceContext

    public void setPreserveNamespaceContext(boolean preserveNamespaceContext)
    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 `OMElement` corresponding 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_ELEMENT` event representing the `ns:echo` element.

    Parameters:
      `preserveNamespaceContext` - the value to set for this option

  - ### isNamespaceURIInterning

    public boolean isNamespaceURIInterning()
    Determine whether namespace URIs returned by the `XMLStreamReader` should be interned.
    Returns:
      the current value of this option

  - ### setNamespaceURIInterning

    public void setNamespaceURIInterning(boolean namespaceURIInterning)
    Specify whether namespace URIs returned by the `XMLStreamReader` should be interned. This applies to the return values of the following methods:
    - `XMLStreamReader.getAttributeNamespace(int)`
    - `XMLStreamReader.getNamespaceURI()`
    - `XMLStreamReader.getNamespaceURI(int)`
    - `XMLStreamReader.getNamespaceURI(String)`
    - `NamespaceContext.getNamespaceURI(String)` of the `NamespaceContext` instance returned by `XMLStreamReader.getNamespaceContext()`
    Parameters:
      `namespaceURIInterning` - the value to set for this option
    See Also:
      - `String.intern()`