SAX2/Java: Towards a final form

[David Megginson]

I spent some time over the holidays working on a new SAX2 package, and
it didn't take me long to decide that redoing everything in a new
org.xml.sax2 package and creating all of the adapters was going to be
too much of a hill for me to climb right now.

We really, really, *really* need SAX2 -- a lot of the debate about
Namespaces, for example, wouldn't exist if there were a simple API for
getting at Namespace information.  Here's a new suggestion that both
preserves a lot of SAX1 and provides a clean path for future SAX
development without some of the SAX1 baggage:

1. Deprecate Parser, DocumentHandler, and AttributeList.

2. Create a new class, ContentHandler, that duplicates the current
   DocumentHandler but adds proper support for Namespace processing
   and for reporting skipped entities (an XML 1.0 requirement that
   SAX1 never met, as John Cowan never got tired of reminding me).

3. Create a new interface, Attributes, that replaces AttributeList.

4. Create a new class, XMLReader, that (for now) extends Parser and
   adds support for the configurability and for setting the
   ContentHandler -- add a warning that this class will likely not
   extend Parser in future versions of SAX.

5. Add the SAXNotRecognizedException and SAXNotSupportedException
   classes.

6. Add the LexicalHandler and DeclarationHandler classes as previously
   planned, but put them in a different extensions package and don't
   provide explicit setters for XMLReader (since we'll be adding more
   extension handlers later, and all extension handlers should be set
   with setProperty).

7. Write the (now fairly simple) adapters for SAX1 parsers.

8. Rewrite some of the existing concrete classes to improve efficiency 
   or fix bugs.

9. Rewrite HandlerBase.


Here are the three new core interfaces:


====================8<====================8<====================

  public interface XMLReader extends Parser
  {
    //
    // Parser.setLocale and Parser.setDocumentHandler are
    // deprecated.
    //

    //
    // Configure the reader.
    //
    public void setFeature (String name, boolean state)
      throws SAXNotRecognizedException, SAXNotSupportedException;
    public boolean getFeature (String name)
      throws SAXNotRecognizedException;
    public void setProperty (String name, Object value)
      throws SAXNotRecognizedException, SAXNotSupportedException;
    public Object getProperty (String name)   
      throws SAXNotRecognizedException;

    //
    // Register handlers.
    //
    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 ();

    //
    // Run a parse.
    //
    public void parse (String systemId)
      throws IOException, SAXException;
    public void parse (InputSource input)
      throws IOException, SAXException;
  }

====================8<====================8<====================

  public interface Attributes
  {
    public int getLength ();

    public String getURI (int pos);
    public String getLocalName (int pos);
    public String getRawName (int pos);
    public String getType (int pos);
    public String getValue (int pos);

    public String getType (String uri, String localName);
    public String getType (String rawName);
    public String getValue (String uri, String localName);
    public String getValue (String rawName);
  }

====================8<====================8<====================

  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 uri, String localName,
                              String rawName, Attributes atts)
      throws SAXException;
    public void endElement (String uri, String localName, String rawName)
      throws SAXException;

    public void characters (char ch[], int start, int length)
      throws SAXException;

    public void ignorableWhitespace (char ch[], int start, int length)
      throws SAXException;

    public void processingInstruction (String target, String data)
      throws SAXException;

    public void skippedEntity (String name)
      throws SAXException;
  
  }

====================8<====================8<====================

There are three significant advantages to doing things this way:

1. Namespace support is a core and natural part of the interface,
   but non-Namespace processing is still possible with no penalty.

2. There's a lot of compatibility with SAX 1.0, but implementations in 
   other languages won't have to carry around the SAX 1.0 baggage
   (they won't have Parser or DocumentHandler at all).

3. Writing an implementation and SAX1 adapters will be easy enough
   that I might actually get around to doing it.

Comments?  If there is anything approaching agreement (or even
grudging acceptance), I can try to get out a beta this week with SAX1
adapters.


All the best,


David

-- 
David Megginson                 david at megginson.com
           http://www.megginson.com/

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/ and on CD-ROM/ISBN 981-02-3594-1
To unsubscribe, mailto:majordomo at ic.ac.uk the following message;
unsubscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)