org.apache.ode.utils
Class NamespaceStack

java.lang.Object
  extended by 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 Strings, e.g., from attribute values or element content, to QName objects.


Constructor Summary
NamespaceStack()
           Construct a new instance with the bare minimum bindings for the xmlns, xml, and empty prefixes.
 
Method Summary
 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.