Re: PROPOSAL (round 3): Extensions to MDR XMI API

Holger Krug wrote:
> Hi Martin,
> 
> Instead of the 6 methods of XMIWriter:
> 
>    ContentHandler getContentHandler()
>    void setContentHandler(..)
>    void XMIWriter.write(..)
> 
> I suggest the following 4 methods would be enough and would result in
> a cleaner API:
> 
>    abstract void write(ContentHandler handler, Collection objects, String uri);
>    void write(OutputStream stream, Collection object, String uri);
>    abstract void write(ContentHandler handler, RefPackage extent, String uri);
>    void write(OutputStream stream, RefPackage extent, String uri);

I agree with Holger. The interface does not make it obvious that 
sometimes the content handler is used and sometimes it is not used.

Another problem with the current set of write methods is the signatures:
       write(Collection, OutputStream, String);
       write(OutputStream, Collection, String);
       write(RefPackage, OutputStream, String);
       write(OutputStream, RefPackage, String);

I think people will have trouble remembering which method has a "uri" 
parameter and which method has a "xmiVersion" parameter. And if we screw 
up the ordering of the first two parameters, the compiler will still 
type-check the code with no error reported and we will only notice the 
mistake at runtime.

I find it the idea that xmiVersion is a property and _sometimes_ a 
parameter to be unnecessarily distracting. Perhaps it wasn't a good idea 
to make it a parameter in JMI, but I think it is important to be 
consistent (either by always requiring the xmiVersion parameter or 
providing versions of the JMI-defined methods that don't require the 
xmiVersion parameter).

I also think that XMIReader is trying to be too many things at once. 
Sometimes it is a SAX content handler and sometimes it is an interface 
to I/O stream-based I/O. "extent" is a property for the SAX-related 
stuff, but it is a parameter for the JMI-defined stuff. I don't think 
that it will be the case very often that one will use XMIReader to read 
a SAX stream _and_ then also use it to read in InputStream. So, I think 
all the SAX content handler stuff should be factored out into a seperate 
interface like so:

public abstract class XMIReaderBase { // what a beautiful name
     public XMIReferenceResolver getReferenceResolver();
     public void setReferenceResolver(XMIReferenceResolver resolver);
     public abstract void resolveReference(String href, RefObject obj);
}

public abstract class XMIReader extends XMIReaderBase
     implements javax.jmi.xmi.XmiReader { }

public abstract class XMIContentHandler
     extends XMIReaderBase
     implements org.xml.sax.ContentHandler {
     public RefPackage getExtent();
     public void setExtent(RefPackage);
}

public abstract class XMIReaderFactory {
     public XMIReader createXMIReader();
     public XMIContentHandler createXMIContentHandler();
}

- Brian