[infinispan-dev] Configuration reference - final solution

[Vladimir Blagojevic]

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