26.1 The org.xml.sax Package

   

The org.xml.sax package contains the core interfaces and classes that comprise the Simple API for XML.

The Attributes Interface

An object that implements the Attributes interface represents a list of attributes on a start-tag. The order of attributes in the list is not guaranteed to match the order in the document itself. Attributes objects are passed as arguments to the startElement( ) method of ContentHandler . You can access particular attributes in three ways:

  • By number

  • By namespace URI and local name

  • By qualified name

This list does not include namespace declaration attributes ( xmlns and xmlns : prefix ) unless the http://xml.org/sax/features/namespace-prefixes feature is true. It is false by default.

If the http://xml.org/sax/features/namespace-prefixes feature is false, qualified name access may not be available; if the http://xml.org/sax/features/namespaces feature is false, local names and namespace URIs may not be available.

 package org.xml.sax;       public interface  Attributes  {         public int  getLength  (  );   public String  getURI  (int  index  );   public String  getLocalName  (int  index  );   public String  getQName  (int  index  );   public int  getIndex  (String  uri  , String  localName  );   public int  getIndex  (String  qualifiedName  );   public String  getType  (int  index  );   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 String  getValue  (int  index  );       } 

The ContentHandler Interface

ContentHandler is the key piece of SAX. Almost every SAX program needs to use this interface. ContentHandler is a callback interface. An instance of this interface is passed to the parser via the setContentHandler( ) method of XMLReader . As the parser reads the document, it invokes the methods in its ContentHandler to tell the program what's in the document:

 package org.xml.sax;       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  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 DTDHandler Interface

After passing an instance of the DTDHandler interface to the setDTDHandler( ) method of XMLReader , the program will receive notification of notation and unparsed entity declarations in the DTD. You can store this information and use it later to retrieve information about the unparsed entities you encounter while reading the document:

 package org.xml.sax;       public interface  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;       } 

The EntityResolver Interface

By passing an instance of the EntityResolver interface to the setEntityResolver( ) method of XMLReader , you can intercept parser requests for external entities, such as the external DTD subset or external parameter entities, and redirect those requests in order to substitute different entities. For example, you could replace a reference to a remote copy of a standard DTD with a local one or find the sources for particular public IDs in a catalog.

 package org.xml.sax;       public interface  EntityResolver  {         public InputSource  resolveEntity  (String  publicID  , String  systemID  )    throws SAXException, IOException;       } 

The ErrorHandler Interface

By passing an instance of the ErrorHandler interface to the setErrorHandler( ) method of XMLReader , you can provide custom handling for particular classes of errors detected by the parser. For example, you can choose to stop parsing when a validity error is detected by throwing an exception from the error( ) method. The SAXParseException passed to each of the three methods in this interface provides details about the specific cause and location of the error:

 package org.xml.sax;       public interface  ErrorHandler  {         public void  warning  (SAXParseException  exception  ) throws SAXException;   public void  error  (SAXParseException  exception  ) throws SAXException;   public void  fatalError  (SAXParseException  exception  )    throws SAXException;       } 

Warnings represent possible problems noticed by the parser that are not technically violations of XML's well- formedness or validity rules. For instance, a parser might issue a warning if an xml:lang attribute's value was not a legal ISO-639 language code. The most common kind of error is a validity problem. The parser should report it, but it should also continue processing. A fatal error violates well-formedness. The parser should not continue parsing after reporting such an error. Some parsers report violations of namespace well-formedness as fatal errors. Others report these as nonfatal errors.

The Locator Interface

Unlike most other interfaces in the org.xml.sax package, the Locator interface does not have to be implemented. Instead, the parser has the option to provide an implementation. If it does so, it passes its implementation to the setDocumentLocator( ) method in the ContentHandler instance before it calls startDocument( ) . You can save a reference to this object in a field in your ContentHandler class, like this:

 private Locator locator;       public void setDocumentLocator(Locator locator) {   this.locator = locator; } 

