The org.xml.sax.helpers Package (XML in a Nutshell, 2nd Edition)

25.2. The org.xml.sax.helpers Package

The org.xml.sax.helpers package contains support classes for the core SAX classes. These classes include factory classes used to build instances of particular org.xml.sax interfaces and default implementations of those interfaces.

The AttributesImpl Class

AttributesImpl is a default implementation of the Attributes interface that SAX parsers and filters may use. Besides the methods of the Attributes interface, this class offers manipulator methods so the list of attributes can be modified or reused. These methods allow you to take a persistent snapshot of an Attributes object in startElement( ) and construct or modify an Attributes object in a SAX driver or filter:

package org.xml.sax.helpers;

public class AttributesImpl implements Attributes {

    public AttributesImpl( );
    public AttributesImpl(Attributes atts);

    public int    getLength( );
    public String getURI(int index);
    public String getLocalName(int index);
    public String getQName(int index);
    public String getType(int index);
    public String getValue(int index);
    public int    getIndex(String uri, String localName);
    public int    getIndex(String qualifiedName);
    public String getType(String uri, String localName);
    public String getType(String qualifiedName);
    public String getValue(String uri, String localName);
    public String getValue(String qualifiedName);
    public void   clear( );
    public void   setAttributes(Attributes atts);
    public void   addAttribute(String uri, String localName,
     String qualifiedName, String type, String value);
    public void   setAttribute(int index, String uri, String localName,
     String qualifiedName, String type, String value);
    public void   removeAttribute(int index)
    public void   setURI(int index, String uri)
    public void   setLocalName(int index, String localName)
    public void   setQName(int index, String qualifiedName);
    public void   setType(int index, String type);
    public void   setValue(int index, String value);

}

The DefaultHandler Class

DefaultHandler is a convenience class that implements the EntityResolver, DTDHandler, ContentHandler, and ErrorHandler interfaces with do-nothing methods. You can subclass DefaultHandler and override methods for events to which you actually want to respond. You never have to use this class. You can always implement the interfaces directly instead. The pattern is similar to the adapter classes in the AWT, such as MouseAdapter and WindowAdapter:

package org.xml.sax.helpers;

public class DefaultHandler
 implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler {

  // Default implementation of the EntityResolver interface.
  public InputSource resolveEntity(String publicID, String systemID)
   throws SAXException {
    return null;
  }

  // Default implementation of the DTDHandler interface.
  public void notationDecl(String name, String publicID, String systemID)
   throws SAXException {}
  public void unparsedEntityDecl(String name, String publicID,
   String systemID, String notationName) throws SAXException{}

  // Default implementation of the ContentHandler interface.
  public void setDocumentLocator(Locator locator) {}
  public void startDocument( ) throws SAXException {}
  public void endDocument( ) throws SAXException {}
  public void startPrefixMapping(String prefix, String uri)
   throws SAXException {}
  public void endPrefixMapping(String prefix) throws SAXException {}
  public void startElement(String uri, String localName,
   String qualifiedName, Attributes attributes) throws SAXException {}
  public void endElement(String uri, String localName,
   String qualifiedName) throws SAXException {}
  public void characters(char[] text, int start, int length)
   throws SAXException {}
  public void ignorableWhitespace(char[] whitespace, int start,
   int length) throws SAXException {}
  public void processingInstruction(String target, String data)
   throws SAXException {}
  public void skippedEntity(String name) throws SAXException {}

  // Default implementation of the ErrorHandler interface.
  public void warning(SAXParseException ex) throws SAXException {}
  public void error(SAXParseException ex) throws SAXException {}
  public void fatalError(SAXParseException ex) throws SAXException {
    throw ex;
  }

}

The LocatorImpl Class

LocatorImpl is a default implementation of the Locator interface for the convenience of parser writers. You probably won't need to use it directly. Besides the constructors, it adds setter methods to set the public ID, system ID, line number, and column number returned by the getter methods declared in Locator:

package org.xml.sax.helpers;

public class LocatorImpl implements Locator {

    public LocatorImpl( );
    public LocatorImpl(Locator locator);

    public String getPublicId( );
    public String getSystemId( );
    public int    getLineNumber( );
    public int    getColumnNumber( );
    public void   setPublicId(String publicID);
    public void   setSystemId(String systemID);
    public void   setLineNumber(int lineNumber);
    public void   setColumnNumber(int columnNumber);

}

