XOM API for Processing XML with Java

[Janek Bogucki <janekdb AT yahoo.co.uk>]

 --- Nils_Kilden-Pedersen AT Countrywide.Com wrote:
> xom-interest-bounces AT lists.ibiblio.org wrote on 11/10/2003 05:34:25 PM:
> 
> > At 2:25 PM +0000 11/10/03, Janek Bogucki wrote:
> > 
> > >Then you get this heirarchy:
> > >
> > >Serializer
> > >   |
> > >   + ConfigurableSerializer
> > >   |
> > >   + CanonicalXMLSerializer
> > >
> > >This is an improvement as the inappropriate setter methods do not 
> > >exist on CanonicalXMLSerializer
> > >and any method expecting a Serializer will not be surprised by 
> > >IllegalArgumentExceptions.
> > 
> > That makes some sense, but it's not like the methods in Serializer 
> > don't belong there; and I don't like adding excess classes to the 
> > core API. I think a lot of developers would end up either complaining 
> > about not having enough options in Serializer (if they don't notice 
> > ConfigurableSerializer) or complaining about having to always type 
> > "Configurable". I think prefer just the one Serializer class.
> 
> Nonetheless, in an OO perspective that's what you should do. Maybe you'll 
> like this better:
> 
> AbstractSerializer
>    |
>    + Serializer
>    |
>    + CanonicalXMLSerializer
> 
> 
> 
> Nils
> _______________________________________________

Nils suggestion is an improvement over the current CVS HEAD because it avoids 
the 'corrective'
design used in this hierarchy

  Serializer
     |
     + CanonicalXMLSerializer

Here setters exist on Serializer which are unsupported on 
CanonicalXMLSerializer. An effort is
made to subtract these methods from CanonicalXMLSerializer by making them 
final and otherwise
non-functional. The exception messages thrown when these setters are invoked 
have an educational
value, if one is learning about canonical xml, otherwise there ends the 
utility of these methods.

Here is an example of how a client of Serializer is required to have an 
understanding of a
possible subclass of Serializer. According to the Liskov Substitution 
Principle this means
CanonicalXMLSerializer is not a subtype of Serializer:

  /* FORM A, WRONG: may throw IllegalArgumentException */
  void publish ( Serializer serializers [] ) {

     for ( int i = 0; i < serializers.length ; i++ ) {

       if ( subscriberIsWindows() )
         serializers [i].setLineSeparator( "\r\n" )

       serializers [i].write ( getDoc() ) ;
     }

  }

  /* FORM B, FIXED. Alternatively use a try..catch block. */
  void publish ( Serializer serializers [] ) {

     for ( int i = 0; i < serializers.length ; i++ ) {

       if ( subscriberIsWindows()
            && ( ! ( serializers [i] instanceof CanonicalXMLSerializer ) ) )
         serializers [i].setLineSeparator( "\r\n" )

       serializers [i].write ( getDoc() ) ;
     }

  }

With Nils' hierarchy FORM A would be correct.

A further advantage comes from making use of an abstract superclass without 
the setters. The
library user is not required to read the JavaDoc of CanonicalXMLSerializer to 
find the setter
restrictions -- it is explicit from the class relationships. The 'corrective' 
approach fails to
take advantage of available language features to enforce correct usage. 

If you do decide to retain the current approach then I'd suggest changing 
from using
IllegalArgumentExceptions to java.util.UnsupportedOperationExceptions in the 
same way as the JDK
Collections classes do _and_ document (in Serializer) that setters are 
optional for subclasses. 

-Janek




________________________________________________________________________
Want to chat instantly with your online friends?  Get the FREE Yahoo!
Messenger http://mail.messenger.yahoo.co.uk