org.apache.ode.utils

## Class NamespaceStack

- java.lang.Object
- - org.apache.ode.utils.NamespaceStack

-     public class NamespaceStack
      extends java.lang.Object

  This is a utility for a SAX `ContentHandler` implementation to use in tracking namespace declarations during a parse. The assumption is that the handler has access to the full stream of events relevant to managing the declarations. The primary use case is the resolution of `String`s, e.g., from attribute values or element content, to `QName` objects.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `NamespaceStack()` Construct a new instance with the bare minimum bindings for the `xmlns`, `xml`, and empty prefixes.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `allocatePrefix(java.lang.String hint, java.lang.String uri)` Allocate and declare a new namespace prefix for the current context that uses the supplied "hint" as a start.
    `void` | `declarePrefix(java.lang.String prefix, java.lang.String uri)` Declare a new prefix binding.
    `javax.xml.namespace.QName` | `dereferenceQName(java.lang.String qname)` Derference the prefix on a QName in `String` form and return a Java `QName` object.
    `void` | `endPrefixMappings(org.xml.sax.ContentHandler ch)` Fire the events for the current frame's prefixes into a `ContentHandler`.
    `java.lang.String` | `getNamespaceUri(java.lang.String prefix)` Retrieve the URI bound to the supplied prefix or `null` if no URI is bound to the supplied prefix.
    `java.lang.String` | `getPrefix(java.lang.String uri)`
    `void` | `pop()` Pop a context from the stack.
    `void` | `pushNewContext()` Push a fresh context onto the stack.
    `void` | `startPrefixMappings(org.xml.sax.ContentHandler ch)` Fire the events for the current frame's prefixes into a `ContentHandler`.
    `NSContext` | `toNSContext()` Convert the current stack of contexts into a single `NSContext`.

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

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

- - ### Constructor Detail

    - #### NamespaceStack

          public NamespaceStack()

      Construct a new instance with the bare minimum bindings for the `xmlns`, `xml`, and empty prefixes. Note that the empty prefix is bound to the empty (non-`null`) URI.

  - ### Method Detail

    - #### toNSContext

          public NSContext toNSContext()

      Convert the current stack of contexts into a single `NSContext`.

      Returns:
        the `NSContext` instance

    - #### pushNewContext

          public void pushNewContext()

      Push a fresh context onto the stack. This method should be called somewhere in the body of a `startElement()`, as it represents the namespace resolution context for the events that occur between that event and the corresponding `endElement()`.

      See Also:
        `ContentHandler`

    - #### pop

          public void pop()

      Pop a context from the stack. This method should be called somewhere in the body of an `endElement`, as it clears the context that was used for namespace resolution within the body of the corresponding element.

      See Also:
        `ContentHandler`

    - #### declarePrefix

          public void declarePrefix(java.lang.String prefix,
                           java.lang.String uri)

      Declare a new prefix binding. This binding will supercede a binding with the same prefix in the same scope. As a crutch, `null` arguments may be passed and will be interpreted as `""`. Note that binding a non-empty prefix to an empty URI is not permitted in XML 1.0 but is not flagged as an error by the method.

      Parameters:
        `prefix` - the prefix to bind
        `uri` - the URI to bind it to

    - #### getNamespaceUri

          public java.lang.String getNamespaceUri(java.lang.String prefix)

      Retrieve the URI bound to the supplied prefix or `null` if no URI is bound to the supplied prefix. As a crutch, a `null` argument may be passed and will be interpreted as the empty prefix (`""`).

    - #### startPrefixMappings

          public void startPrefixMappings(org.xml.sax.ContentHandler ch)
                                   throws org.xml.sax.SAXException

      Fire the events for the current frame's prefixes into a `ContentHandler`.

      Parameters:
        `ch` - the target `ContentHandler`
      Throws:
        `org.xml.sax.SAXException` - if the target method does.

    - #### endPrefixMappings

          public void endPrefixMappings(org.xml.sax.ContentHandler ch)
                                 throws org.xml.sax.SAXException

      Fire the events for the current frame's prefixes into a `ContentHandler`.

      Parameters:
        `ch` - the target `ContentHandler`.
      Throws:
        `org.xml.sax.SAXException` - if the target method does.

    - #### allocatePrefix

          public java.lang.String allocatePrefix(java.lang.String hint,
                                        java.lang.String uri)

      Allocate and declare a new namespace prefix for the current context that uses the supplied "hint" as a start. The algorithm used will defer to an existing binding, then try the hint, then use a variant of the hint until it finds an available prefix.

      Parameters:
        `hint` - a hint as to the desired prefix or `null` if any prefix will do.
        `uri` - the URI to bind to the prefix.
      Returns:
        the suggested prefix.

    - #### getPrefix

          public java.lang.String getPrefix(java.lang.String uri)

    - #### dereferenceQName

          public javax.xml.namespace.QName dereferenceQName(java.lang.String qname)

      Derference the prefix on a QName in `String` form and return a Java `QName` object.

      Parameters:
        `qname` - the QName in string form.
      Returns:
        the dereferenced `QName`.
      Throws:
        `java.lang.IllegalArgumentException` - if a `null` argument is passed, a malformed argument (e.g., `:foo` or `foo:`) is passed, or if the prefix cannot be resolved to a URI.