[infinispan-dev] Configuration reference - final solution

[Manik Surtani]

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