THIS DOCUMENT IS CURRENTLY BEING WORKED ON AND IS NOT READY FOR DISCUSSION/MODIFCATION.
Please bear with the authors until they finish up with the initial document (this note will be removed as soon as initial work is done!)
This page will host the description and the results of the discussion on the implementation details for an extendable Info Architecture.
The current implementation of the ClassInfo and FieldInfo classes and its (abstract) superclass XMLClassInfo, respectively, do not provide the possibility/facilities for easy extension to add custom information provided for purposes other than XML and Java unmarshalling from a XML Schema. Hence, a refactoring of the current *Info class architecture is needed to "pave the way" for custom and/or extendable *Info classes.
The purpose of a *Info class is to store the information gathered during an unmarshalling process of a XML-Schema document containing the definition for various elements and their attributes which will eventually be mapped to Java Classes. In order to support marshalling of these generated Java classes so-called Descriptors are generated which describe the mapping of these Java classes to XML documents. To support not only the extraction of Java/XML-specific informarion from a XML-Schema, one might want to introduce a new Schema to support, for example, the mapping from Schema to SQL-based Database Engines via JDO. This developer would place her meta-information (which specifies the mapping) in the <appinfo> element of an <annotation> element within the base Schema.
The following Schema snippet shows an example of an <xs:complexType> annotated with meta-information to support the mapping between Java and JDO:
"Encapsulate what varies" or "The introduction of Natures"
A Nature opens the possibility to introduce custom properties which are read from <appinfo> elements found in the schema that is handed to the Source Generator. These properties aren't stored by the Natures directly, instead they are stored in a HashMap within a ClassInfo. A Nature only specifies how these properties (contained in the ClassInfo's HashMap) are stored and assigned. In this sense a Nature represents an external accessor on a ClassInfo which is "extended" by custom properties.
In the code snippet above a schema was annotated with JDO-specific information, e.g. with a <jdo:table> tag. The information contained therein should be stored in a corresponding ClassInfo representing the "employeeType". The following code snippets show how this could be accomplished with the implementation suggested above, namely Natures.
Therefor we are in need of defining two new interfaces:
Along with the introduction of Natures we need to add (at least) two other Interfaces/Classes to model the flow from an annotation (representing some nature property) added to a Schema, on to the addition of a property in the ClassInfo's HashMap and finally to produce some output (JClasses, Descriptors) from these Nature-specific properties. These additional interfaces are the NatureHandler and the NatureProducer.
The NatureHandler's purpose is to parse/handle the information obtained from an <appinfo> element and extract the Nature-specific content therein. It then passes this extracted information to a corresponding ClassInfo via the appropriate Nature implementation.
The NatureProducer obtains Nature-specific information stored in the HashMap of a ClassInfo and produces the corresponding output, e.g. JClasses, Descriptors, and so on.