[infinispan-dev] Configuration reference - final solution

[Vladimir Blagojevic]

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