[infinispan-dev] Configuration reference - final solution

[Manik Surtani]

Thanks Vladimir!

On 26 Aug 2009, at 14:12, Vladimir Blagojevic wrote:

> Hey guys,
>
> I've committed a massive change that removed all our annotations  
> that were previously used for configuration. A new solution and a  
> more permanent one is in place. It is described below.
>
> In the next day or so I'll complete a few minor remaining tasks  
> along with documentation Manik outlined below.
>
> Regards,
> Vladimir
>
> On 21/08/09 12:33 PM, Manik Surtani wrote:
>> Yeah, looks good to me.  :-)
>>
>> Could you also pls create a wiki page - perhaps linked to http://www.jboss.org/community/wiki/InfinispanQuickStartGuideforDevelopers 
>>  - on how to create new configuration elements.
>>
>> Basically, creating a new configuration variable should entail:
>>
>> 1.  Adding setter and getter to the Configuration bean?   What else?
>> 2.  Annotating accordingly - which annotations?  Where?  On setter?
>> 3.  Javadoc accordingly - any custom tags to use?
>> 4.  Unit tests and sample cfg files to ship?  Where are these?
>>
>> Also, you should blog about this - and link to this wiki page in  
>> your blog!
>>
>> Thanks!
>> Manik
>>
>> On 21 Aug 2009, at 11:28, Vladimir Blagojevic wrote:
>>
>>> On 21/08/09 12:18 PM, Manik Surtani wrote:
>>>> I would say this should be on the infinispan-dev list - but the  
>>>> list is broken at the moment!  :P
>>>>
>>>> On 21 Aug 2009, at 11:14, Vladimir Blagojevic wrote:
>>>>
>>>>> Hey,
>>>>>
>>>>> We have two options for the final HTML configuration reference  
>>>>> solution:
>>>>>
>>>>> - keep things as they are and maintain our documentation  
>>>>> annotations (CofigurationElement, ConfigurationAttribute etc)
>>>>> - implement a new solution based on XML Schema and javadoc  
>>>>> comments
>>>>>
>>>>> Since you are familiar with the first let me explain the second.  
>>>>> The new solution loads created XML Schema using XSOM library and  
>>>>> creates in-memory tree representation of that schema. Once that  
>>>>> is done it is very simple to create exact same reference as it  
>>>>> is today, however, the content would be coming from source file  
>>>>> javadoc, not annotations as it is today. We would simply  
>>>>> document our Java classes that correspond to XML schema elements  
>>>>> with special @ tags. All documentation related to attributes,  
>>>>> general element description in configuration reference would be  
>>>>> coming from our own javadoc @tags.
>>>>>
>>>>> One shortcoming of the new solution is that not all types of  
>>>>> loaders would be documented. Recall, how different loaders allow  
>>>>> special properties and how these are documented in configuration  
>>>>> reference. Proposed new solution would not contain these but as  
>>>>> a trade-off we would get rid of all these ConfigurationElement  
>>>>> annotations. Hmmm, now that I am writing this email I realize  
>>>>> that it would be still possible to do document all these  
>>>>> different loaders but it would require a bit more effort - an  
>>>>> extra day or two. It is doable.
>>>>
>>>> What does the 2nd solution entail by way of dependencies?  I  
>>>> assume we already have all of the JSXB deps we need?
>>> There extra two dependencies: xsom.jar and relaxngDatatype.jar
>>>
>>>> Perhaps a few more deps for the generation tool, but nothing more  
>>>> for the distro/runtime?
>>>
>>> Yes, strictly in tools project. These would not go into distro.
>>>>
>>>> Also, is there any impact (performance-wise or anything else) on  
>>>> the runtime?
>>>
>>> Maybe on tools execution time but infinispan runtime absolutely not.
>>>
>>>>
>>>> Finally, what are these extra Javadoc tags going to look like?   
>>>> Could you show us a short sample?
>>>
>>>  /**
>>>   *
>>>   * @configElementRef locking
>>>   * @configElementDoc any documentation here
>>>   */
>>>  @XmlAccessorType(XmlAccessType.PROPERTY)
>>>  private static class LockingType  extends  
>>> AbstractNamedCacheConfigurationBean{
>>>
>>>
>>>     /** The serialVersionUID */
>>>     private static final long serialVersionUID =  
>>> 8142143187082119506L;
>>>
>>>     @Dynamic
>>>     private Long lockAcquisitionTimeout = 10000L;
>>>
>>>     private IsolationLevel isolationLevel =  
>>> IsolationLevel.READ_COMMITTED;
>>>
>>>     private Boolean writeSkewCheck = false;
>>>
>>>     private Boolean useLockStriping = true;
>>>
>>>     private Integer concurrencyLevel = 500;
>>>
>>>     /**
>>>      *  @configElementDoc reference documentation here
>>>      */
>>>     @XmlAttribute
>>>     public void setLockAcquisitionTimeout(Long  
>>> lockAcquisitionTimeout) {
>>>        testImmutability("lockAcquisitionTimeout");
>>>        this.lockAcquisitionTimeout = lockAcquisitionTimeout;
>>>     }
>>>
>>>     /**
>>>      *  @configElementDoc reference documentation here
>>>      */
>>>     @XmlAttribute
>>>     public void setIsolationLevel(IsolationLevel isolationLevel) {
>>>        testImmutability("isolationLevel");
>>>        this.isolationLevel = isolationLevel;
>>>     }
>>>
>>>     /**
>>>      *  @configElementDoc reference documentation here
>>>      */
>>>     @XmlAttribute
>>>     public void setWriteSkewCheck(Boolean writeSkewCheck) {
>>>        testImmutability("writeSkewCheck");
>>>        this.writeSkewCheck = writeSkewCheck;
>>>     }
>>>
>>>     /**
>>>      *  @configElementDoc reference documentation here
>>>      */
>>>     @XmlAttribute
>>>     public void setUseLockStriping(Boolean useLockStriping) {
>>>        testImmutability("useLockStriping");
>>>        this.useLockStriping = useLockStriping;
>>>     }
>>>
>>>     @XmlAttribute
>>>     public void setConcurrencyLevel(Integer concurrencyLevel) {
>>>        testImmutability("concurrencyLevel");
>>>        this.concurrencyLevel = concurrencyLevel;
>>>     }
>>>  }
>>
>> -- 
>> 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