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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### OMXMLStreamReaderConfiguration

          public OMXMLStreamReaderConfiguration()

  - ### Method Detail

    - #### 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()`