The NamespaceSupport Class

NamespaceSupport provides a stack that can track the namespaces in scope at various points in the document. To use it, push a new context at the beginning of each element's namespace mappings, and place it at the end of each element. Each startPrefixMapping( ) invocation should call declarePrefix( ) to add a new mapping to the NamespaceSupport object. Then at any point where you need to figure out to which URI a prefix is bound, you can call getPrefix( ). The empty string indicates the default namespace. The getter methods can then tell you the prefix that is mapped to any URI or the URI that is mapped to any prefix at each point in the document. If you reuse the same NamespaceSupport object for multiple documents, be sure to call reset( ) in between documents.

package org.xml.sax.helpers;

public class NamespaceSupport {

 public final static String XMLNS="http://www.w3.org/XML/1998/namespace";

  public NamespaceSupport( );

  public void        reset( );
  public void        pushContext( );
  public void        popContext( );
  public boolean     declarePrefix(String prefix, String uri);
  public String[]    processName(String qualifiedName, String[] parts,
   boolean isAttribute);
  public String      getURI(String prefix);
  public Enumeration getPrefixes( );
  public String      getPrefix(String uri);
  public Enumeration getPrefixes(String uri);
  public Enumeration getDeclaredPrefixes( );

}

The ParserAdapter Class

The ParserAdapter class uses the adapter design pattern to convert a SAX1 org.xml.sax.Parser object into a SAX2 org.xml.sax.XMLReader object. As more parsers support SAX2, this class becomes less necessary. Note that some SAX2 features are not available through an adapted SAX1 parser. For instance, a parser created with this adapter does not report skipped entities and does not support most features and properties, not even the core features and properties:

package org.xml.sax.helpers;

public class ParserAdapter implements XMLReader, DocumentHandler {

  public ParserAdapter( ) throws SAXException;
  public ParserAdapter(Parser parser);

  // Implementation of org.xml.sax.XMLReader.
  public void           setFeature(String name, boolean state)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public boolean        getFeature(String name)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public void           setProperty(String name, Object value)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public Object         getProperty(String name)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public void           setEntityResolver(EntityResolver resolver);
  public EntityResolver getEntityResolver( );
  public void           setDTDHandler(DTDHandler handler);
  public DTDHandler     getDTDHandler( );
  public void           setContentHandler(ContentHandler handler);
  public ContentHandler getContentHandler( );
  public void           setErrorHandler(ErrorHandler handler);
  public ErrorHandler   getErrorHandler( );
  public void parse(String systemID) throws IOException, SAXException;
  public void parse(InputSource input) throws IOException, SAXException;

  // Implementation of org.xml.sax.DocumentHandler.
  public void setDocumentLocator(Locator locator);
  public void startDocument( ) throws SAXException;
  public void endDocument( ) throws SAXException;
  public void startElement(String qualifiedName,
   AttributeList qualifiedAttributes) throws SAXException;
  public void endElement(String qualifiedName) throws SAXException;
  public void characters(char[] text, int start, int length)
   throws SAXException;
  public void ignorableWhitespace(char[] text, int start, int length)
   throws SAXException;
  public void processingInstruction(String target, String data)
   throws SAXException;

}

The XMLFilterImpl Class

XMLFilterImpl is invaluable for implementing XML filters correctly. An instance of this class sits between an XMLReader and the client application's event handlers. It receives messages from the reader and passes them to the application unchanged, and vice versa. However, by subclassing this class and overriding particular methods, you can change the events that are sent before the application gets to see them. You chain a filter to an XMLReader by passing the reader as an argument to the filter's constructor. When parsing, you invoke the filter's parse( ) method, not the reader's parse( ) method.

package org.xml.sax.helpers;

