The org.xml.sax.helpers Package (SAX2)

A.2. The org.xml.sax.helpers Package

The org.xml.sax.helpers package holds support classes, including vendor-neutral bootstrapping support and some support for the original SAX1 APIs. These classes are in a sense optional but are provided by all widely available implementations. They're also required for conformance with Sun's JAXP API.

A.2.1. The AttributeListImpl Interface

This SAX1 class is not used in SAX2; the AttributesImpl class is used instead.

For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".

public class AttributeListImpl implements AttributeList {
    public AttributeListImpl();
    public AttributeListImpl(AttributeList original);
    // AttributeList (accessors only)
    public int getLength();
    public String getName(int index);
    public String getType(int index);
    public String getValue(int index);
    public String getType(String qName);
    public String getValue(String qName);
    // mutators
    public void setAttributeList(AttributeList original);
    public void addAttribute(String qName, String type, String value);
    public void removeAttribute(String qName);
    public void clear();
}

A.2.2. The AttributesImpl Class

This class can be a convenient way to snapshot attribute information using the copy constructor. Since the attributes provided by an event producer are only valid during the particular ContentHandler.startElement() call that provides them, applications may need such snapshots. The class also supports construction of arbitrary attribute sets for filtering or event production.

For more information, refer to Section 5.1.1, "The AttributesImpl Class " in Chapter 5, "Other SAX Classes".

public class AttributesImpl implements Attributes {
    public AttributesImpl();
    public AttributesImpl(Attributes original);
    // Attributes (accessors only)
    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 qName);
    public String getType(String uri, String localName);
    public String getType(String qName);
    public String getValue(String uri, String localName);
    public String getValue(String qName);
    // setters
    public void setLocalName(int index, String localName);
    public void setQName(int index, String qName);
    public void setType(int index, String type);
    public void setURI(int index, String uri);
    public void setValue(int index, String value);
    // mutators
    public void addAttribute(String uri, String localName, 
	String qName,
    		String type, String value);
    public void clear();
    public void removeAttribute(int index);
    public void setAttribute(int index, String, String, 
	String, String, String);
    public void setAttributes(Attributes original);
}

A.2.3. The DefaultHandler Class

This class provides stub implementations of all the standard SAX2 handlers, including ErrorHandler, and the EntityResolver. Those stub implementations do nothing, except that ErrorHandler.fatalError() throws its argument. Extension handler callbacks are not supported; if you need DeclHandler or LexicalHandler stubs you'll need to provide them yourself (perhaps by subclassing).

For more information, refer to Section 2.3.1, "The DefaultHandler Class" in Chapter 2, "Introducing SAX2".

public class DefaultHandler
    implements EntityResolver, DTDHandler, ContentHandler, 
	ErrorHandler
{
    public DefaultHandler();
    // ContentHandler
    public void setDocumentLocator(Locator locator);
    public void startDocument() throws SAXException;
    public void endDocument() throws SAXException;
    public void startElement(String uri, String localName,
	    String qName, 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 ignorableWhitespace(char buf[], int offset, 
	int length)
	throws SAXException;
    public void processingInstruction(String target, String data)
	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;
    // 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;
    // 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;
}

A.2.4. The LocatorImpl Class

This class can provide a convenient way to snapshot locator information. Since the locator provided by an event producer may report different values during each event callback, applications may need such snapshots.

For more information, refer to Section 5.1.2, "The LocatorImpl Class " in Chapter 5, "Other SAX Classes".

public class LocatorImpl implements Locator {
    public LocatorImpl();
    public LocatorImpl(Locator);
    // Locator
    public String getPublicId();
    public String getSystemId();
    public int getLineNumber();
    public int getColumnNumber();
    // setters
    public void setPublicId(String publicId);
    public void setSystemId(String systemId);
    public void setLineNumber(int line);
    public void setColumnNumber(int column);
}

A.2.5. The NamespaceSupport Class

This class helps implement stacks of XML namespace context data. It's mostly useful for applications that need to handle element or attribute names within document content (including attributes) or for parser writers.

For more information, refer to Section 5.1.3, "The NamespaceSupport Class " in Chapter 5, "Other SAX Classes".

public class NamespaceSupport {
    // fixed uri for the "xml" prefix 
    public static final String XMLNS;
    public NamespaceSupport();
    // manipulate binding stack
    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);
    // access currently visible prefix bindings
    public String getURI(String prefix);
    public java.util.Enumeration getPrefixes();
    public String getPrefix(String uri);
    public java.util.Enumeration getPrefixes(String uri);
    public java.util.Enumeration getDeclaredPrefixes();
}

A.2.6. The ParserAdapter Class

This class is used to convert SAX1 Parser objects into XMLReader objects by converting SAX1 event callbacks into SAX2 callbacks. It uses the NamespaceSupport class internally to track namespaces so it can report them for elements and attributes, as required by SAX2. If you need to make a SAX1 parser report handling of validation or external entities though feature flags, you can subclass ParserAdapter and override the appropriate methods.

