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

[Manik Surtani]

On 8 Jul 2009, at 19:46, Jason T. Greene wrote:

> I don't want to sound like a broken record, but IMO this style of  
> docs belongs in the schema file in xsd:documentation tags. Then IDEA  
> and Eclipse display the docs while you are actually editing the  
> config file. You could then use one of the many tools out there to  
> generate docs, or extend one to produce it in a more docbook-like way.
>
> For the config API, just use javadoc, you can then describe things  
> in a way more specific to the API.

+1 to putting this information in the XSD in documentation tags, but  
this should be done by the XSD generation tool based on annotated  
info.  I just think that if docs are in two separate places, they are  
not going to get maintained in the long run and will degenerate.

>
> 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
>> _______________________________________________
>> infinispan-dev mailing list
>> infinispan-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
>
> -- 
> Jason T. Greene
> JBoss, a division of Red Hat

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