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

[Manik Surtani]

On 7 Jul 2009, at 12:38, Emmanuel Bernard wrote:

> 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.

This would form more of a quick reference guide.  As you suggest, task- 
oriented, hand-written docs will be a superset.  Right now we have  
next to no docs for configs.

>
> 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
>>
>>
>>
>>
>

--
Manik Surtani
manik at jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org