API Reference (Java & XML, 2nd Edition)

This appendix is an API reference for the four lower-level Java and XML APIs covered in this book, SAX, DOM, JDOM, and JAXP. It is broken down into sections based on the API being documented.

A.1. SAX 2.0

SAX 2.0 provides a sequential look into an XML document. Detailed in Chapter 3, "SAX" and Chapter 4, "Advanced SAX ", SAX defines a set of interfaces that can be implemented and will be invoked as callbacks during the XML parsing process. The SAX packages are detailed here, with the classes and interfaces listed alphabetically. In the org.xml.sax.helpers package, most of the methods in the helper classes are implementations of interfaces already defined in the core SAX package (org.xml.sax).

A.1.1. Package: org.xml.sax

This package contains the core interfaces and classes for SAX 2.0. Most of the interfaces defined are intended to be implemented by you, the Java developer, with the exception of the actual XMLReader and Attributes implementation. These interfaces should be implemented by your vendor's XML parsing software. In addition, several exceptions that SAX methods are allowed to throw are defined. Several of the interfaces defined here are part of the SAX 1.0 and 2.0 alpha distributions, and are now deprecated.

A.1.1.1. AttributeList [deprecated]

This interface was defined in SAX 1.0, and is now deprecated. The Attributes interface should be used instead of AttributeList for SAX 2.0 implementations.

public interface AttributeList {
    public abstract int getLength( );
    public abstract String getName(int i);
    public abstract String getType(int i);
    public abstract String getValue(int i);
    public abstract String getType(String name);
    public abstract String getValue(String name);
}

A.1.1.2. Attributes

This interface represents a listing of XML attributes. It is reported to the callbacks associated with the start of element (startElement( ) in ContentHandler), and is somewhat analogous to a Java Vector. The number of attributes represented can be obtained, as well as various views of the attributes' names (local, namespace prefix and URI, and raw) and values. Additionally, methods are available for locating the index of an attribute given its name. The primary difference between this interface and its predecessor, AttributeList, is that this interface is namespace-aware.

public interface Attributes {
    public abstract int getLength( );
    public abstract String getURI(int index);
    public abstract String getLocalName(int index);
    public abstract String getQName(int index);
    public abstract String getType(int index);
    public abstract String getValue(int index);
    public int getIndex(String uri, String localName);
    public int getIndex(String qName);
    public abstract String getType(String uri, String localName);
    public abstract String getType(String qName);
    public abstract String getValue(String uri, String localName);
    public abstract String getValue(String qName);
}

A.1.1.3. ContentHandler

This interface defines the callback methods available to an application that deal with the content of the XML document being parsed. These include notification of the start and end of parsing (which precede and follow all other handler callbacks, respectively), processing instructions, and entities that may be skipped by nonvalidating parsers. Element callbacks, complete with namespace mappings, are also made available.

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 qName, Attributes atts)
        throws SAXException;
    public void endElement(String namespaceURI, String localName,
                              String qName)
        throws SAXException;
    public void characters(char ch[], int start, int length)
        throws SAXException;
    public void ignorableWhitespace(char ch[], int start, int length)
        throws SAXException;
    public void processingInstruction(String target, String data)
        throws SAXException;
    public void skippedEntity(String name)
        throws SAXException;
}

A.1.1.4. DocumentHandler

This interface was defined in SAX 1.0, and is now deprecated. The ContentHandler interface should be used instead of DocumentHandler for SAX 2.0 implementations.

public interface DocumentHandler {
    public abstract void setDocumentLocator(Locator locator);
    public abstract void startDocument( ) throws SAXException;
    public abstract void endDocument( ) throws SAXException;
    public abstract void startElement(String name, AttributeList atts)
               throws SAXException;
    public abstract void endElement(String name)
               throws SAXException;
    public abstract void characters(char ch[], int start, int length)
               throws SAXException;
    public abstract void ignorableWhitespace(char ch[], int start, int length)
               throws SAXException;
    public abstract void processingInstruction (String target, String data)
               throws SAXException;
}

A.1.1.5. DTDHandler

This interface defines callbacks that are invoked in the process of parsing a DTD. Note that this interface does not provide information about the constraints within the DTD, but instead about references to unparsed entities and NOTATION declarations, indicating items that are generally unparsed data.

