 |  |
25.2. The org.xml.sax.helpers Package
The org.xml.sax.helpers package contains support classes for the core SAX classes. These classes include factory classes used to build instances of particular org.xml.sax interfaces and default implementations of those interfaces.
| The AttributesImpl Class |
AttributesImpl is a default implementation of the Attributes interface that SAX parsers and filters may use. Besides the methods of the Attributes interface, this class offers manipulator methods so the list of attributes can be modified or reused. These methods allow you to take a persistent snapshot of an Attributes object in startElement( ) and construct or modify an Attributes object in a SAX driver or filter:
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 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); 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); }
| The DefaultHandler Class |
DefaultHandler is a convenience class that implements the EntityResolver, DTDHandler, ContentHandler, and ErrorHandler interfaces with do-nothing methods. You can subclass DefaultHandler and override methods for events to which you actually want to respond. You never have to use this class. You can always implement the interfaces directly instead. The pattern is similar to the adapter classes in the AWT, such as MouseAdapter and WindowAdapter:
package org.xml.sax.helpers; public class DefaultHandler implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler { // Default implementation of the EntityResolver interface. public InputSource resolveEntity(String publicID, String systemID) throws SAXException { return null; } // Default implementation of the DTDHandler interface. public void notationDecl(String name, String publicID, String systemID) throws SAXException {} public void unparsedEntityDecl(String name, String publicID, String systemID, String notationName) throws SAXException{} // Default implementation of the ContentHandler interface. 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[] whitespace, int start, int length) throws SAXException {} public void processingInstruction(String target, String data) throws SAXException {} public void skippedEntity(String name) throws SAXException {} // Default implementation of the ErrorHandler interface. public void warning(SAXParseException ex) throws SAXException {} public void error(SAXParseException ex) throws SAXException {} public void fatalError(SAXParseException ex) throws SAXException { throw ex; } }
| The LocatorImpl Class |
LocatorImpl is a default implementation of the Locator interface for the convenience of parser writers. You probably won't need to use it directly. Besides the constructors, it adds setter methods to set the public ID, system ID, line number, and column number returned by the getter methods declared in Locator:
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 |
NamespaceSupport provides a stack that can track the namespaces in scope at various points in the document. To use it, push a new context at the beginning of each element's namespace mappings, and place it at the end of each element. Each startPrefixMapping( ) invocation should call declarePrefix( ) to add a new mapping to the NamespaceSupport object. Then at any point where you need to figure out to which URI a prefix is bound, you can call getPrefix( ). The empty string indicates the default namespace. The getter methods can then tell you the prefix that is mapped to any URI or the URI that is mapped to any prefix at each point in the document. If you reuse the same NamespaceSupport object for multiple documents, be sure to call reset( ) in between documents.
package org.xml.sax.helpers; public class NamespaceSupport { public final static String XMLNS="http://www.w3.org/XML/1998/namespace"; 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( ); }
| The ParserAdapter Class |
The ParserAdapter class uses the adapter design pattern to convert a SAX1 org.xml.sax.Parser object into a SAX2 org.xml.sax.XMLReader object. As more parsers support SAX2, this class becomes less necessary. Note that some SAX2 features are not available through an adapted SAX1 parser. For instance, a parser created with this adapter does not report skipped entities and does not support most features and properties, not even the core features and properties:
package org.xml.sax.helpers; public class ParserAdapter implements XMLReader, DocumentHandler { public ParserAdapter( ) throws SAXException; public ParserAdapter(Parser parser); // Implementation of org.xml.sax.XMLReader. 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; // Implementation of org.xml.sax.DocumentHandler. public void setDocumentLocator(Locator locator); public void startDocument( ) throws SAXException; public void endDocument( ) throws SAXException; public void startElement(String qualifiedName, AttributeList qualifiedAttributes) throws SAXException; public void endElement(String qualifiedName) throws SAXException; public void characters(char[] text, int start, int length) throws SAXException; public void ignorableWhitespace(char[] text, int start, int length) throws SAXException; public void processingInstruction(String target, String data) throws SAXException; }
| The XMLFilterImpl Class |
XMLFilterImpl is invaluable for implementing XML filters correctly. An instance of this class sits between an XMLReader and the client application's event handlers. It receives messages from the reader and passes them to the application unchanged, and vice versa. However, by subclassing this class and overriding particular methods, you can change the events that are sent before the application gets to see them. You chain a filter to an XMLReader by passing the reader as an argument to the filter's constructor. When parsing, you invoke the filter's parse( ) method, not the reader's parse( ) method.
package org.xml.sax.helpers; public class XMLFilterImpl implements XMLFilter, EntityResolver, DTDHandler, ContentHandler, ErrorHandler { public XMLFilterImpl( ); public XMLFilterImpl(XMLReader parent); // Implementation of org.xml.sax.XMLFilter public void setParent(XMLReader parent); public XMLReader getParent( ); // Implementation of org.xml.sax.XMLReader 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 // Implementation of org.xml.sax.EntityResolver public InputSource resolveEntity(String publicID, String systemID) throws SAXException, IOException; // Implementation of org.xml.sax.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; // Implementation of org.xml.sax.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[] text, int start, int length) throws SAXException; public void processingInstruction(String target, String data) throws SAXException; public void skippedEntity(String name) throws SAXException; // Implementation of org.xml.sax.ErrorHandler public void warning(SAXParseException ex) throws SAXException; public void error(SAXParseException ex) throws SAXException; public void fatalError(SAXParseException ex) throws SAXException; }
| The XMLReaderAdapter Class |
XMLReaderAdapter is the reverse of ParserAdapter; it uses the Adapter design pattern to adapt a SAX2 XMLReader to a SAX1 Parser. This lets you use SAX2 parsers for legacy programs written to a SAX1 interface:
package org.xml.sax.helpers; public class XMLReaderAdapter implements Parser, ContentHandler { public XMLReaderAdapter( ) throws SAXException; public XMLReaderAdapter(XMLReader reader); // Implementation of org.xml.sax.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(String systemID) throws IOException, SAXException; public void parse(InputSource input) throws IOException, SAXException // Implementation of org.xml.sax.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[] text, int start, int length) throws SAXException; public void processingInstruction(String target, String data) throws SAXException; public void skippedEntity(String name) throws SAXException; }
| The XMLReaderFactory Class |
XMLReaderFactory creates XMLReader instances in a parser-independent manner. The noargs createXMLReader( ) method instantiates the class named by the org.xml.sax.driver system property. The other createXMLReader( ) method instantiates the class named by its argument. This argument should be a fully packaged qualified name, such as org.apache.xerces.parsers.SAXParser:
package org.xml.sax.helpers; public final class XMLReaderFactory { public static XMLReader createXMLReader( ) throws SAXException; public static XMLReader createXMLReader(String className) throws SAXException; }
|  | |
| 25. SAX Reference |  | 25.3. SAX Features and Properties |
Copyright © 2002 O'Reilly & Associates. All rights reserved.