Mircea, I use this annotation to denote property: @Retention(RetentionPolicy.RUNTIME) @Target( { ElementType.METHOD, ElementType.FIELD }) public @interface ConfigurationProperty { String parentElement(); String name(); String description() default ""; } So you can annotate any method to denote a certain property. If you need to annotate more than one property you can use @Retention(RetentionPolicy.RUNTIME) @Target( { ElementType.METHOD}) public @interface ConfigurationProperties { ConfigurationProperty [] elements(); } We can annotate those methods with multiple properties @ConfigurationProperties(elements = { @ConfigurationProperty(name = "maxThreads", parentElement = "asyncListenerExecutor"), @ConfigurationProperty(name = "threadNamePrefix", parentElement = "asyncListenerExecutor") }) public void setAsyncListenerExecutorProperties(Properties asyncListenerExecutorProperties) { testImmutability("asyncListenerExecutorProperties"); this.asyncListenerExecutorProperties = toTypedProperties(asyncListenerExecutorProperties); } and any of those simple ones as well.... Anything wrong with this simple approach? On 6/19/09 11:58 AM, Mircea Markus wrote: > Continuing a conversation Vladimir and I had on irc, about how > <property> tags can be be listed in the documentation. > > <property> are a way to configure extension points (e.g. CacheStore > implementations, ScheduledExecutorFactory implemetations etc), e.g: > > <replicationQueueScheduledExecutor > factory="org.infinispan.executors.DefaultScheduledExecutorFactory"> > <property name="threadNamePrefix" value="ReplicationQueueThread"/> > </replicationQueueScheduledExecutor> > > "threadNamePrefix" property is specific to > DefaultScheduledExecutorFactory, other implementations of > ScheduledExecutorFactory would not recognize it, and/or use > different properties. > So there's no way to handle "property" tags as the other 'regular' > attributes that map to fixed configuration elements: e.g. > transportClass maps to GlobalConfiguration#transportClass etc. > Even more, in some situations these properties are not being used > to call setters on the target objects, but are being passed all > together through a java.util.Properties: which makes them > impossible/harder to annotate. > > On the other hand it would be very nice to have all the properties > of default extension points (e.g. FileCacheStore, > JdbcStringBasedCacheStore etc) having all the documentation exposed > through annotations. > A possible way I see to make this working is: > 1) create a new annotation to denote an extension point, > @ExtenssionPoint(defaultImplementations={ClassName1, ClassName2, > ClassName3}) > e.g. > > CacheLoaderConfig > { @ExtenssionPoint > (defaultImplementations={FileCacheStore.class, > JdbcStringBasedCacheStore.class}) //this will break module > dependency, guess strings should be used > void setCacheLoaderClassName(String s); > } > > 2) For all existing extension points the tool will create a > different table containing all its specific properties, obtained by > parsing class's @Property tags > > 3) Make all the current extension points that use > java.util.Property are replace by setters that can be annotated: > this way we would remain consistent in all code, and IMHO the code > would be more readable > > wdyt? > Cheers, > Mircea > _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

