This appendix is a quick reference to the major Java and XML APIs, SAX and DOM. It also includes a complete API reference for JDOM, covered in Chapter 8, and the rest of the book. It is broken down into sections based on the API being documented.
SAX 2.0 provides a sequential look into an
XML document. Detailed in Chapter 3, and Chapter 5, 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, a large percentage of
the available methods in the helper classes are implementations of
interfaces already defined in the core SAX package
(org.xml.sax
). For the sake of brevity, these
duplicate method definitions will be omitted in the helper classes,
and instead a comment will be included noting that an
interface’s methods are implemented.
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.
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); }
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 getRawName (int index); public abstract String getType (int index); public abstract String getValue (int index); public int getIndex (String uri, String localPart); public int getIndex (String rawName); public abstract String getType (String uri, String localName); public abstract String getType (String rawName); public abstract String getValue (String uri, String localName); public abstract String getValue (String rawName); }
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 non-validating parsers. Element callbacks, complete with namespace mappings, are also made available. Complete coverage of this interface is included in Chapter 3.
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 rawName, Attributes atts) throws SAXException; public void endElement (String namespaceURI, String localName, String rawName) 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; }
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; }
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. Complete coverage of this interface is
included in Chapter 5.
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; }
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; }
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. Complete coverage of this interface is included
in Chapter 3 and Chapter 5.
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; }
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; }
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 ( ); }
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. Complete coverage of this interface is included in Chapter 3.
public interface Locator { public abstract String getPublicId ( ); public abstract String getSystemId ( ); public abstract int getLineNumber ( ); public abstract int getColumnNumber ( ); }
This interface was defined in SAX 1.0, and is
now deprecated. The XMLReader
interface should be
used instead of this one 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; }
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 ( ); }
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); }
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) }
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 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 ( ); }
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 ( ); }
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. Complete coverage of this interface is
included in Chapter 3, and a complete list of SAX
core features and properties is contained in Appendix B.
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; }
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.
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; }
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; }
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.
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 ( ); }
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 rawName, String type, String value); public void setAttribute (int index, String uri, String localName, String rawName, String type, String value); public void clear ( ); }
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 }
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); }
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 rawName, String parts[], boolean isAttribute); public String getURI (String prefix); public Enumeration getPrefixes ( ); public Enumeration getDeclaredPrefixes ( ); }
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 will not behave normally
is skippedEntity( )
in the
ContentHandler
interface; it will never be
invoked.
public class ParserAdapter implements XMLReader, DocumentHandler { public ParserAdapter ( ) throws SAXException; public ParserAdapter (Parser parser); // Implementation of XMLReader interface // Implementation of DocumentHandler interface }
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; }
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 }
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 }
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; }
18.116.65.130