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

[Emmanuel Bernard]

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/hibernate/search/test/configuration/ProgrammaticMappingTest.java
>>> (check NotUseddefineMapping)
>>> and the root class
>>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/main/java/org/hibernate/search/cfg/SearchMapping.java
>>>
>>> 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 at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
> --
> Manik Surtani
> manik at jboss.org
> Lead, Infinispan
> Lead, JBoss Cache
> http://www.infinispan.org
> http://www.jbosscache.org
>
>
>
>