Hey, We want to use these annotations to create infinispan configuration option documentation directly from the source code as well as to read XML config files and populate corresponding configuration beans with xml data. If we go with expressive annotations we would end up with many many annotations.... On 6/20/09 1:11 PM, Emmanuel Bernard wrote: > Guys, String based parameters are as much XML than well XML. > Can't you create nice clean expressive annotations > > @InfinispanConfig > public @interface ListenerExecutor { > int maxThread() default 5; > String theadNamePrefix() default ""; > } > > etc > > On Jun 19, 2009, at 13:31, Vladimir Blagojevic wrote: > >> Mircea, >> >> I use this annotation to denote property: >> >> @Retention(RetentionPolicy.RUNTIME) >> @Target( { ElementType.METHOD, ElementType.FIELD }) >> public @interface ConfigurationProperty { >> String parentElement(); >> String name(); >> String description() default ""; >> } >> >> So you can annotate any method to denote a certain property. If >> you need to annotate more than one property you can use >> >> >> @Retention(RetentionPolicy.RUNTIME) >> @Target( { ElementType.METHOD}) >> public @interface ConfigurationProperties { >> ConfigurationProperty [] elements(); >> } >> >> >> We can annotate those methods with multiple properties >> >> @ConfigurationProperties(elements = { >> @ConfigurationProperty(name = "maxThreads", >> parentElement = "asyncListenerExecutor"), >> @ConfigurationProperty(name = "threadNamePrefix", >> parentElement = "asyncListenerExecutor") }) >> public void setAsyncListenerExecutorProperties(Properties >> asyncListenerExecutorProperties) { >> testImmutability("asyncListenerExecutorProperties"); >> this.asyncListenerExecutorProperties = >> toTypedProperties(asyncListenerExecutorProperties); >> } >> >> and any of those simple ones as well.... >> >> >> Anything wrong with this simple approach? >> >> >> >> >> On 6/19/09 11:58 AM, Mircea Markus wrote: >>> Continuing a conversation Vladimir and I had on irc, about how >>> <property> tags can be be listed in the documentation. >>> >>> <property> are a way to configure extension points (e.g. >>> CacheStore implementations, ScheduledExecutorFactory >>> implemetations etc), e.g: >>> >>> <replicationQueueScheduledExecutor >>> factory="org.infinispan.executors.DefaultScheduledExecutorFactory"> >>> <property name="threadNamePrefix" value="ReplicationQueueThread"/> >>> </replicationQueueScheduledExecutor> >>> >>> "threadNamePrefix" property is specific to >>> DefaultScheduledExecutorFactory, other implementations of >>> ScheduledExecutorFactory would not recognize it, and/or use >>> different properties. >>> So there's no way to handle "property" tags as the other >>> 'regular' attributes that map to fixed configuration elements: >>> e.g. transportClass maps to GlobalConfiguration#transportClass etc. >>> Even more, in some situations these properties are not being used >>> to call setters on the target objects, but are being passed all >>> together through a java.util.Properties: which makes them >>> impossible/harder to annotate. >>> >>> On the other hand it would be very nice to have all the >>> properties of default extension points (e.g. FileCacheStore, >>> JdbcStringBasedCacheStore etc) having all the documentation >>> exposed through annotations. >>> A possible way I see to make this working is: >>> 1) create a new annotation to denote an extension point, >>> @ExtenssionPoint(defaultImplementations={ClassName1, ClassName2, >>> ClassName3}) >>> e.g. >>> >>> CacheLoaderConfig >>> { @ExtenssionPoint >>> (defaultImplementations={FileCacheStore.class, >>> JdbcStringBasedCacheStore.class}) //this will break module >>> dependency, guess strings should be used >>> void setCacheLoaderClassName(String s); >>> } >>> >>> 2) For all existing extension points the tool will create a >>> different table containing all its specific properties, obtained >>> by parsing class's @Property tags >>> >>> 3) Make all the current extension points that use >>> java.util.Property are replace by setters that can be annotated: >>> this way we would remain consistent in all code, and IMHO the >>> code would be more readable >>> >>> wdyt? >>> Cheers, >>> Mircea >>> >> >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev >

We and others already use configuration beans directly (subclasses of AbstractConfigurationBean) to configure infinispan instances. However, we "manually" read data from xml and populate those beans with data. We want to make this reading more automatic via metadata available in annotations. On 6/22/09 9:32 AM, Emmanuel Bernard wrote: > You mean people could actually populate beans themselves to > programmatically create the InfiniSpan config? > > On Jun 22, 2009, at 09:25, Vladimir Blagojevic wrote: > >> Hey, >> >> We want to use these annotations to create infinispan >> configuration option documentation directly from the source code >> as well as to read XML config files and populate corresponding >> configuration beans with xml data. >> >> If we go with expressive annotations we would end up with many >> many annotations....

On 6/22/09 10:52 AM, Emmanuel Bernard wrote: > OK here is my take. > > Populating bean is fairly PITA for a user and a fluent API approach > makes configuration more readable. Fluent config API is the one that allows chaining calls, right? These are very elegant, but they seem more suitable for configs that follow more of a grammar like structure. Infinispan's config tree is not so nice so to speak. > > http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/test/java/org/h... > (check NotUseddefineMapping) > and the root class > http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/main/java/org/h... > > if you want to stay on the bean side, I am wondering why you don't > use JAXB or something like that to bind the XML model to the object > model. We want to reuse these annotations to kill three birds with one stone. Configuration beans are the source, or if you want - code is the source. We annotate those beans and get for free human readable configuration documentation, configuration schema, and, if possible, use those annotations in conjunction with beans to populate the beans automatically during configuration reading from xml. Does it make better sense now? Appreciate your input! Regards, Vladimir _______________________________________________ infinispan-dev mailing list infinispan-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev

Just a remark, when was the last time you found a documentation listing all possible parameters with a one line description useful? The MBean style documentation of JBoss AS was horrible :) Task oriented documentations are much more useful but cannot be generated.

On Jul 7, 2009, at 13:14, Manik Surtani wrote: > Interesting discussions. > > I agree that JAXB *would* have been the ideal way about this, but > that brings in a) additional deps with Java5, and b) a not-so- > pretty object model for configuration beans, and c) does not help > us generate docs. > > So essentially we have: > > 1) a simple(-ish) object model for programmatic configuration. > 2) an XML parser to parse a coherent XML file and generate the > beans in (1). > 3) documentation for all setters in (1) and all elements/attributes > in (2). > > As Vladimir pointed out, this effort is to remove the hand-written > parser we have which handles (2), and to save us writing hand- > written docs for (3). By annotating the object model in (1), we > can generate appropriate documentation for (3) as well as parse XML > to populate the bean for (2). > > Emmanuel, note that these annotations are internal only and are not > public API. End users would configure stuff by doing: > > Configuration c = new Configuration(); > c.setBlah( blah ); > > The annotations are purely for core devs who would need to add a > new configuration element for new feature X. By adding a new > getter and setter to the Configuration bean, and appropriately > annotating it, this new config element is automagically added to > the XSD, will be parsed from XML, and is documented. > > That said, I do like the "fluent config" approach where folks can do: > > c.setBlah( blah ).setFoo( foo ); > > HTH, > Cheers > Manik > > On 22 Jun 2009, at 18:41, Vladimir Blagojevic wrote: > >> On 6/22/09 10:52 AM, Emmanuel Bernard wrote: >>> OK here is my take. >>> >>> Populating bean is fairly PITA for a user and a fluent API >>> approach makes configuration more readable. >> Fluent config API is the one that allows chaining calls, right? >> These are very elegant, but they seem more suitable for configs >> that follow more of a grammar like structure. Infinispan's config >> tree is not so nice so to speak. >>> >>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/test/java/org/h... >>> (check NotUseddefineMapping) >>> and the root class >>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/main/java/org/h... >>> >>> if you want to stay on the bean side, I am wondering why you >>> don't use JAXB or something like that to bind the XML model to >>> the object model. >> >> We want to reuse these annotations to kill three birds with one >> stone. Configuration beans are the source, or if you want - code >> is the source. We annotate those beans and get for free human >> readable configuration documentation, configuration schema, and, >> if possible, use those annotations in conjunction with beans to >> populate the beans automatically during configuration reading from >> xml. >> >> Does it make better sense now? Appreciate your input! >> >> Regards, >> Vladimir >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > -- > Manik Surtani > manik(a)jboss.org > Lead, Infinispan > Lead, JBoss Cache > http://www.infinispan.org > http://www.jbosscache.org > > > >

I don't want to sound like a broken record, but IMO this style of docs belongs in the schema file in xsd:documentation tags. Then IDEA and Eclipse display the docs while you are actually editing the config file. You could then use one of the many tools out there to generate docs, or extend one to produce it in a more docbook-like way. For the config API, just use javadoc, you can then describe things in a way more specific to the API.