public interface DTDHandler {
    public abstract void notationDecl(String name, String publicId,
                                      String systemId)
                 throws SAXException;
    public abstract void unparsedEntityDecl(String name, String publicId,
                                      String systemId,
                                      String notationName)
           throws SAXException;
}

A.1.1.6. EntityResolver

This interface allows applications to intervene in the process of referencing external entities, such as an XML document that references a DTD or stylesheet. By implementing this interface, a modified or even completely different SAX InputSource can be returned to the calling program. Additionally, null can be returned to indicate that a normal URI connection should be opened to the specified system ID.

public interface EntityResolver {
    public abstract InputSource resolveEntity(String publicId,
                                    String systemId)
             throws SAXException, IOException;
}

A.1.1.7. ErrorHandler

This interface allows custom behavior to be attached to the three types of problem conditions that can occur within the lifecycle of XML parsing. Each receives the SAXParseException indicating what problem initiated the callback. The SAXException is provided to allow a means of throwing an exception that could stop parsing altogether.

public interface ErrorHandler {
    public abstract void warning(SAXParseException exception)
               throws SAXException;
    public abstract void error(SAXParseException exception)
               throws SAXException;
    public abstract void fatalError(SAXParseException exception)
               throws SAXException;
}

A.1.1.8. HandlerBase

This helper class provides empty implementations of all the SAX 1.0 core handler interfaces, and can be extended to allow the quick addition of handlers by overriding methods with application-defined behavior. This class was defined in SAX 1.0, and is now deprecated. The org.xml.sax.helpers.DefaultHandler class should be used instead of HandlerBase for SAX 2.0 implementations.

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

        // EntityResolver implementation
        public InputSource resolveEntity(String publicId, String systemId);

        // DTDHandler implementation
        public void notationDecl(String name, String publicId, 
                             String systemId);
    public void unparsedEntityDecl(String name, String publicId,
                         String systemId, String notationName);

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

       // ErrorHandler implementation
    public abstract void warning(SAXParseException exception)
               throws SAXException;
    public abstract void error(SAXParseException exception)
               throws SAXException;
    public abstract void fatalError(SAXParseException exception)
               throws SAXException;
}

A.1.1.9. InputSource

This class encapsulates all information about a resource used in XML processing. This can be as little as a String or InputStream used for locating input, or as complex as an entity with a public ID and system ID as well as a URI reference (such as a DTD publicly defined). This class is the preferred wrapper for passing input into a SAX parser.

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 systemId);
    public String getSystemId( );
    public void setByteStream(InputStream byteStream);
    public InputStream getByteStream( );
    public void setEncoding(String encoding);
    public String getEncoding( );
    public void setCharacterStream(Reader characterStream);
    public Reader getCharacterStream( );
}

A.1.1.10. Locator

This class is a complement to an XML document or other parsed construct, as it provides the document's system ID and public ID as well as information about the location within the file being processed. This is particularly helpful for use in IDE applications and for identifying where errors occur in parsing.

public interface Locator {
    public abstract String getPublicId( );
    public abstract String getSystemId( );
    public abstract int getLineNumber( );
    public abstract int getColumnNumber( );
}

A.1.1.11. Parser

This interface was defined in SAX 1.0, and is now deprecated. The XMLReader interface should be used instead for SAX 2.0 implementations.

public interface Parser {
    public abstract void setLocale(Locale locale) throws SAXException;
    public abstract void setEntityResolver(EntityResolver resolver);
    public abstract void setDTDHandler(DTDHandler handler);
    public abstract void setDocumentHandler(DocumentHandler handler);
    public abstract void setErrorHandler(ErrorHandler handler);
    public abstract void parse(InputSource source)
              throws SAXException, IOException;
    public abstract void parse(String systemId)
              throws SAXException, IOException;
}

A.1.1.12. SAXException

This is the core exception thrown by SAX callbacks and parser implementations. Because it is often thrown as a result of other exceptions, it has a constructor that allows the passing in of a lower-level Exception as well as an accessor method to retrieve the originating Exception. It is also the base class for all other SAX Exception classes.

public class SAXException extends Exception {
     public SAXException(String message);
       public SAXException(Exception e);
       public SAXException(String message, Exception e);
       public String getMessage( );
       public Exception getException( );
       public String toString( );
}

A.1.1.13. SAXNotRecognizedException

This class provides a means for an XMLReader implementation to throw an error when an unrecognized identifier is received. This is most common in the setProperty( ) and setFeature( ) methods (as well as their accessor counterparts) when a URI is supplied about which the parser has no information.