For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".

public class ParserAdapter implements XMLReader, 
	DocumentHandler {
    public helpers.ParserAdapter() throws SAXException;
    public helpers.ParserAdapter(Parser sax1);
    // XMLReader getters
    public boolean getFeature(String uri)
	throws SAXNotRecognizedException, 
	SAXNotSupportedException;
    public ContentHandler getContentHandler();
    public DTDHandler getDTDHandler();
    public EntityResolver getEntityResolver();
    public ErrorHandler getErrorHandler();
    public Object getProperty(String uri)
	throws SAXNotRecognizedException, 
	SAXNotSupportedException;
    // XMLReader setters
    public void setContentHandler(ContentHandler contentHandler);
    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;
    // XMLReader parsing
    public void parse(String uri) throws java.io.IOException, 
	SAXException;
    public void parse(InputSource in) throws java.io.IOException, 
	SAXException;
    // DocumentHandler (internals -- don't use)
    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, int length)
	throws SAXException;
    public void ignorableWhitespace(char buf[], int offset, 
	int length)
	throws SAXException;
    public void processingInstruction(String target, 
	String data)
	throws SAXException;
}

A.2.7. The ParserFactory Class

This SAX1 interface is not used in SAX2; the XMLReaderFactory is used instead. The org.xml.sax.parser system property was used to configure the default SAX1 parser.

For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".

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.2.8. The XMLFilterImpl Class

This class implements all the standard SAX2 events received from its parent XMLReader by passing them on to the handlers (or EntityResolver) registered with it. It only supports filtering core events, because it ignores the two extension handlers for declaration and lexical events.

This means you can use it in two modes. First, it can be a base class for simple consumer pipelines, unless you need information that's provided using extension handlers. Second, you can package a filter with a parser, so it can produce events like an XMLReader that just happens to do a bit of extra work (such as cleaning up input data).

For more information, refer to Section 4.5.1, "The XMLFilterImpl Class " in Chapter 4, "Consuming SAX2 Events".

public class XMLFilterImpl
    implements XMLFilter, EntityResolver, DTDHandler,
	ContentHandler, ErrorHandler
{
    public XMLFilterImpl();
    public XMLFilterImpl(XMLReader parent);
    public void setParent(XMLReader parent);
    // EntityResolver
    public InputSource resolveEntity(String publicId, 
	String publicId);
	throws SAXException;
    // 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;
    // ContentHandler
    public void setDocumentLocator(Locator locator);
    public void startDocument() throws SAXException;
    public void endDocument() throws SAXException;
    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 ignorableWhitespace(char buf[], int offset, 
	int length)
	throws SAXException;
    public void processingInstruction(String target, String data)
	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;
    // ErrorHandler
    public void error(SAXParseException x) throws SAXException;
    public void fatalError(SAXParseException x) throws 
	SAXException;
    public void warning(SAXParseException x) throws SAXException;
    // XMLFilter
    public XMLReader getParent();
    // XMLReader
    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;
    public void setContentHandler(ContentHandler contentHandler);
    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;
    public void parse(InputSource in)
	throws java.io.IOException, SAXException;
    public void parse(String uri)
	throws java.io.IOException, SAXException;
}

A.2.9. The XMLReaderAdapter Class

This class is used to convert SAX2 XMLReader objects into Parser objects by converting SAX2 event callbacks into SAX1 callbacks.

For more information, refer to Section 5.2, "SAX1 Support " in Chapter 5, "Other SAX Classes".

public class XMLReaderAdapter implements Parser, 
	ContentHandler {
    public XMLReaderAdapter() throws SAXException;
    public XMLReaderAdapter(XMLReader reader);
    // Parser
    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);
    public void parse(String uri) throws java.io.IOException, 
	SAXException;
    public void parse(InputSource in) throws java.io.IOException, 
	SAXException;
    // ContentHandler (internals -- don't use)
    public void setDocumentLocator(Locator locator);
    public void startDocument() throws SAXException;
    public void endDocument() throws SAXException;
    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 ignorableWhitespace(char buf[], int offset, 
	int length)
	throws SAXException;
    public void processingInstruction(String target, 
	String data)
	throws SAXException;
    public void startPrefixMapping(String prefix, String uri);
    public void endPrefixMapping(String prefix);
    public void skippedEntity(String name) throws SAXException;
}

A.2.10. The XMLReaderFactory Class

This factory is the parser-independent bootstrapping API for SAX2. The reference implementation uses the org.xml.sax.driver system property (or META-INF/services/org.xml.sax.driver resource in the class path) to determine the package-qualified name of the environment's default implementation for the no-parameters call. Most implementations maintain that behavior, but some resource-constrained environments can use simpler policies with less configurability.

For more information, refer to Section 3.2.1, "The XMLReaderFactory Class" in Chapter 3, "Producing SAX2 Events".

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