Manik Surtani wrote: > Interesting discussions. > I agree that JAXB *would* have been the ideal way about this, but > that brings in a) additional deps with Java5, and b) a not-so- > pretty object model for configuration beans, and c) does not help > us generate docs. > So essentially we have: > 1) a simple(-ish) object model for programmatic configuration. > 2) an XML parser to parse a coherent XML file and generate the > beans in (1). > 3) documentation for all setters in (1) and all elements/attributes > in (2). > As Vladimir pointed out, this effort is to remove the hand-written > parser we have which handles (2), and to save us writing hand- > written docs for (3). By annotating the object model in (1), we > can generate appropriate documentation for (3) as well as parse XML > to populate the bean for (2). > Emmanuel, note that these annotations are internal only and are not > public API. End users would configure stuff by doing: > Configuration c = new Configuration(); > c.setBlah( blah ); > The annotations are purely for core devs who would need to add a > new configuration element for new feature X. By adding a new > getter and setter to the Configuration bean, and appropriately > annotating it, this new config element is automagically added to > the XSD, will be parsed from XML, and is documented. > That said, I do like the "fluent config" approach where folks can do: > c.setBlah( blah ).setFoo( foo ); > HTH, > Cheers > Manik > On 22 Jun 2009, at 18:41, Vladimir Blagojevic wrote: >> On 6/22/09 10:52 AM, Emmanuel Bernard wrote: >>> OK here is my take. >>> >>> Populating bean is fairly PITA for a user and a fluent API >>> approach makes configuration more readable. >> Fluent config API is the one that allows chaining calls, right? >> These are very elegant, but they seem more suitable for configs >> that follow more of a grammar like structure. Infinispan's config >> tree is not so nice so to speak. >>> >>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/test/java/org/h... >>> (check NotUseddefineMapping) >>> and the root class >>> http://anonsvn.jboss.org/repos/hibernate/search/trunk/src/main/java/org/h... >>> >>> if you want to stay on the bean side, I am wondering why you >>> don't use JAXB or something like that to bind the XML model to >>> the object model. >> >> We want to reuse these annotations to kill three birds with one >> stone. Configuration beans are the source, or if you want - code >> is the source. We annotate those beans and get for free human >> readable configuration documentation, configuration schema, and, >> if possible, use those annotations in conjunction with beans to >> populate the beans automatically during configuration reading from >> xml. >> >> Does it make better sense now? Appreciate your input! >> >> Regards, >> Vladimir >> _______________________________________________ >> infinispan-dev mailing list >> infinispan-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > -- > Manik Surtani > manik(a)jboss.org > Lead, Infinispan > Lead, JBoss Cache > http://www.infinispan.org > http://www.jbosscache.org > _______________________________________________ > infinispan-dev mailing list > infinispan-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev -- Jason T. Greene JBoss, a division of Red Hat

On 7/9/09 11:58 AM, Manik Surtani wrote: > > On 8 Jul 2009, at 19:46, Jason T. Greene wrote: > >> I don't want to sound like a broken record, but IMO this style of >> docs belongs in the schema file in xsd:documentation tags. Then >> IDEA and Eclipse display the docs while you are actually editing >> the config file. You could then use one of the many tools out >> there to generate docs, or extend one to produce it in a more >> docbook-like way. >> >> For the config API, just use javadoc, you can then describe things >> in a way more specific to the API. > > +1 to putting this information in the XSD in documentation tags, > but this should be done by the XSD generation tool based on > annotated info. I just think that if docs are in two separate > places, they are not going to get maintained in the long run and > will degenerate. Exactly! Jason, I am almost done with xml configuration reading based on combination of reflection and annotations of configuration (the nutshell is like 100 lines of code). We already create human readable configuration reference from the same source. And now on top of it if we can create, and I think we can, xsd schema along with xsd documentation tags that come from the same annotations then that would be an achievement worth at least one blog entry and one round of beers on Manik!!! Maintenance cost of Infinispan configuration converging to zero! No bull!

This approach is nice and very effective, but I'm not sure will work for "property" tags. that's because these property tags depend on the object they configure. E.g.: 1) file cache store: <loader class="org.infinispan.loaders.jdbc.binary.FileCacheStore"> <properties> <property name="location" value="/tmp"/> </properties> <loader> 2) JDBC cache store: <loader class="org.infinispan.loaders.file.FileCacheStore"> <properties> <property name="dropTableOnExit" value="false"/> <property name="bucketTableName" value="jdb_table_name"/> <property name="idColumnType" value="id_column_type"/> </properties> <loader> As per this example, possible 'propery' tags within loader element depend on the value supplied to class, and that's what I was referring to. Now logically, these properties are only present for extension points. By extension point I mean something that is pluggable in ispn, e.g. CacheStore interface is an extension point as it can be implemented and plugged in. What I was trying to define is a way to also document existing implementations of these extension points.