The AttributeList interface was used in SAX1 to pass attribute sets to the startElement() method of DocumentHandler. It is now deprecated and should not be used.

package org.xml.sax;

public interface AttributeList  {

  public int    getLength();
  public String getName(int i);
  public String getType(int i);
  public String getValue(int i);
  public String getType(String name);
  public String getValue(String name);

}

The Attributes interface is used to pass attribute sets to the startElement() method of ContentHandler Although list-like, indexed access is supported for convenience, there is absolutely no guarantee that the attributes will be stored in the list in the order they appear in the start-tag. Indeed, in practice it’s more likely than not that they aren’t. If the attribute is declared to have any type other than CDATA (e.g., ID, NMTOKENS, enumerated, etc.) and the parser has read the DTD, then the reported value is normalized; that is, leading and trailing whitespace is trimmed and runs of whitespace are converted to single space. The unnormalized value will not be available. Undeclared attributes are not normalized.

package org.xml.sax;

public interface Attributes  {

  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);

}

ContentHandler is the basic callback interface a client application implements in order to receive information from the parser. Client applications register an instance of this interface with the parser using the setContentHandler() method in XMLReader. The parser will invoke the methods in that object in the same order that the corresponding markup and text appears in the original document.

package org.xml.sax;

public interface 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[] space, int start, int length)
   throws SAXException;
  public void processingInstruction(String target, String data) throws SAXException;
  public void skippedEntity(String name) throws SAXException;

}

DTDHandler is a callback interface a client application can implement and register with the XMLReader using the setDTDHandler() method if it wishes to receive information from the parser about notations and unparsed entities declared in the DTD. These methods will be called sometime after startDocument() and sometime before the startElement() method for the root element. You'll generally store the information in some data structure such as a Map so you can refer back to it when you an encounter an attribute with type NOTATION or ENTITY.

package org.xml.sax;

public interface 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;

}

DocumentHandler is the SAX1 equivalent of ContentHandler. It is now deprecated and should not be used.

package org.xml.sax;

public interface DocumentHandler  {

  public void setDocumentLocator(Locator locator);
  public void startDocument() throws SAXException;
  public void endDocument() throws SAXException;
  public void startElement(String name, AttributeList atts) 
   throws SAXException;
  public void endElement(String name) throws SAXException;
  public void characters(char[] text, int start, int length) 
   throws SAXException;
  public void ignorableWhitespace(char[] space, int start, int length) 
   throws SAXException;
  public void processingInstruction(String target, String data) 
   throws SAXException;

}

A client program can implement the EntityResolver interface to substitute different sources for entities referenced in the main document by public or system ID. A specific instance of EntityResolver is registered with the parser by passing it to the setEntityResolver() method in XMLReader. If resolveEntity() cannot locate a requested entity, it should return null to tell the parser to use its default entity resolution mechanism.

package org.xml.sax;

public interface EntityResolver  {

  public InputSource resolveEntity(String publicID, 
   String systemID) throws SAXException, IOException;

}

ErrorHandler is a callback interface parsers use to report the three levels of errors that may be encountered while parsing an XML document: a fatal well-formedness error, a non-fatal error such as a validity violation, and a warning. Parsers normally stop parsing the current document after reporting a fatal error. That is, the parser calls endDocument() and the parse() method returns. If you want the same behavior from a non-fatal error, you should rethrow the exception from inside the error() method. You install a specific instance of this interface by passing it to the setErrorHandler() method in XMLReader.

package org.xml.sax;

public interface ErrorHandler  {

  public void warning(SAXParseException ex) throws SAXException;
  public void error(SAXParseException ex) throws SAXException;
  public void fatalError(SAXParseException ex) 
   throws SAXException;

}

HandlerBase is the SAX1 equivalent of DefaultHandler, that is an adapter class that provides do-nothing implementations of the SAX1 callback interfaces. It is now deprecated and should not be used.

package org.xml.sax;

