Creating a design document

[starksm64]

One thing I would like to do before the final release is to get a design document that gives an overview of how all of the binding metadata fits together along with the terminology used in the jbossxb classes. The primary thing I want to get out of this doc, is how the binding layer controls the xml to object coversion as one walks through an xml document. How the binding default, xsd binding, SchemaBindingInitializer produce an order set of binding instructions is what I want to be able to understand.

I'll start fleshing this out as a docbook project to be added to the soon to be broken out jbossxb project as there are some particular examples that I want documented.

[adrian.brock]

The terminology and the overall design of the metadata comes from
the xsd spec with some more info in the JAXB spec.

[starksm64]

It seems that the ObjectModelFactory is obsolete, being replaced by GenericObjectModelFactory, but old ObjectModelFactory impls work because of DelegatingObjectModelFactory? Seems like a lot of evolution of the ObjectModelFactory side and I'm not sure how much to document. We do have a number of ObjectModelFactory implementation that magically behave as GenericObjectModelFactorys which seems strange. What was the reason for splitting ObjectModelFactory into two interfaces?

The dual nature of the Unmarshaller into methods related to ObjectModelFactory and another related to SchemaBinding also seems like an unnatural coupling of two models that should probably be broken out in the future, and align this with the JAXBContext/Unmarshaller where the different ObjectModelFactory/SchemaBinding behaviors would be internal implementation details?

For now I'll focus on documenting the SchemaBinding based parsing.

[starksm64]

I have been creating some sequence diagrams to try to tie together the interaction of the xml parser and the SchemaBinding metadata, but the resulting startElement/endElement diagrams are looking like designs for pentinum chips. The SundayContentHandler.startElement callout is a 16719x14241 px image that at 96dpi requires 14 feet x 12 feet to display the image on a screen.

There seems to be a lot of repeated code being executed under subtle differences in the state of the java object stack as function of how the schema model relates to the current element. I still don't have a good enough understanding of the schema model representation to understand why the startElement can't be structured into a more linear flow consisting of:

 public void startElement(String namespaceURI,
 String localName,
 String qName,
 Attributes atts,
 XSTypeDefinition xercesType)
 {
 QName startName = localName.length() == 0 ? new QName(qName) : new QName(namespaceURI, localName);
 SchemaBinding schemaBinding = resolveSchema(schema, schemaResolver, namespaceURI, atts);
 Object parent = getParent();
 ParticleBinding particle = resolveParticle(...);
 ParticleHandler handler = resolveHandler(...);
 Object elementObj = handler.startParticle(parent, startName, particle, atts, nsRegistry);
 push(startName, particle, elementObj);
 }

with all the current back and forth encapsulated better. The endElement(s) end up being about as complicated. What can we do to break this up into a more orderly interaction between the java object stack and schema metadata?

[aloubyansky]

The difference between ObjectModelFactory and GenericObjectModelFactory is documented in javadoc and on the wiki.

[aloubyansky]

The code has almost never been refactored because there seemed urgent feature requests. The refactoring work including review of the public API and repackaging is planned for the 1.0 release.

[starksm64]

The difference between ObjectModelFactory and GenericObjectModelFactory is documented in javadoc and on the wiki.

I don't see where there is a description of why an ObjectModelFactory implementation has methods not defined in the interface that are discovered via reflection. I would guess its due to backward compatibility issues?

If that is the case, I think its time to forget about the backward compatibility problem and focus on a refactoring that lends itself to better maintence and extensibility of the codebase. Its only your steel trap mind that is able to deal with the current complexity. Obviously we have projects that need a release, but if we can't be comfortable with a design that is going to take use through a JAXB 2.0 implementation, then the current jbossxb usage is an implementation detail on a alpha/beta API that is subject to change until the refactoring is complete.

[aloubyansky]

I don't see where there is a description of why an ObjectModelFactory implementation has methods not defined in the interface that are discovered via reflection.

I am sorry for my mind. I tried to explain here http://wiki.jboss.org/wiki/Wiki.jsp?page=ObjectModelFactory

See examples of ObjectModelFactory implementations in the testsuite but not GenericObjectModelFactory. The methods cannot be added to the interface because application object domain is not known to the framework.

You could question how useful this approach is but that's a totaly different question, to my mind at least.