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

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/in... [2] http://anonsvn.jboss.org/repos/infinispan/trunk/tools/src/main/java/org/i... [3] http://anonsvn.jboss.org/repos/infinispan/trunk/tools/src/main/java/org/i...