 |  |
| |
This appendix provides a quick reference to each of the SAX2 APIs presented in this book. It shows API signatures and provides a brief overview for each interface, class, and exception in alphabetical order.
Full documentation for these APIs is available for you to download or browse online at the SAX web site (http://sax.sourceforge.net/), and it should also be available with documentation for your SAX parser.
The org.xml.sax package holds the interfaces and exceptions that are at the core of SAX, including some deprecated SAX1 APIs.
This SAX1 interface is not used in SAX2; the Attributes interface, which supports namespace identifiers, is used instead.
For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".
public interface AttributeList
{
public int getLength();
public String getType(int index);
public String getValue(int index);
// access to name info
public String getName(int index);
// access by XML 1.0-style names
public String getType(String qName);
public String getValue(String qName);
}
This interface groups all the attributes associated with a given element in the ContentHandler.startElement() call. Attribute characteristics are frequently accessed using an indexed access model, though you can also determine the index, type, or value of an attribute given XML 1.0-style (qName) or namespace-style (uri, localName) versions of its name.
For more information, refer to Section 2.3.3, "The Attributes Interface " in Chapter 2, "Introducing SAX2".
public interface Attributes
{
public int getLength();
public String getType(int index);
public String getValue(int index);
// access to name info
public String getQName(int index);
public String getLocalName(int index);
public String getURI(int index);
// access by XML Namespace-style names
public int getIndex(String uri, String localName);
public String getType(String uri, String localName);
public String getValue(String uri, String localName);
// access by XML 1.0-style names
public int getIndex(String qName);
public String getType(String qName);
public String getValue(String qName);
}
This is the primary SAX2 handler interface, which is used in almost all applications.
For more information, refer to Section 2.3.4, "Essential ContentHandler Callbacks" and Section 2.6.4, "ContentHandler and Prefix Mappings", both in Chapter 2, "Introducing SAX2", as well as Section 4.1.1, "Other ContentHandler Methods " in Chapter 4, "Consuming SAX2 Events".
public interface ContentHandler
{
// bookkeeping
public void setDocumentLocator(Locator locator);
public void startDocument() throws SAXException;
public void endDocument() throws SAXException;
// content events
public void startElement(String uri, String localName, String qName,
Attributes attributes)
throws SAXException;
public void endElement(String uri, String localName, String qName)
throws SAXException;
public void characters(char buf[], int offset, int length)
throws SAXException;
public void processingInstruction(String target, String data)
throws SAXException;
// extra info
public void ignorableWhitespace(char buf[], int offset, int length)
throws SAXException;
public void startPrefixMapping(String prefix, String uri)
throws SAXException;
public void endPrefixMapping(String prefix) throws SAXException;
public void skippedEntity(String name) throws SAXException;
}
This SAX1 interface is not used in SAX2; the ContentHandler interface, which reports namespace identifiers and scopes as well as skipped entities, is used instead.
For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".
public interface DocumentHandler
{
// bookkeeping
public void setDocumentLocator(Locator locator);
public void startDocument() throws SAXException;
public void endDocument() throws SAXException;
// content events
public void startElement(String qName, AttributeList attributes)
throws SAXException;
public void endElement(String qName) throws SAXException;
public void characters(char buf[], int offset, int length)
throws SAXException;
public void processingInstruction(String target, String data)
throws SAXException;
// extra info
public void ignorableWhitespace(char buf[], int offset, int length)
throws SAXException;
}
This interface is used to report information that is useful to some SGML-derived applications.
For more information, refer to Section 4.3.2, "The DTDHandler Interface " in Chapter 4, "Consuming SAX2 Events".
public interface DTDHandler
{
public void notationDecl(String notationName,
String publicId, String systemId)
throws SAXException;
public void unparsedEntityDecl(String entityName,
String publicId, String systemId, String notationName)
throws SAXException;
}
This interface encapsulates a strategy for resolving public or system identifiers for parsed entities into data that a parser will read. It is commonly used to ensure that local copies of DTDs are used, instead of DTDs accessed across a network link that may be saturated or unavailable. It can resolve general entities, used to store non-DTD parts of a document in separate storage units.
For more information, refer to Section 3.4, "The EntityResolver Interface" in Chapter 3, "Producing SAX2 Events".
public interface EntityResolver
{
public InputSource resolveEntity(String publicId,
String systemId)
throws SAXException, java.io.IOException;
}
This interface encapsulates a strategy for handling different kinds of errors. Parsers use its methods when reporting errors, and have default policies that are used if the application's strategy doesn't result in throwing an exception. Applications can benefit from sharing the same mechanism to report their own errors. Implementations typically use the problem's severity to choose first whether to emit a diagnostic, and then whether to throw the parameter (to terminate processing) or return (to continue processing).
For more information, refer to Section 2.5.2, "ErrorHandler Interface" in Chapter 2, "Introducing SAX2".
public interface ErrorHandler
{
public void error(SAXParseException x) throws SAXException;
public void fatalError(SAXParseException x) throws SAXException;
public void warning(SAXParseException x) throws SAXException;
}
This SAX1 class is not used in SAX2; the org.xml.sax.helpers.Defaulthandler class, which supports SAX2 features, is used instead.
For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".
public class HandlerBase
implements EntityResolver, DTDHandler,
DocumentHandler, ErrorHandler
{
public HandlerBase();
// DocumentHandler (SAX1)
public void setDocumentLocator(Locator locator);
public void startDocument() throws SAXException;
public void endDocument() throws SAXException;
public void startElement(String qName,
AttributeList attributes)
throws SAXException;
public void endElement(String qName) throws SAXException;
public void characters(char buf[], int offset, length)
throws SAXException;
public void ignorableWhitespace(char buf[], int offset,
length)
throws SAXException;
public void processingInstruction(String target,
String data)
throws SAXException;
// DTDHandler ... NOTE: no "throws SAXException"!
public void notationDecl(String notationName,
String publicId, String publicId);
public void unparsedEntityDecl(String entityName,
String publicId, String publicId, notationName);
// EntityResolver
public InputSource resolveEntity(String publicId,
String publicId);
throws SAXException;
// ErrorHandler
public void error(SAXParseException x) throws SAXException;
public void fatalError(SAXParseException x) throws SAXException;
public void warning(SAXParseException x) throws SAXException;
}
This class is used to encapsulate entities for consumption by an XMLReader (or a SAX1 Parser). Applications should make every effort to provide a usable system identifier (an absolute URI, rather than null). This will ensure that relative URIs can be properly resolved so that diagnostics are meaningful. Given that identifier, SAX parsers can do the rest, possibly with assistance from an EntityResolver.
For more information, refer to Section 3.1.2, "The InputSource Class" in Chapter 3, "Producing SAX2 Events".
public class InputSource {
public InputSource();
public InputSource(String systemId);
public InputSource(java.io.InputStream in);
public InputSource(java.io.Reader in);
// getters
public String getPublicId();
public String getSystemId();
public java.io.InputStream getByteStream();
public String getEncoding();
public java.io.Reader getCharacterStream();
// setters
public void setPublicId(String publicId);
public void setSystemId(String systemId);
public void setByteStream(java.io.InputStream in);
public void setEncoding(String encodingName);
public void setCharacterStream(java.io.Reader in);
}
An event producer may invoke the ContentHandler.setDocumentLocator() call to provide one of these objects. It may then be used inside event callbacks, until the final ContentHandler.endDocument() call, to determine the location of the data that triggered the event. A common use is to figure out the base URI used to resolve relative URIs found in document content. This is true even when xml:base attributes have been used to override the real base URI of the document. Another common use is to construct SAXParseException objects to construct application-level diagnostics.
For more information, refer to Section 4.1.2, "The Locator Interface " in Chapter 4, "Consuming SAX2 Events".
public interface Locator
{
public String getPublicId();
public String getSystemId();
public int getLineNumber();
public int getColumnNumber();
}
This SAX1 interface is no longer used in SAX2; the XMLReader is used instead.
For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".
public interface Parser
{
// setters
public void setLocale(java.util.Locale locale)
throws SAXException;
public void setEntityResolver(EntityResolver resolver);
public void setDTDHandler(DTDHandler dtdHandler);
public void setDocumentHandler(DocumentHandler docHandler);
public void setErrorHandler(ErrorHandler errHandler);
// parsing
public void parse(InputSource in) throws SAXException,
java.io.IOException;
public void parse(String uri) throws SAXException,
java.io.IOException;
}
This is the base SAX exception class. It can wrap another exception, and (like most exceptions) a descriptive message.
For more information, refer to Section 2.5.1, "SAX2 Exception Classes" in Chapter 2, "Introducing SAX2".
public class SAXException extends Exception {
public SAXException(String message);
public SAXException(Exception cause);
public SAXException(String message, Exception cause);
// getters
public Exception getException();
public String getMessage();
}
This exception is used to report that the identifier for a feature flag, or parser property, is not recognized. When this doesn't indicate a mistyped identifier, it means that the parser isn't exposing that particular information.
For more information, refer to Section 2.5.1, "SAX2 Exception Classes" in Chapter 2, "Introducing SAX2".
public class SAXNotRecognizedException extends SAXException {
public SAXNotRecognizedException(String message);
}
This exception is used to report that while the identifier for a feature flag, or parser property, was recognized, setting the value was not practical. For example, read-only values can't be changed to nondefault values, handler properties need to implement the appropriate interface, and some values can't be changed while parsing, or accessed except while parsing.
For more information, refer to Section 2.5.1, "SAX2 Exception Classes" in Chapter 2, "Introducing SAX2".
public class SAXNotSupportedException extends SAXException {
public SAXNotSupportedException(String message);
}
This type of SAXException is reported to the ErrorHandler, and adds information that is useful for locating (and hence fixing) problems in input text. That information may include the line and character offset in the entity being parsed, the entity's URL, and any public identifier associated with the entity. When used to report application-level errors, any exception caused by problematic data can be encapsulated, and associated with such Locator information to help pinpoint problematic input data. It's safe to provide null Locator or Exception objects.
For more information, refer to Section 2.5.1, "SAX2 Exception Classes" as well as Section 2.5.3, "Errors and Diagnostics", which are both located in Chapter 2, "Introducing SAX2".
public class SAXParseException extends SAXException {
public SAXParseException(String message, Locator where);
public SAXParseException(String message, Locator where,
Exception cause);
public SAXParseException(String message,
String publicId, String systemId, int line, int column);
public SAXParseException(String message,
String publicId, String systemId, int line, int column,
Exception cause);
// getters
public String getPublicId();
public String getSystemId();
public int getLineNumber();
public int getColumnNumber();
}
This interface encapsulates the notion that one XMLReader may process the output of another one before delivering it. The XMLFilterImpl helper class is substantially more interesting, since it does the real work and can be used in a postprocessing mode as well.
For more information, refer to Section 3.5.4, "The XMLFilter Interface" in Chapter 3, "Producing SAX2 Events".
public interface XMLFilter extends XMLReader
{
public void setParent(XMLReader parent);
public XMLReader getParent();
}
A SAX2 "parser" will normally be packaged as an implementation of this interface. Such a parser often takes XML text as input, though it need not. Some parsers need a DOM Document as input, and others parse non-XML text and report it as if it were XML, to leverage the SAX event processing model.
For more information, refer to Section 3.1.1, "The XMLReader Interface" in Chapter 3, "Producing SAX2 Events". For quick reference to the standard SAX2 feature and property identifiers, refer to Section 3.3.2, "XMLReader Feature Flags" and Section 3.3.1, "XMLReader Properties", both in Chapter 3, "Producing SAX2 Events".
public interface XMLReader
{
// getters
public ContentHandler getContentHandler();
public DTDHandler getDTDHandler();
public EntityResolver getEntityResolver();
public ErrorHandler getErrorHandler();
public boolean getFeature(String uri)
throws SAXNotRecognizedException,
SAXNotSupportedException;
public Object getProperty(String uri)
throws SAXNotRecognizedException,
SAXNotSupportedException;
// setters
public void setContentHandler(ContentHandler contentHandelr);
public void setDTDHandler(DTDHandler dtdHandler);
public void setEntityResolver(EntityResolver resolver);
public void setErrorHandler(ErrorHandler errHandler);
public void setFeature(String uri, boolean value)
throws SAXNotRecognizedException,
SAXNotSupportedException;
public void setProperty(String uri, Object value)
throws SAXNotRecognizedException,
SAXNotSupportedException;
// parsing
public void parse(InputSource in)
throws java.io.IOException, SAXException;
public void parse(String uri)
throws java.io.IOException, SAXException;
}
|  | |
| 6.3. Including Subdocuments |  | A.2. The org.xml.sax.helpers Package |
Copyright © 2002 O'Reilly & Associates. All rights reserved.