public class SAXNotRecognizedException extends SAXException {
    public SAXNotRecognizedException(String message);
}

A.1.1.14. SAXNotSupportedException

This class provides a means for an XMLReader implementation to throw an error when an unsupported (but recognized) identifier is received. This is most common in the setProperty( ) and setFeature( ) methods (as well as their accessor counterparts) when a URI is supplied for which the parser has no supporting code.

public class SAXNotSupportedException extends SAXException {
    public SAXNotSupportedException(String message)
}

A.1.1.15. SAXParseException

This class represents exceptions that can occur during the parsing process. Information about the location of the error within the XML document is available through this class's accessor methods. The preferred means of supplying this information to the class is through a Locator, but the line and column number where problems occurred can be supplied directly through overloaded constructors. The system ID and public ID of the document with the problem are also made available to the class through various means in the constructors.

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

A.1.1.16. XMLFilter

This class is analogous to an XMLReader, but it obtains its events from another XMLReader rather than a static document or network resource. These filters can also be chained on each other. Their primary use is in modifying the output from a lower-level XMLReader in the chain, providing filtering of the data reported to callback methods before the final application receives notification of the data.

public interface XMLFilter extends XMLReader {
    public abstract void setParent(XMLReader parent);
    public abstract XMLReader getParent( );
}

A.1.1.17. XMLReader

This is the core interface that defines parsing behavior in SAX 2.0. Each vendor's XML parsing software package must include at least one implementation of this interface. It replaces the SAX 1.0 Parser interface by adding support for namespaces in a document's elements and attributes. In addition to providing an entry into parsing (with either a system ID or InputSource as input), it allows registering of the various handler interfaces that SAX 2.0 provides. The features and properties available to a SAX parser implementation are also set through this interface. A complete list of SAX core features and properties is contained in Appendix B, "SAX 2.0 Features and Properties".

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

A.1.2. Package: org.xml.sax.ext

This package provides extensions to the SAX core classes and interfaces. Specifically, additional handlers are defined for less common processing within the SAX parsing process. XMLReader implementations are not required to support these extension handlers.

A.1.2.1. DeclHandler

This interface defines callbacks that give specific information about DTD declarations. Element and attribute definitions invoke the appropriate callback with their names (and the element names for attributes) as well as constraint information. While this is a fairly rigid set of data for attributes, elements only receive a String with the constrained model as pure text. Additionally, internal and external entity reference notifications are defined.

public interface DeclHandler {
    public abstract void elementDecl(String name, String model)
              throws SAXException;
    public abstract void attributeDecl(String eName, String aName,
                                      String type, String valueDefault,
                                      String value)
              throws SAXException;
    public abstract void internalEntityDecl(String name, String value)
              throws SAXException;
    public abstract void externalEntityDecl(String name, String publicId,
                                               String systemId)
              throws SAXException;
}

A.1.2.2. LexicalHandler

This interface defines callbacks for various events that are at a document level in terms of processing, but do not affect the resulting data within the XML document. For example, the handling of a DTD declaration, comments, and entity references would invoke callbacks in implementations of this interface. Additionally, a callback is defined to signal when a CDATA section is started and ended (although the reported data will always remain the same).

public interface LexicalHandler {
    public abstract void startDTD(String name, String publicId,
                                  String systemId)
              throws SAXException;
    public abstract void endDTD( )
              throws SAXException;
    public abstract void startEntity(String name)
              throws SAXException;
    public abstract void endEntity(String name)
              throws SAXException;
    public abstract void startCDATA( )
              throws SAXException;
    public abstract void endCDATA( )
              throws SAXException;
    public abstract void comment(char ch[], int start, int length)
              throws SAXException;
}

A.1.3. Package: org.xml.sax.helpers

NOTE: In the classes in this package that are default implementations of core org.xml.sax interfaces, I have left out the repeated methods for brevity. Instead, I've simply added a comment indicating what interface's methods are implemented.

A.1.3.1. AttributeListImpl

This class provides a default implementation of the org.xml.sax.AttributeList interface, and is deprecated in SAX 2.0. It allows addition and removal of attributes as well as a clearing of the list.

public class AttributeListImpl implements AttributeList {
       public AttributeListImpl( );
       public AttributeListImpl(AttributeList atts);

       // Implementation of AttributeList interface

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

}

A.1.3.2. AttributesImpl

