Hi.
I'm currently working on an approach to produce help packages for
schema-derived classes. The goal is to produce the set of HTML files
describing, the semantics of XML Schema constructs (complex and simple
types, elements and attributes) and, respectively, derived classes and
their properties.
Since the topic might be important to other JAXB users and developers,
I'd like to share some of my thoughts and discuss the ideas. This
primarily applies to JAXB 1.x, but is also relevant to 2.x.
JAXB generates class items consisting of zero or more fields. Fields
might be either single (0..1) or collections (0..N). There are six
significant types of fields:
* primitive;
* enum;
* DOM;
* wildcard;
* complex;
* heterogeneous;
Basic help pack should provide help for class items as well as for the
contained fields.
Class item help contains:
* title;
* description;
* list of subelements;
* list of containing types or elements (optional, if possible).
Field help contains:
* title;
* description;
* type or types;
* cardinality.
Lists of subelements, containing constructs and field types are
hyperlinked to the referred items. Titles are taken from the
user-provided language packs. Descriptions are taken from the
user-provided XHTML files. All other items are derived from the JAXB
grammar of the schema.
A sample help file from one of my previopus projects might be found here:
http://nokis.baw.de/editor/help/en/nokis/record.html
HTML files for help are generated in a two-step process.
On the first step, JAXB add-on (or annotation processor for 2.0)
produces an XML representation of the grammar. This is a very simple
definition which describes class items, contained fields and their types.
On the second step, grammar XML together with language packs and
user-provided descriptions is processed by the XSLT transformation which
finally produces (X)HTML files. Separating grammar extraction and HTML
rendering allows adjusting presentation of the help packs without
changing the code of the add-on.
I was also considering XMI as the format for grammar XML. This has an
added value of making schema-derived classes UML-ready, but XMI seems to
be a bit overcomplicated for the task.
Bye.
/lexi