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

Hi Martin,

It seems that XMIReader and XMIWriter do not implement
javax.jmi.xmi.XmiReader and javax.jmi.xmi.XmiWriter any more. I wonder 
if there is going to be a confusion because the MDR XMIReader and 
XMIWriter operate using a different model than the JMI XmiWriter and 
XmiReader, but they have nearly identical names.

The new API is notably more complex than the previous one. More tutorial 
documentation will need to be provided. As a potential user of this API, 
I would like to see how it works in a "chain" of XML processing like 
Holger mentioned before: Repository -> XMIWriter -> XSLT processing -> 
file; file -> XSLT processing -> XMIReader -> repository. Also, I would 
like to see how the JMI XMI API maps to the MDR XMI API. I.e., how can 
one acheive the effects of the methods javax.jmi.xmi.XmiReader and 
XmiWriter using just the MDR API.

1. I wonder if XMIReference is even needed? Perhaps XMIReferenceProvider
should have methods like:
      java.lang.String getXmiId(RefObject o);
      java.lang.String getDocumentURI(RefObject o);

This could possibly result in fewer objects being allocated,
and it would be simpler for the MDR client application to implement one 
interface instead of two. It also makes the API simpler in the sense 
that there is "less API."

2. The names "XMIReference" and "XMIReferenceProvider" were good before
because each instance of XMI Reference represented a single link to a
serialized object. But, now XMIReference represents the location of that
object (instead of the link to that location). For example, it is
possible to generate different kinds of references (xmi.idref, href)
using the same XMIReference object. So, perhaps "XMILocation" and
"XMILocationProvider" or "XMILocation" and "XMILocator" would be better
names? The idea being that XMILocation represents the "serialized 
location" of the object.

3. How are document URI's to be compared? Are they just compared by
String.equals(), or is any URI canonicalization done?

4. Since there are numerous XMI-specific classes/interfaces now, with
more likely on the way, perhaps they should be in a package
org.netbeans.api.mdr.xmi?

5. How will you document the valid property mappings? It would be nice 
to have some table of the known values.

6. When I add or change a property's value, is it checked for validity? 
(e.g. does
     xmiWriter.getProperties().put(XMIReferenceProvider.class,
                                   <myReferenceProvider>);
check that <myReferenceProvider> implements XMIReferenceProvider?

7. Instead of #5 and #6, maybe XMIReader/XMIWriter could be abstract 
classes with methods like this (for XMIWriter):
     XMIReferenceProvider getReferenceProvider();
     void setReferenceProvider(XMIReferenceProvider p);
     XMIExtensionProvider getExtensionProvider();
     void setExtensionProvider(XMIExtensionProvider p);
     XMIHeaderProvider getHeaderProvider();
     void setHeaderProvider(XMIHeaderProvider p);
The idea is that these "property" methods would never be abstract or 
final, so new ones could be added to the API over time without breaking 
existing (old) XMIReader/Writer implementations. The advantage is that 
the classes would be self documenting (see #5 above) and statically 
type-checked (see #6 above).

8. I recommend renaming methods in OutputTarget as follows:
    rename getByteStream      to getOutputStream
    rename getCharacterStream to getWriter
These are the names used for similar methods in 
javax.servlet.ServletResponse.

9. Shouldn't XMIWriter.getObjects() be in OutputTarget? Otherwise, I 
wouldn't be able to use the same XMIWriter to write multiple documents. 
Does XMIWriter.getObjects() contain references to _all_ the objects in 
the XMI document, or just the top-level (uncontained) ones? If I want to 
serialize a whole package extent, how would I go about doing that?

10. Could XMIWriter.getObjects() return java.util.List instead of 
java.util.Collection? I would like to be able to control the order that 
top-level (uncontained) objects get written in.

11. Would "XMIDocument" be a better name for OutputTarget? Or, does 
OutputTarget not really represent an XMI Document?

12. I am confused about OutputTarget.getSystemId(). Is this the same as 
XMIReference.getDocumentURI()? What is the difference? Similarly, what 
does OutputTarget.getPublicId() represent? My (limited) understanding of 
XML is that documents don't really have system and public identifiers 
but that only XML DTD's and XML notations do.

Thanks,
Brian