public class HandlerBase implements EntityResolver, 
 DTDHandler, DocumentHandler, ErrorHandler {

  public HandlerBase();

  // EntityResolver methods
  public InputSource resolveEntity(String publicID, 
   String systemID) throws SAXException;

  // DTDHandler methods
  public void notationDecl(String name, String publicID,
   String systemID);
  public void unparsedEntityDecl(String name, String publicID,
   String systemID, String notationName);

  // DocumentHandler methods
  public void setDocumentLocator(Locator locator);
  public void startDocument() throws SAXException;
  public void endDocument() throws SAXException;
  public void startElement(String name, AttributeList attributes)
   throws SAXException;
  public void endElement(String name) throws SAXException;
  public void characters(char[] text, int start, int length) 
   throws SAXException;
  public void ignorableWhitespace(char[] space, int start, int length) 
   throws SAXException;
  public void processingInstruction(String target, String data) 
   throws SAXException;

  // ErrorHandler methods
  public void warning(SAXParseException ex) throws SAXException;
  public void error(SAXParseException ex) throws SAXException;
  public void fatalError(SAXParseException ex)
   throws SAXException;

}

InputSource is a wrapper for all the different things that may contain an XML document including URLs, InputStreams, and Readers. An InputSource should be configured with a system ID URL and either an InputStream or a Reader.

package org.xml.sax;

public class InputSource  {

  public InputSource();
  public InputSource(String systemID);
  public InputSource(InputStream byteStream);
  public InputSource(Reader characterStream);

  public void        setPublicId(String publicID);
  public String      getPublicId();
  public void        setSystemId(String url);
  public String      getSystemId();
  public void        setByteStream(InputStream in);
  public InputStream getByteStream();
  public void        setEncoding(String encoding);
  public String      getEncoding();
  public void        setCharacterStream(Reader in);
  public Reader      getCharacterStream();

}

You should always set the system ID for an InputSource. If nothing else is set, then the parser will read the document from that URL. You may also set either the byte stream or the character stream, in which case that will be used to read the document. If you set both the byte stream and the character stream, then the parser will read from the character stream.

Many parsers pass a Locator object to the setLocator() method of ContentHandler before they call startDocument(). If a parser does this (and it’s not required to), client applications can use that Locator object to determine in which entity at which line and column a particular event occurs. The location information returned is not guaranteed to be perfectly accurate, but it’s normally close enough to help in debugging.

package org.xml.sax;

public interface Locator  {

  public String getPublicId();
  public String getSystemId();
  public int    getLineNumber();
  public int    getColumnNumber();

}

Parser is the SAX1 class that represents an XML parser. Modern programs should use SAX2’s XMLReader instead.

package org.xml.sax;

public interface 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(InputSource source) 
   throws SAXException, IOException;
  public void parse(String systemID)
   throws SAXException, IOException;

}

XMLFilter is an XMLReader that receives its content from another XMLReader rather than directly from a parsed document. Thus it has the opportunity to modify, log, replace, or otherwise manipulate the content the parser sends. However, most of the time it is much easier to write a filter by subclassing the org.xml.sax.helpers.XMLFilterImpl class rather than by implementing this interface directly.

package org.xml.sax;

public interface XMLFilter implements XMLReader {

  public void      setParent(XMLReader parent);
  public XMLReader getParent();

}

XMLReader is SAX2’s representation of an XML parser. It has methods to get and set features and properties, to configure the parser with the various handler classes, and to parse documents from an InputSource or a URL.

package org.xml.sax;

public interface XMLReader  {

  public boolean getFeature(String name) 
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public void    setFeature(String name, boolean value) 
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public Object  getProperty(String name) 
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public void    setProperty(String name, Object value) 
   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 IOException, SAXException;
  public void parse(String systemID) 
   throws IOException, SAXException;

}

All SAX exceptions are checked exceptions and all are derived from org.xml.sax.SAXException. In addition, a few methods that perform I/O can also throw an IOException.

package org.xml.sax;

public class SAXException extends Exception {

  public SAXException(String message);
  public SAXException(Exception ex);
  public SAXException(String message, Exception ex);

  public String    getMessage();
  public Exception getException();
  public String    toString();

}

package org.xml.sax;

public class SAXNotRecognizedException extends SAXException {

  public SAXNotRecognizedException(String message);

}

package org.xml.sax;

public class SAXNotSupportedException extends SAXException {

  public SAXNotSupportedException(String message);

}

package org.xml.sax;

public class SAXParseException extends SAXException {

