Re: [infinispan-dev] Configuration reference - final solution

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