Skip to Content.
Sympa Menu

xom-interest - Re: [XOM-interest] CanonicalXMLSerializer exceptions

xom-interest AT lists.ibiblio.org

Subject: XOM API for Processing XML with Java

List archive

Chronological Thread  
  • From: Janek Bogucki <janekdb AT yahoo.co.uk>
  • To: xom-interest AT lists.ibiblio.org
  • Subject: Re: [XOM-interest] CanonicalXMLSerializer exceptions
  • Date: Thu, 13 Nov 2003 11:30:49 +0000 (GMT)

--- 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




Archive powered by MHonArc 2.6.24.

Top of Page