26.2 The org.xml.sax.helpers Package

   

The org.xml.sax.helpers package contains support classes for the core SAX classes. These 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  addAttribu   te  (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 pop 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( ) 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;       } 



XML in a Nutshell
XML in a Nutshell, Third Edition
ISBN: 0596007647
EAN: 2147483647
Year: 2003
Pages: 232

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net