  public SAXParseException(String message, Locator locator);
  public SAXParseException(String message, Locator locator, 
   Exception e);
  public SAXParseException(String message, String publicID, 
   String systemID, int lineNumber, int columnNumber);
  public SAXParseException(String message, String publicID, 
   String systemID, int lineNumber, int columnNumber,
   Exception e);

  public String getPublicId();
  public String getSystemId();
  public int    getLineNumber();
  public int    getColumnNumber();

}

DeclHandler is a callback interface client applications can implement and register with the parser in order to receive notification of element, attribute, and parsed entity declarations. Parsers are not required to provide this information, but most validating parsers do. If a LexicalHandler is also installed, then all calls to these methods occur in between the calls to startDTD() and endDTD().

A DeclHandler is installed in an XMLReader as the value of the http://xml.org/sax/properties/declaration-handler property with the setProperty() method. Parsers that do not provide declaration events will throw a SAXNotRecognizedException when you do this.

package org.xml.sax.ext;

public interface DeclHandler  {

  public void elementDecl(String name, String model) 
   throws SAXException;
  public void attributeDecl(String elementName, 
   String attributeName, String type, String valueDefault, 
   String value) throws SAXException;
  public void internalEntityDecl(String name, String value) 
   throws SAXException;
  public void externalEntityDecl(String name, String publicID, 
   String systemID) throws SAXException;

}

LexicalHandler is a callback interface client applications can implement and register with the parser in order to receive notification of lexical information such as comments, parsed entities, and CDATA section boundaries. Parsers are not required to provide lexical information, though most do. In normal usage, this interface is not common. Excessive reliance on it often indicates a misdesigned XML application.

A LexicalHandler is installed in an XMLReader as the value of the http://xml.org/sax/properties/lexical-handler property with the setProperty() method. Parsers that do not provide lexical events will throw a SAXNotRecognizedException when you do this.

package org.xml.sax.ext;

public interface LexicalHandler  {

  public void startDTD(String name, String publicID, 
   String systemID) throws SAXException;
  public void endDTD() throws SAXException;
  public void startEntity(String name) throws SAXException;
  public void endEntity(String name) throws SAXException;
  public void startCDATA() throws SAXException;
  public void endCDATA() throws SAXException;
  public void comment(char[] text, int start, int length) 
   throws SAXException;

}

The legacy AttributeListImpl class is a SAX1 class that parser vendors may (or may not) use to implement the AttributesList interface. There’s little to no need for this in SAX2.

package org.xml.sax.helpers;

public class AttributeListImpl implements AttributeList {

  public AttributeListImpl();
  public AttributeListImpl(AttributeList atts);

  public int    getLength();
  public String getName(int i);
  public String getType(int i);
  public String getValue(int i);
  public String getType(String name);
  public String getValue(String name);

  public void   setAttributeList(AttributeList atts);
  public void   addAttribute(String name, String type, 
   String value);
  public void   removeAttribute(String name);
  public void   clear();

}

AttributesImpl is a class that parser vendors may (or may not) use to implement the Attributes interface. It can also be useful for taking persistent snapshots of Attributes objects and modifying Attributes lists in filters.

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 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);

  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);

}

DefaultHandler is an adapter class that implements the four required SAX2 callback interfaces—EntityResolver, DTDHandler, ContentHandler, and ErrorHandler— with do-nothing implementations of all their methods. It’s often more convenient to subclass this class rather than implement those interfaces directly.

package org.xml.sax.helpers;

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

  public DefaultHandler();

  // EntityResolver methods
  public InputSource resolveEntity(String publicID, 
   String systemID) throws SAXException;
 
  // DTDHandler methods
  public void notationDecl(String name, String publicID, 
   String systemID) throws SAXException;
  public void unparsedEntityDecl(String name, String publicID, 
   String systemID, String notationName) throws SAXException;

  // ContentHandler methods
  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[] space, int start, int length) 
   throws SAXException;
  public void processingInstruction(String target, String data) 
   throws SAXException;
  public void skippedEntity(String name) throws SAXException;

  // ErrorHandler methods
  public void warning(SAXParseException e) throws SAXException;
  public void error(SAXParseException e) throws SAXException;
  public void fatalError(SAXParseException e) throws SAXException;

}

