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

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(a)jboss.org > Lead, Infinispan > Lead, JBoss Cache > http://www.infinispan.org > http://www.jbosscache.org > > > >