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

Hi Brian,

Brian Smith wrote:
> 0. Could you explain what the intended threading model is? I.e. when can 
> multiple threads simultaneously operate on a shared 
> XMIReader/XMIWriter/XMIProducer/XMIReferenceResolver/etc.

The XMIReader/Writer/ReferenceProvider should be thread safe. As I wrote 
to the Javadoc, reader should lock XMIReferenceResolver for the whole 
reading, which ensures that other threads will not interfere with the 
state of XMIReferenceResolver.

> 1. Do you think that XMIOutputConfig/XMIInputConfig need to be abstract? 
> I am thinking that they are just a statically-typed variant of 
> Properties/Map.

I thought that it would be better to make them abstract to not dictate 
how the thread safeness of them will be implemented. As documented in 
factories, the created object should copy the configuration rather than 
use the passed object. This way the XMI reader can implement it so that 
the methods of the configuration are synchronized, and during the 
reading the XMI reader can synchronize on the configuration object to 
avoid changes of the configuration during the reading.
But for the convenience of users I can make the configuration class 
non-abstract (so that users can create instance of it), althogh I 
thought that they will rather work like this:
XMIReader reader = XMIReaderFactory.createXMIReader();
reader.getConfiguration().set...();

And use the non-default factory methods only for the case when they want 
to create a reader with the same config:
XMIReader reader2 = 
XMIReaderFactory.createXMIReader(reader.getConfiguration());

That's how I expect ReferenceResolver to be implemented.

> 
> 2. I think that XMIOutputConfig and XMIInputConfig need to be Cloneable 
> or at least there should be some other way to copy them.

I didn't made them cloneable. Instead I think that XMIReader/Writer... 
should do a property-by-property copy or the config to its internal 
config. Unrecognized properties will be ignored (thus the default value 
inherited from the abstract base class will be used).
This way the config propagated to subsequently created XMIReaders will 
be really the same as the one used by the current reader.

> 3. There is an obscure (never used?) XMI.Reference element in XMI (See 
> XMI 1.2 3.8.4). I think the motivation for the XMI.Reference element is 
> to allow links to binary data (e.g. icons for stereotypes in the UML 
> metamodel). Do you think that XMIReferenceResolver and 
> XMIReferenceProvider can be used for them? If not, maybe that could be 
> noted in the JavaDoc to avoid confusion since the names are similar.

XMIReferenceProvider was not designed to be used for that. I will state 
it in JavaDoc.

> 4. I don't see how an XMIReferenceResolver can be used in multiple 
> invocations (concurrent or serialized), because it is stateful, and 
> because there is no way to reset the state. Is it your intention that an 
> ever-accumulating state is to be shared by multiple readers, and that a 
> new XMIReferenceResolver/XMIInputConfig needs to be created whenever a 
> fresh state is needed?

No. There is a way to reset the state. As stated in JavaDoc, 
XMIReferenceResolver resets to its fresh state before it exists from the 
outermost call of the resolve method. So according to JavaDoc it should 
work in the following way:
1) reader starts reading the document
2) reader is about to register the first object
3) reader synchronizes on XMIReferenceResolver
4) reader registers the first deserialized object
5) reader registers other objects
6) reader finished reading, but some references are still unresolved
7) reader calls resolve method on XMIReferenceResolver
8) ref. res. starts to read other documents by creating readers reading 
the referenced documents
9) steps 1-7 are repeated for nested readers - during the reading more 
nesting of resolve calls may be needed, at the end, all the references 
are resolved
10) XMIReferenceResolver resets to its fresh state
11) ref. resolver returns from resolve method entered at step 7
12) reader frees the lock on XMIReferenceResolver

> 5. Do you think it would be a good idea to have XMIReferenceProvider be 
> able to (optionally) provide xmi.uuid values too?

Sounds interesting. I guess I will add a note that xmiId can be set to 
null, which means that it should be automatically generated by writer. 
Then we can add uuid (now or later) and also allow null which would mean 
that it will not be included in the document.

> 6. I recommend that you add some package-level JavaDoc to 
> org.netbeans.api.xmi that makes it clear that XMI is for JMI-related 
> stuff and not for general-purpose XML processing like org.netbeans.api.xml.

OK, I am just tired of writing too many javadoc for each new round of 
this proposal and then rewrite it at the next round. I will wait till 
the API is finalized.

> 8. I recommend that the SAX-specific stuff be moved into a package like 
> org.netbeans.api.xmi.sax like was done for javax.xml.transform.sax. I 
> might also like to add an org.netbeans.api.xmi.dom and implementation 
> sometime, as I mentioned before. This would also let you just say that 
> the "SAX API" = org.netbeans.api.xmi.sax and that the entire package is 
> currently unstable.

OK
Martin