LocatorImpl is a class that parser vendors may take advantage of to help them provide the optional Locator interface. There’s little reason for most developers to use it, though it may occasionally be useful if you want to provide pseudo-location information from a filter or non-parser-based XMLReader or you want to take a persistent snapshot of location information at some point in the parse process.

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 provides a stack for storing namespace prefix-URI mappings. It’s useful when a program needs to resolve namespace prefixes that occur in attribute values and element content. You can reuse a NamespaceSupport object for multiple documents. However, if you do so, you need to call reset() in between documents (typically in startDocument()).

package org.xml.sax.helpers;

public class NamespaceSupport  {

  public static final String XMLNS;

  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();

}

ParserAdapter uses the adapter design pattern to convert SAX1 Parser objects into SAX2 XMLReader objects. Given the large number of high-quality, native SAX2 parsers that are now available, there’s little reason to use this class anymore.

package org.xml.sax.helpers;

public class ParserAdapter implements XMLReader, DocumentHandler {

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

  // XMLReader methods
  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;

  // DocumentHandler methods
  public void setDocumentLocator(Locator locator);
  public void startDocument() throws SAXException;
  public void endDocument() throws SAXException;
  public void startElement(String qualifiedName, 
   AttributeList qAtts) throws SAXException;
  public void endElement(String qualifiedName) 
   throws SAXException;
  public void characters(char[] text, int start, int length) 
   throws SAXException;
  public void ignorableWhitespace(char[] space, int start, int length) 
   throws SAXException;
  public void processingInstruction(String target, String data) 
   throws SAXException;

}

ParserFactory is a factory class used to create implementation specific instances of the SAX1 Parser class. The default implementation is determined by the org.xml.sax.parser Java system property. ParserFactory is now deprecated like the rest of SAX1, and should not be used.

package org.xml.sax.helpers;

public class ParserFactory  {

  public static Parser makeParser() 
   throws ClassNotFoundException, IllegalAccessException, 
          InstantiationException, NullPointerException, 
          ClassCastException;
  public static Parser makeParser(String className) 
   throws ClassNotFoundException, IllegalAccessException, 
          InstantiationException, ClassCastException;

}

Although there is a more generic XMLFilter interface, XMLFilterImpl is the class you should actually subclass to implement SAX filters. The parent XMLReader is the object from which the filter will receive its information. By default, all the methods in this class simply delegate to the parent’s equivalent methods or objects. However, you can override any or all of them to perform the filtering.

package org.xml.sax.helpers;

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

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

  public void      setParent(XMLReader parent);
  public XMLReader getParent();

  // XMLReader methods
  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;

  // EntityResolver methods
  public InputSource resolveEntity(String publicID, 
   String systemID) throws SAXException, IOException;

  // DTDHandler methods
  public void notationDecl(String name, String publicID,
   String systemID) throws SAXException;
  public void unparsedEntityDecl(String name, String publicID, 
   String systemID, String notationName) throws SAXException;

  // ContentHandler methods
  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 atts) 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[] space, int start, int length) 
   throws SAXException;
  public void processingInstruction(String target, String data) 
   throws SAXException;
  public void skippedEntity(String name) throws SAXException;

  // ErrorHandler methods
  public void warning(SAXParseException e) throws SAXException;
  public void error(SAXParseException e) throws SAXException;
  public void fatalError(SAXParseException e) 
   throws SAXException;

}

XMLReaderAdapter uses the adapter design pattern to convert SAX2 XMLReader objects into SAX1 Parser objects for compatibility with legacy code.

package org.xml.sax.helpers;

public class XMLReaderAdapter implements Parser, ContentHandler {

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

  // Parser methods
  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;

  // ContentHandler methods
  public void setDocumentLocator(Locator locator);
  public void startDocument() throws SAXException;
  public void endDocument() throws SAXException;
  public void startPrefixMapping(String prefix, String uri);
  public void endPrefixMapping(String prefix);
  public void startElement(String uri, String localName, 
   String qualifiedName, Attributes atts) 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[] space, int start, int length) 
   throws SAXException;
  public void processingInstruction(String target, String data) 
   throws SAXException;
  public void skippedEntity(String name) throws SAXException;

}

XMLReaderFactory is a factory class used to create implementation specific instances of XMLReader. The default implementation is determined by the org.xml.sax.driver Java system property.

package org.xml.sax.helpers;

public final class XMLReaderFactory  {

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

}