SAX2: Migration strategies for option (2)

[Miles Sabin]

I've been giving some thought to how we could go about
making the transition from SAX1 to SAX2 as painless as
possible if we were to take David's option (2): adding
new methods to existing interfaces.

As far as I can make out the following might be the
best bet. We'll need to use a marker interface, but
it's not used in _quite_ the same way as in some of the
other proposals that have been made over the last few
days. It's defined as follows,

  public interface SAX2
  {
  }

All SAX2 parser implementations should implement this
interface, ie.,

  public class MySAX2Parser
    implements Parser, SAX2
  {
    // etc.
  }

Now, we migrate in one of two ways, depending on what
guarantees we can make about which Java platform we're
working with.

1. Where a SAX2 client application can *guarantee* that 
   it's running on the Java 2 platform it uses a 
   version of SAX2 implemented along the lines I 
   discussed in,

   http://www.lists.ic.ac.uk/hypermail/xml-dev/9905/0425.html

   This allows those fortunate enough to be able to
   specify Java 2 to have perfect forwards and backwards
   compatibility between SAX1 and SAX2.

   Invoking such an application would be done something
   like this,

     java \        (a)          (b)              (c)
       -classpath SAX2.jar:SAX2ClientApp.jar:SAXParser.jar \
       SAXClientMain

   Where,
     (a) SAX2.jar contains the SAX2 classes and 
         interfaces, incorporating the adapter mechanism 
         I outlined.

     (b) SAX2ClientApp is the SAX2 client.

     (c) SAXParser.jar is a SAX parser. This could be 
         either a SAX1 or a SAX2 parser, and it makes no 
         difference whether or not the SAX1/2 classes 
         and interfaces are bundled in with it in the 
         same jar.

   References to the SAX classes and interfaces will 
   resolve to the versions present in SAX2.jar, even 
   those made from a SAX1 parser, because SAX2.jar 
   apprears on the classpath first.

2. Where a SAX2 client application can *not* guarantee
   that it is running on the Java 2 platform *and*
   it desires compatibility with SAX1, it should use
   whatever SAX classes and interfaces come bundled
   with the parser it is run against, and should
   itself be bundled with the SAX2 marker interface
   *only*.

   When creating a Parser SAX2 client apps can test
   for the presence of the marker interface and act
   accordingly, ie.

   Parser p = ParserFactory.makeParser(); (*)
   if(p instanceof SAX2) // (**)
   {
     // do SAX2 stuff
   }
   else
   {
     // do SAX1 stuff
   }

   The use of the SAX classes and interfaces bundled
   with the parser (whichever SAX version it conforms 
   to) ensures that at (*) it will be possible to 
   instantiate a Parser irrespective of JDK version.

   The presence of the marker interface on the classpath 
   ensures that the line marked (**) will not fail with
   a ClassNotFoundException.

   The use of the marker interface is preferable to
   catching NoSuchMethodErrors, both from the
   maintainability/comprehensibility, and from the
   efficiency points of view.

Note that both (1) and (2) are transitional strategies.
We should encourage parser developers to move to SAX2
as soon as possible so that these shenanigans can be
dropped and the SAX2 interface can be deprecated (in
fact we might consider deprecating it from the outset).

Note that there is no comparable problem with 
combinations of SAX1 *clients* with SAX2 parsers: the 
only SAX2 interface which is being modified is Parser
and that will not (normally? ever?) be implemented in
the client. Consequently the IncompatibleClassChange
problem that I highlighted in,

  http://www.lists.ic.ac.uk/hypermail/xml-dev/9905/0465.html

will not occur.

Cheers,


Miles

-- 
Miles Sabin                          Cromwell Media
Internet Systems Architect           5/6 Glenthorne Mews
+44 (0)181 410 2230                  London, W6 0LJ
msabin at cromwellmedia.co.uk           England

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 (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe 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)