Re: [infinispan-dev] Re: property tags in configuration files

Just a remark, when was the last time you found a documentation listing all possible parameters with a one line description useful? The MBean style documentation of JBoss AS was horrible :) Task oriented documentations are much more useful but cannot be generated.

On Jul 7, 2009, at 13:14, Manik Surtani wrote: > Interesting discussions. > > I agree that JAXB *would* have been the ideal way about this, but > that brings in a) additional deps with Java5, and b) a not-so- > pretty object model for configuration beans, and c) does not help > us generate docs. > > So essentially we have: > > 1) a simple(-ish) object model for programmatic configuration. > 2) an XML parser to parse a coherent XML file and generate the > beans in (1). > 3) documentation for all setters in (1) and all elements/attributes > in (2). > > As Vladimir pointed out, this effort is to remove the hand-written > parser we have which handles (2), and to save us writing hand- > written docs for (3). By annotating the object model in (1), we > can generate appropriate documentation for (3) as well as parse XML > to populate the bean for (2). > > Emmanuel, note that these annotations are internal only and are not > public API. End users would configure stuff by doing: > > Configuration c = new Configuration(); > c.setBlah( blah ); > > The annotations are purely for core devs who would need to add a > new configuration element for new feature X. By adding a new > getter and setter to the Configuration bean, and appropriately > annotating it, this new config element is automagically added to > the XSD, will be parsed from XML, and is documented. > > That said, I do like the "fluent config" approach where folks can do: > > c.setBlah( blah ).setFoo( foo ); > > HTH, > Cheers > Manik > > On 22 Jun 2009, at 18:41, Vladimir Blagojevic wrote: > >> On 6/22/09 10:52 AM, Emmanuel Bernard wrote: >>> OK here is my take. >>> >>> Populating bean is fairly PITA for a user and a fluent API >>> approach makes configuration more readable. >> Fluent config API is the one that allows chaining calls, right? >> These are very elegant, but they seem more suitable for configs >> that follow more of a grammar like structure. Infinispan's config >> tree is not so nice so to speak. >>> >>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/test/java/org/h... >>> (check NotUseddefineMapping) >>> and the root class >>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/main/java/org/h... >>> >>> if you want to stay on the bean side, I am wondering why you >>> don't use JAXB or something like that to bind the XML model to >>> the object model. >> >> We want to reuse these annotations to kill three birds with one >> stone. Configuration beans are the source, or if you want - code >> is the source. We annotate those beans and get for free human >> readable configuration documentation, configuration schema, and, >> if possible, use those annotations in conjunction with beans to >> populate the beans automatically during configuration reading from >> xml. >> >> Does it make better sense now? Appreciate your input! >> >> Regards, >> Vladimir >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > -- > Manik Surtani > manik(a)jboss.org > Lead, Infinispan > Lead, JBoss Cache > http://www.infinispan.org > http://www.jbosscache.org > > > >