com.nwalsh.namespace
Class NamespaceContextHelper

java.lang.Object
  com.nwalsh.namespace.NamespaceContextHelper

All Implemented Interfaces:

javax.xml.namespace.NamespaceContext

public class NamespaceContextHelper
extends java.lang.Object
implements javax.xml.namespace.NamespaceContext

Helper implementation of the javax.xml.namespace.NamespaceContext interface.

This class implements the JAXP (1.3+) NamespaceContext interface. This is the interface used by the JAXP XPath APIs to establish namespace bindings for XPath expressions.

There are two errors (in retrospect) with respect to the namespace context in the XPath API. First, there's no way to construct a new one. Given an XPath you can find out what context it is using, but if you want to construct a new expression, there's no standard class that you can instantiate to build a new context. Second, the NamespaceContext interface is obviously (again, in retrospect) missing a method that returns an iterator that will allow you to find all the namespace URIs (and/or prefixes, which would be equivalent) in the context.

This class addresses the first error by providing an object that you can instantiate that implements the NamespaceContext interface. It's not a standard class, but it at least saves you the trouble of writing it yourself. (Feel free to move it into your own package, of course.)

There's really no way to address the second error. An interface, like NamespaceContext, is immutable once released into the wild in the Java platform. (This is a consequence of backwards compatibility rules.) To really address the problem, we'll have to invent a new interface or provide an alternative abstract class that implementations will be required to use, or something. However, as an experiment, this class implements a couple of extra methods that we might wish had been in the interface. These methods are carefully identified as non-standard. Having them here really isn't all that useful because your underlying XPath implementation isn't likely to return instances of this class.

There are three ways to instantiate this class:

1. The no-argument constructor produces an initially empty namespace context.
2. Another constructor takes a prefix and URI and produces a namespace context with that binding.
3. Finally, there's a constructor that takes a hash of namespace/uri pairs and produces a namespace context with those initial bindings.
4. The obvious constructor, one that takes an existing NamespaceContext so that you can extend it, isn't there because you can't get the current bindings from that interface; see the aforementioned bug.

After the object has been instantiated, you can call the add(String,String) method to add additional bindings to the namespace context. Because I'm not sure how and where the XPath API implementations might save pointers to the context object, I've imposed a number of rules designed to make sure that the context remains coherent:

• Namespace bindings can only be added, not removed.
• Once a prefix is bound, its binding cannot be changed.
• The XML restrictions on the 'xml' prefix, the 'xmlns' prefix, and their respective namespace URIs are enforced.
• Namespace prefixes must be valid NCNames (or "" for the default namespace). Note that unprefixed element and attribute names in an XPath expression can never match a name that's in a namespace. In particular, setting the default namespace won't have that effect.

Even with these rules, you can't assume that the context is thread safe. Don't allow it to be changed while someone else is reading it.

Other notes:

• There's no getNamespaceURIs(String prefix) method because there can be at most one URI bound to any given prefix. Wrapping an interator around the mapping available with getNamespaceURI(String) seemed silly.
• This class relies on XML11Char to test that the prefixes are valid NCNames. Note that this means that they're valid XML 1.1 names. XML 1.1 names are a superset of XML 1.0 names and it didn't seem worth the extra effort that would be required to allow the user to choose XML 1.0 or XML 1.1. You might not think it's worth the effort to check at all. Fair enough.
• I've used generics here and there to make the JDK 1.5 compiler stop complaining. Just delete them for JDK 1.4 and everything should work fine.

See Also:

Java API for XML Processing, Namespaces in XML, Namespaces in XML Errata

Constructor Summary

NamespaceContextHelper()
Creates a new instance of NamespaceContextHelper.

NamespaceContextHelper(java.util.Hashtable initialNamespaces)
Creates a new instance of NamespaceContextHelper.

NamespaceContextHelper(java.lang.String prefix, java.lang.String uri)
Creates a new instance of NamespaceContextHelper.

Method Summary

void	add(java.lang.String prefix, java.lang.String uri) Adds a new prefix/uri binding to the namespace context.
java.lang.String	getNamespaceURI(java.lang.String prefix) Implements the NamespaceContext getNamespaceURI method.
java.util.Iterator	getNamespaceURIs() Implements a NON STANDARD method for finding all of the namespace URIs in the namespace context.
java.lang.String	getPrefix(java.lang.String namespaceURI) Implements the NamespaceContext getPrefix method.
java.util.Iterator	getPrefixes() Implements a NON STANDARD method for finding all of the prefixes in the namespace context.
java.util.Iterator	getPrefixes(java.lang.String namespaceURI) Implements the NamespaceContext getPrefixes method.

Methods inherited from class java.lang.Object

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

Constructor Detail

NamespaceContextHelper

public NamespaceContextHelper()

Creates a new instance of NamespaceContextHelper.

Creates an empty namespace context.

NamespaceContextHelper

public NamespaceContextHelper(java.util.Hashtable initialNamespaces)

Creates a new instance of NamespaceContextHelper.

Creates a namespace context with the bindings specified in initialNamespaces.

NamespaceContextHelper

public NamespaceContextHelper(java.lang.String prefix,
                              java.lang.String uri)

Creates a new instance of NamespaceContextHelper.

Creates a namespace context with the specified prefix bound to uri.

Method Detail

add

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

Adds a new prefix/uri binding to the namespace context.

Throws:

java.lang.NullPointerException - if the prefix or uri is null.

java.lang.IllegalArgumentException - if the caller attempts to change the binding of prefix, if the caller attempts to bind the prefix "xml" or the namespace "http://www.w3.org/XML/1998/namespace" incorrectly, if the caller attempts to bind the prefix "xmlns" or the namespace "http://www.w3.org/2000/xmlns", or if the prefix is not a valid NCName.

getNamespaceURI

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

Implements the NamespaceContext getNamespaceURI method.

Specified by:

getNamespaceURI in interface javax.xml.namespace.NamespaceContext

getPrefix

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

Implements the NamespaceContext getPrefix method.

Specified by:

getPrefix in interface javax.xml.namespace.NamespaceContext

getPrefixes

public java.util.Iterator getPrefixes()

Implements a NON STANDARD method for finding all of the prefixes in the namespace context.

Returns an iterator over all of the prefixes in the namespace context. Note that multiple prefixes may be bound to the same URI.

getPrefixes

public java.util.Iterator getPrefixes(java.lang.String namespaceURI)

Implements the NamespaceContext getPrefixes method.

Specified by:

getPrefixes in interface javax.xml.namespace.NamespaceContext

getNamespaceURIs

public java.util.Iterator getNamespaceURIs()

Implements a NON STANDARD method for finding all of the namespace URIs in the namespace context.

Returns an iterator over all of the namespace URIs in the namespace context. Note that each namespace URI is returned exactly once, even if it is bound to several different prefixes.