public class XMLFilterImpl implements XMLFilter, EntityResolver,
 DTDHandler, ContentHandler, ErrorHandler {

  public XMLFilterImpl( );
  public XMLFilterImpl(XMLReader parent);

  // Implementation of org.xml.sax.XMLFilter
  public void      setParent(XMLReader parent);
  public XMLReader getParent( );

  // Implementation of org.xml.sax.XMLReader
  public void           setFeature(String name, boolean state)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public boolean        getFeature(String name)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public void           setProperty(String name, Object value)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public Object         getProperty(String name)
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public void           setEntityResolver(EntityResolver resolver);
  public EntityResolver getEntityResolver( );
  public void           setDTDHandler(DTDHandler handler);
  public DTDHandler     getDTDHandler( );
  public void           setContentHandler(ContentHandler handler);
  public ContentHandler getContentHandler( );
  public void           setErrorHandler(ErrorHandler handler);
  public ErrorHandler   getErrorHandler( );
  public void parse(InputSource input) throws SAXException, IOException;
  public void parse(String systemID) throws SAXException, IOException

  // Implementation of org.xml.sax.EntityResolver
  public InputSource resolveEntity(String publicID, String systemID)
   throws SAXException, IOException;

  // Implementation of org.xml.sax.DTDHandler
  public void notationDecl(String name, String publicID, String systemID)
   throws SAXException;
  public void unparsedEntityDecl(String name, String publicID,
   String systemID, String notationName) throws SAXException;

  // Implementation of org.xml.sax.ContentHandler
  public void setDocumentLocator(Locator locator);
  public void startDocument( ) throws SAXException;
  public void endDocument( ) throws SAXException;
  public void startPrefixMapping(String prefix, String uri)
   throws SAXException;
  public void endPrefixMapping(String prefix) throws SAXException;
  public void startElement(String namespaceURI, String localName,
   String qualifiedName, Attributes atts) throws SAXException;
  public void endElement(String namespaceURI, String localName,
   String qualifiedName) throws SAXException;
  public void characters(char[] text, int start, int length)
   throws SAXException;
  public void ignorableWhitespace(char[] text, int start, int length)
   throws SAXException;
  public void processingInstruction(String target, String data)
   throws SAXException;
  public void skippedEntity(String name) throws SAXException;

  // Implementation of org.xml.sax.ErrorHandler
  public void warning(SAXParseException ex) throws SAXException;
  public void error(SAXParseException ex) throws SAXException;
  public void fatalError(SAXParseException ex) throws SAXException;

}

The XMLReaderAdapter Class

XMLReaderAdapter is the reverse of ParserAdapter; it uses the Adapter design pattern to adapt a SAX2 XMLReader to a SAX1 Parser. This lets you use SAX2 parsers for legacy programs written to a SAX1 interface:

package org.xml.sax.helpers;

public class XMLReaderAdapter implements Parser, ContentHandler {

  public XMLReaderAdapter( ) throws SAXException;
  public XMLReaderAdapter(XMLReader reader);

  // Implementation of org.xml.sax.Parser.
  public void setLocale(Locale locale) throws SAXException;
  public void setEntityResolver(EntityResolver resolver);
  public void setDTDHandler(DTDHandler handler);
  public void setDocumentHandler(DocumentHandler handler);
  public void setErrorHandler(ErrorHandler handler);
  public void parse(String systemID) throws IOException, SAXException;
  public void parse(InputSource input) throws IOException, SAXException

  // Implementation of org.xml.sax.ContentHandler.
  public void setDocumentLocator(Locator locator);
  public void startDocument( ) throws SAXException;
  public void endDocument( ) throws SAXException;
  public void startPrefixMapping(String prefix, String uri)
   throws SAXException;
  public void endPrefixMapping(String prefix) throws SAXException;
  public void startElement(String namespaceURI, String localName,
   String qualifiedName, Attributes atts) throws SAXException;
  public void endElement(String namespaceURI, String localName,
   String qualifiedName) throws SAXException;
  public void characters(char[] text, int start, int length)
   throws SAXException;
  public void ignorableWhitespace(char[] text, int start, int length)
   throws SAXException;
  public void processingInstruction(String target, String data)
   throws SAXException;
  public void skippedEntity(String name) throws SAXException;

}

The XMLReaderFactory Class

XMLReaderFactory creates XMLReader instances in a parser-independent manner. The noargs createXMLReader( ) method instantiates the class named by the org.xml.sax.driver system property. The other createXMLReader( ) method instantiates the class named by its argument. This argument should be a fully packaged qualified name, such as org.apache.xerces.parsers.SAXParser:

package org.xml.sax.helpers;

public final class XMLReaderFactory {

  public static XMLReader createXMLReader( ) throws SAXException;
  public static XMLReader createXMLReader(String className)
   throws SAXException;

}