SAX2 Namespace Support

This document is in the Public Domain.

SAX2 adds XML Namespace support, which is required for higher-level standards like XSL, XML Schemas, RDF, and XLink. Every implementation of the SAX2 XMLReader interface is required to support Namespace processing as its default state; some XML readers may also allow Namespace processing to be disabled or modified (note to SAX driver writers: there is a helper class, NamespaceSupport, that can do most of the work of Namespace processing for you).

Namespace processing affects only element and attribute names. Without Namespace processing, each XML element and attribute has a single, local name (called the qName), which may contain a colon; with Namespace processing, each element and attribute has a two-part name, consisting of an optional URI (equivalent to a Java or Perl package name) followed by a local name which may not contain a colon.

SAX is capable of supporting either of these views or both simultaneously, though XML readers are required to support only the Namespaces view, and most applications will not need anything further.

1. Namespaces in SAX Events

Namespace support affects the ContentHandler and Attributes interfaces.

1.1. Element names

In SAX2, the startElement and endElement callbacks in a content handler look like this:

public void startElement (String uri, String localName,
                          String qName, Attributes atts)
  throws SAXException;

public void endElement (String uri, String localName, String qName)
  throws SAXException;

By default, an XML reader will report a Namespace URI and a local name for every element, in both the start and end handler. Consider the following example:

  <html:hr xmlns:html="http://www.w3.org/1999/xhtml"/>

With the default SAX2 Namespace processing, the XML reader would report a start and end element event with the Namespace URI "http://www.w3.org/1999/xhtml" and the local name "hr". The XML reader might also report the original qName "html:hr", but that parameter might simply be an empty string.

1.2. Attribute Names

For attributes, you can look up the value of a named attribute using the getValue method, and you can look up the Namespace URI or local name of an attribute by its index using the getURI and getLocalName methods (usually when you're iterating through the entire attribute list):

String rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
String resource = atts.getValue(rdfns, "resource");

for (int i = 0; i < atts.getLength(); i++) {
  String uri = atts.getURI(i);
  String localName = atts.getLocalName(i);
  String value = atts.getValue(i);
  /* ... */
}

1.3. Prefix Mappings

In addition to those events, SAX2 reports the scope of Namespace declarations using the startPrefixMapping and endPrefixMapping methods, so that applications can resolve prefixes in attribute values or character data if necessary. The callbacks look like this:

public void startPrefixMapping (String prefix, String uri)
  throws SAXException;
public void endPrefixMapping (String prefix)
  throws SAXException;

For the above example, the XML reader would make the following callback before the start-element event:

startPrefixMapping("html", "http://www.w3.org/1999/xhtml")

The XML reader would make the following callback after the end-element event:

endPrefixMapping("html")

The rest of this document applies only to SAX2 applications with special requirements, such as text editors.

2. Configuration

2.1. Configuring Namespace Support

The "http://xml.org/features/namespaces" feature controls general Namespace processing: when this feature is true (the default), Namespace URIs and local names must be available through the startElement and endElement callbacks in the ContentHandler interface, and through the various methods in the Attributes interface, and start/endPrefixMapping events must be reported.

The "http://xml.org/features/namespace-prefixes" feature controls the reporting of qNames and Namespace declarations (xmlns* attributes): when this feature is false (the default), qNames may optionally be reported, and xmlns* attributes must not be reported.

The following table summarizes the interaction of these two features (for general information on using features, see SAX2: Features and Properties):

namespaces namespace-prefixes Namespace names start/endPrefixMapping qNames xmlns* attributes
true false YES YES unknown NO
true true YES YES YES YES
false false (ILLEGAL COMBINATION)
false true unknown unknown YES YES

Note xmlns* attributes will not be reported unless the namespace-prefixes feature is true (it is false by default).

2.2. Configuration Example

Consider the following simple sample document:

<?xml version="1.0"?>

<h:hello xmlns:h="http://www.greeting.com/ns/" id="a1" h:person="David"/>

If namespaces is true and namespace-prefixes is false (the default), then a SAX2 XML reader will report the following:

If namespaces is true and namespace-prefixes is true, then a SAX2 XML reader will report the following:

If namespaces is false and namespace-prefixes is true, then a SAX2 XML reader will report the following:

$Id$