[jboss-dev] Infinispan configuration - all in one solution

[Vladimir Blagojevic]

Recently, I was assigned to complete 
https://jira.jboss.org/jira/browse/ISPN-97

The driving force behind this JIRA was to achieve a minimal maintenance 
of Infinispan XML configuration. We have scarce resources but we needed 
to: maintain professional looking HTML configuration reference, keep a 
well documented XML schema for configuration files, and finally we 
wanted to achieve seamless marshaling from XML configuration files into 
configuration object model. Since configuration reference and schema 
need to be generated for every release we wanted to completely automate 
this process.

The obvious candidate library to achieve seamless unmarshalling of XML 
configuration files into object model was either JAXB or JBossXB. We 
wanted to keep our current configuration class hierarchy loosely coupled 
with XML schema - i.e not every type in XML schema mapped into an 
appropriate class in configuration hierarchy. In another words we wanted 
to group configuration attributes into many XML elements but did not 
want to have as many classes in our configuration class hierarchy. Any 
solution to this problem, including JBossXB, requires maintenance of 
mapping between XML schema types and our configuration class hierarchy. 
Not a big problem, but this was a first hurdle in a serious of hurdles.

As any other HTML configuration reference Infinispan's should display 
default values and their types, constraints for those values, human 
readable descriptions and so on. If we were to generate configuration 
reference automatically we needed to keep this information somewhere, 
extract it, and spit it out. In JAXB/JBossXB based solution, the obvious 
place to keep this information was in a "hand maintained" schema. But 
schema, although it carries most of this information, is a blueprint, it 
does not contain all instances of all possible configuration elements. 
For example, our schema constrains that <loader> element has such and 
such form but it does not document all the configuration options for all 
possible loaders. The source code of those loader classes does! Another 
problem with keeping documentation in hand maintained schema was that 
all the information in schema was replicating what already existed in 
the source code. We already had comments, attribute types and their 
default values, they were already in the source. Why do we need to keep 
a mirror of this data and then on top of it hand maintain it along with 
a mapping from schema types to our configuration class hierarchy?

A proper solution for all of these minor issues, but issues that create 
a lot of maintenance headache, lies in switching to the source code as 
the main source of all information we need. What we had to do was to add 
a bit of metadata in a form of annotations to complete everything. The 
algorithm to unmarshall XML configuration file into object model is 
about 300 lines of code [1], documentation [2] and schema generator [3] 
around 200 each.

In conclusion, out of source code itself you automatically get a kick 
ass configuration documentation reference, a well documented XML schema 
and XML configuration unmarshalling into object model. All of this with 
almost zero maintenance cost.

Yes, indeed, we are almost reinventing the wheel here but this is the 
solution we need and we would gladly contribute to a project that does 
exactly what we need. At the moment, I doubt that we can do this with 
JBossXB, Alexey please correct me if I am wrong. Since we are already 
having documentation reference maintenance problems in other projects 
maybe we should somehow extend JBossXB with annotation based framework 
and apply it in other projects as well?

Automatically generated configuration reference is included as 
attachment. To view, download both stylesheet and config.html into a 
local directory and open config.html in your favorite browser.


Regards,
Vladimir



[1] 
http://anonsvn.jboss.org/repos/infinispan/trunk/core/src/main/java/org/infinispan/config/parsing/AutomatedXmlConfigurationParserImpl.java 


[2] 
http://anonsvn.jboss.org/repos/infinispan/trunk/tools/src/main/java/org/infinispan/tools/doclet/config/ConfigHtmlGenerator.java 


[3] 
http://anonsvn.jboss.org/repos/infinispan/trunk/tools/src/main/java/org/infinispan/tools/schema/SchemaGeneratorTreeWalker.java 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-development/attachments/20090717/2d14a02a/attachment.html 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: stylesheet2.css
Type: text/css
Size: 6893 bytes
Desc: not available
Url : http://lists.jboss.org/pipermail/jboss-development/attachments/20090717/2d14a02a/attachment.css