Once you've found the locator, you can then use it inside any other ContentHandler method, such as startElement( ) or characters( ) , to determine in exactly which document and at which line and column the event took place. For instance, the locator allows you to determine that a particular start-tag began on the third column of the document's seventeenth line at the URL http://www.slashdot.org/slashdot.xml :

 package org.xml.sax;       public interface  Locator  {         public String  getPublicId  (  );   public String  getSystemId  (  );   public int  getLineNumber  (  );   public int  getColumnNumber  (  );       } 

The XMLFilter Interface

An XMLFilter is an XMLReader that obtains its events from another parent XMLReader , rather than reading it from a text source such as InputStream . Filters can sit between the original source XML and the application and modify data in the original source before passing it to the application. Implementing this interface directly is unusual. It is almost always much easier to use the more complete org.xml.sax.helpers.XMLFilterImpl class instead.

 package org.xml.sax;       public interface  XMLFilter  extends XMLReader {         public void  setParent  (XMLReader  parent  );   public XMLReader  getParent  (  );       } 

The XMLReader Interface

The XMLReader interface represents the parser that reads XML documents. You generally do not implement this interface yourself. Instead, use the org.xml.sax.helpers.XMLReaderFactory class to build a parser-specific implementation. Then use this parser's various setter methods to configure the parsing process. Finally, invoke the parse( ) method to read the document, while calling back to methods in your own implementations of ContentHandler , ErrorHandler , EntityResolver , and DTDHandler as the document is read:

 package org.xml.sax;       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;       } 

The InputSource Class

The InputSource class is an abstraction of a data source from which the raw bytes of an XML document are read. It can wrap a system ID, a public ID, an InputStream , or a Reader . When given an InputSource , the parser tries to read from the Reader . If the InputSource does not have a Reader , the parser will try to read from the InputStream using the specified encoding. If no encoding is specified, then it will try to autodetect the encoding by reading the XML declaration. Finally, if neither a Reader nor an InputStream has been set, then the parser will open a connection to the URL given by the system ID.

 package org.xml.sax;       public class  InputSource  {           public  InputSource  (  );     public  InputSource  (String  systemID  );     public  InputSource  (InputStream  byteStream  );     public  InputSource  (Reader  reader  );           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  reader  );     public Reader  getCharacterStrea   m  (  );       } 

The SAXException Class

Most exceptions thrown by SAX methods are instances of the SAXException class or one of its subclasses. The single exception to this rule is the parse( ) method of XMLReader , which may throw a raw IOException if a purely I/O- related error occurs; for example, if a socket is broken before the parser finishes reading the document from the network.

Besides the usual exception methods such as getMessage( ) and printStackTrace( ) that SAXException inherits from or overrides in its superclasses, SAXException adds a getException( ) method to return the nested exception that caused the SAXException to be thrown in the first place.

 package org.xml.sax;       public class  SAXException  extends Exception {           public  SAXException  (String  message  );     public  SAXException  (Exception  ex  );     public  SAXException  (String  message  , Exception  ex  );           public String  getMessage  (  );     public Exception  getException  (  );     public String  toString  (  );       } 

SAXParseException

If the parser detects a well-formedness error while reading a document, it throws a SAXParseException , a subclass of SAXException . SAXParseException s are also passed as arguments to the methods of the ErrorHandler interface, where you can decide whether you want to throw them.

Besides the methods it inherits from its superclasses, this class adds methods to get the line number, column number, system ID, and public ID of the document where the error was detected:

 package org.xml.sax;       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  getLineNumber  (  );   public int  getColumnNumber  (  );       } 

SAXNotRecognizedException

A SAXNotRecognizedException is thrown if you attempt to set a property or feature the parser does not recognize. Besides the constructors, all its methods are inherited from superclasses:

 package org.xml.sax;       public class  SAXNotRecognizedException  extends SAXException {         public  SAXNotRecognizedException  (  );   public  SAXNotRecognizedException  (String  message  );       } 

SAXNotSupportedException

A SAXNotSupportedException is thrown if you attempt to set a property or feature that the parser recognizes, but either cannot set or get or does not allow the particular value you're trying to set it to. Besides the constructors, all of its methods are inherited from superclasses:

 package org.xml.sax;       public class  SAXNotSupportedException  extends SAXException {         public  SAXNotSupportedException  (  );   public  SAXNotSupportedException  (String  message  );       } 



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

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