This class provides a default implementation of the org.xml.sax.Attributes interface. It allows addition and removal of attributes as well as a clearing of the list.

public class AttributesImpl implements Attributes {
       public AttributesImpl( );
       public AttributesImpl(Attributes atts);

       // Implementation of Attributes interface

       // Additional methods
    public void addAttribute(String uri, String localName, 
                             String qName, String type, String value);
    public void setAttribute(int index, String uri, String localName,
                              String qName, String type, String value);
       public void clear( );
}

A.1.3.3. DefaultHandler

This helper class provides empty implementations of all the SAX 2.0 core handler interfaces, and can be extended to allow for quick addition of handlers by only overriding methods with application-defined behavior. This replaces the SAX 1.0 org.xml.sax.HandlerBase class.

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

       // (Empty) Implementation of EntityResolver interface

       // (Empty) Implementation of DTDHandler interface

       // (Empty) Implementation of ContentHandler interface

       // (Empty) Implementation of ErrorHandler interface
}

A.1.3.4. LocatorImpl

This class provides a default implementation of the org.xml.sax.Locator interface. It also provides a means of directly setting the line and column numbers.

public class LocatorImpl implements Locator {
       public LocatorImpl( );
       public LocatorImpl(Locator locator);

       // Implementation of Locator interface

       // Additional methods
       public void setPublicId(String publicId);
       public void setSystemId(String systemId);
       public void setLineNumber(int lineNumber);
       public void setColumnNumber(int columnNumber);
}

A.1.3.5. NamespaceSupport

This encapsulates namespace behavior, allowing applications to not have to implement the behavior on their own (unless desired for performance reasons). It allows handling of namespace contexts in a stack fashion, and also provides the ability to process XML 1.0 names, retrieving their "namespace-aware" counterparts.

public class NamespaceSupport {
       public NamespaceSuport( );
       public void reset( );
    public void pushContext( );
    public void popContext( );
    public boolean declarePrefix(String prefix, String uri);
    public String [] processName(String qName, String parts[],
                                 boolean isAttribute);
    public String getURI(String prefix);
    public Enumeration getPrefixes( );
    public Enumeration getDeclaredPrefixes( );
}

A.1.3.6. ParserAdapter

This helper class wraps a SAX 1.0 Parser implementation and makes it behave like a 2.0 XMLReader implementation (making namespace support available). The only callback that does not behave normally is skippedEntity( ) in the ContentHandler interface; it is never invoked.

public class ParserAdapter implements XMLReader, DocumentHandler {
       public ParserAdapter( ) throws SAXException;
       public ParserAdapter(Parser parser);

       // Implementation of XMLReader interface

       // Implementation of DocumentHandler interface
}

A.1.3.7. ParserFactory

This class contains methods that dynamically create an instance of a Parser implementation from a specified class name, or if none is supplied, from a system property named "org.xml.sax.driver".

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

A.1.3.8. XMLFilterImpl

This class provides a default implementation of the org.xml.sax.XMLFilter interface.

public class XMLFilterImpl implements XMLFilter, EntityResolver, 
                                      DTDHandler, ContentHandler, 
                                      ErrorHandler {
       public XMLFilterImpl( );
       public XMLFilterImpl(XMLReader parent);

       // Implementation of XMLFilter interface

       // Implementation of XMLReader interface

       // Implementation of EntityResolver interface

       // Implementation of DTDHandler interface

       // Implementation of ContentHandler interface

       // Implementation of ErrorHandler interface
}

A.1.3.9. XMLReaderAdapter

This helper class wraps a SAX 2.0 XMLReader implementation and makes it behave like a 1.0 Parser implementation (making namespace support unavailable). The namespaces feature (http://xml.org/sax/features/namespaces) must be supported, or errors in parsing will occur.

public class XMLReaderAdapter implements Parser, ContentHandler {
       public XMLReaderAdapter ( ) throws SAXException;
       public XMLReaderAdapter (XMLReader xmlReader);

    // Implementation of Parser interface

       // Implementation of ContentHandler interface
}

A.1.3.10. XMLReaderFactory

This class contains methods that dynamically create an instance of an XMLReader implementation from a specified class name, or if none is supplied, from a system property named "org.xml.sax.driver".

final public class XMLReaderFactory {
    public static XMLReader createXMLReader( ) throws SAXException;
    public static XMLReader createXMLReader(String className)
              throws SAXException;
}

Appendix A. API Reference

Contents: