Recently, I was assigned to complete https://jira.jboss.org/jira/browse/ISPN-97 The driving force behind this JIRA was to achieve a minimal maintenance of Infinispan XML configuration. We have scarce resources but we needed to: maintain professional looking HTML configuration reference, keep a well documented XML schema for configuration files, and finally we wanted to achieve seamless marshaling from XML configuration files into configuration object model. Since configuration reference and schema need to be generated for every release we wanted to completely automate this process. The obvious candidate library to achieve seamless unmarshalling of XML configuration files into object model was either JAXB or JBossXB. We wanted to keep our current configuration class hierarchy loosely coupled with XML schema - i.e not every type in XML schema mapped into an appropriate class in configuration hierarchy. In another words we wanted to group configuration attributes into many XML elements but did not want to have as many classes in our configuration class hierarchy. Any solution to this problem, including JBossXB, requires maintenance of mapping between XML schema types and our configuration class hierarchy. Not a big problem, but this was a first hurdle in a serious of hurdles. As any other HTML configuration reference Infinispan's should display default values and their types, constraints for those values, human readable descriptions and so on. If we were to generate configuration reference automatically we needed to keep this information somewhere, extract it, and spit it out. In JAXB/JBossXB based solution, the obvious place to keep this information was in a "hand maintained" schema. But schema, although it carries most of this information, is a blueprint, it does not contain all instances of all possible configuration elements. For example, our schema constrains that <loader> element has such and such form but it does not document all the configuration options for all possible loaders. The source code of those loader classes does! Another problem with keeping documentation in hand maintained schema was that all the information in schema was replicating what already existed in the source code. We already had comments, attribute types and their default values, they were already in the source. Why do we need to keep a mirror of this data and then on top of it hand maintain it along with a mapping from schema types to our configuration class hierarchy? A proper solution for all of these minor issues, but issues that create a lot of maintenance headache, lies in switching to the source code as the main source of all information we need. What we had to do was to add a bit of metadata in a form of annotations to complete everything. The algorithm to unmarshall XML configuration file into object model is about 300 lines of code [1], documentation [2] and schema generator [3] around 200 each. In conclusion, out of source code itself you automatically get a kick ass configuration documentation reference, a well documented XML schema and XML configuration unmarshalling into object model. All of this with almost zero maintenance cost. Yes, indeed, we are almost reinventing the wheel here but this is the solution we need and we would gladly contribute to a project that does exactly what we need. At the moment, I doubt that we can do this with JBossXB, Alexey please correct me if I am wrong. Since we are already having documentation reference maintenance problems in other projects maybe we should somehow extend JBossXB with annotation based framework and apply it in other projects as well? Automatically generated configuration reference is included as attachment. To view, download both stylesheet and config.html into a local directory and open config.html in your favorite browser. Regards, Vladimir [1] http://anonsvn.jboss.org/repos/infinispan/trunk/core/src/main/java/org/in... [2] http://anonsvn.jboss.org/repos/infinispan/trunk/tools/src/main/java/org/i... [3] http://anonsvn.jboss.org/repos/infinispan/trunk/tools/src/main/java/org/i... ------------------------------------------------------------------------ Infinispan configuration options <infinispan <#ce__infinispan>> <default <#ce_infinispan_default>> <jmxStatistics <#ce_default_jmxStatistics>> <loaders <#ce_default_loaders>> <loader <#ce_loaders_loader>> <async <#ce_loader_async>> <singletonStore <#ce_loader_singletonStore>> <properties <#ce_loader_properties>> <clustering <#ce_default_clustering>> <async <#ce_clustering_async>> <hash <#ce_clustering_hash>> <sync <#ce_clustering_sync>> <l1 <#ce_clustering_l1>> <stateRetrieval <#ce_clustering_stateRetrieval>> <lazyDeserialization <#ce_default_lazyDeserialization>> <eviction <#ce_default_eviction>> <expiration <#ce_default_expiration>> <invocationBatching <#ce_default_invocationBatching>> <locking <#ce_default_locking>> <transaction <#ce_default_transaction>> <customInterceptors <#ce_default_customInterceptors>> <interceptor <#ce_customInterceptors_interceptor>> <unsafe <#ce_default_unsafe>> <namedCache <#ce_infinispan_namedCache>> <global <#ce_infinispan_global>> <globalJmxStatistics <#ce_global_globalJmxStatistics>> <shutdown <#ce_global_shutdown>> <replicationQueueScheduledExecutor <#ce_global_replicationQueueScheduledExecutor>> <evictionScheduledExecutor <#ce_global_evictionScheduledExecutor>> <serialization <#ce_global_serialization>> <asyncTransportExecutor <#ce_global_asyncTransportExecutor>> <asyncListenerExecutor <#ce_global_asyncListenerExecutor>> <transport <#ce_global_transport>> loader org.infinispan.loaders.s3.S3CacheStore Parent element is <loaders> <#ce_default_loaders>. Child elements are <async> <#ce_loader_async>,<singletonStore> <#ce_loader_singletonStore>,<properties> <#ce_loader_properties>. Attribute Type Default Description |fetchPersistentState| |boolean| false If true, fetch persistent state on state transfer |ignoreModifications| |boolean| false If true, any operation that modifies the cache store (remove, clear, store...etc) won't be applied to it |purgeOnStartup| |boolean| false If true, purge node state on startup |class| |String| org.infinispan.loaders.s3.S3CacheStore Full class name of a cache loader properties todo Parent element is <loader> <#ce_loaders_loader>. Property Description requestTimeout todo maxConnections todo secure todo awsAccessKey todo awsSecretKey todo bucket todo proxyHost todo proxyPort todo lockConcurrencyLevel Concurrency level as integer. Default is 2048 lockAcquistionTimeout Default lock acquisition timeout as long. Default is 60000 default todo Parent element is <infinispan> <#ce__infinispan>. Child elements are <jmxStatistics> <#ce_default_jmxStatistics>,<loaders> <#ce_default_loaders>,<clustering> <#ce_default_clustering>,<lazyDeserialization> <#ce_default_lazyDeserialization>,<eviction> <#ce_default_eviction>,<expiration> <#ce_default_expiration>,<invocationBatching> <#ce_default_invocationBatching>,<locking> <#ce_default_locking>,<transaction> <#ce_default_transaction>,<customInterceptors> <#ce_default_customInterceptors>,<unsafe> <#ce_default_unsafe>. namedCache todo Parent element is <infinispan> <#ce__infinispan>. locking todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |writeSkewCheck| |boolean| false todo |concurrencyLevel| |int| 500 todo |lockAcquisitionTimeout| |long| 10000 todo |isolationLevel| |String|* (NONE|SERIALIZABLE|REPEATABLE_READ|READ_COMMITTED|READ_UNCOMMITTED) READ_COMMITTED todo transaction todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |transactionManagerLookupClass| |String| org.infinispan.transaction.lookup.GenericTransactionManagerLookup todo |syncCommitPhase| |boolean| false todo |syncRollbackPhase| |boolean| false todo |useEagerLocking| |boolean| false todo jmxStatistics todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |enabled| |boolean| false todo lazyDeserialization todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |enabled| |boolean| false todo invocationBatching todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |enabled| |boolean| false todo clustering todo Parent element is <default> <#ce_infinispan_default>. Child elements are <async> <#ce_clustering_async>,<hash> <#ce_clustering_hash>,<sync> <#ce_clustering_sync>,<l1> <#ce_clustering_l1>,<stateRetrieval> <#ce_clustering_stateRetrieval>. Attribute Type Default Description |mode| |String|* (LOCAL|REPL|INVALIDATION|DIST) LOCAL todo stateRetrieval todo Parent element is <clustering> <#ce_default_clustering>. Attribute Type Default Description |fetchInMemoryState| |boolean| false todo |timeout| |long| 10000 todo sync todo Parent element is <clustering> <#ce_default_clustering>. Attribute Type Default Description |replTimeout| |long| 15000 todo hash todo Parent element is <clustering> <#ce_default_clustering>. Attribute Type Default Description |rehashRpcTimeout| |long| 600000 todo |consistentHashClass| |String| org.infinispan.distribution.DefaultConsistentHash todo |numOwners| |int| 2 todo |rehashWait| |long| 60000 todo l1 todo Parent element is <clustering> <#ce_default_clustering>. Attribute Type Default Description |enabled| |boolean| true todo |lifespan| |long| 600000 todo |onRehash| |boolean| true todo async todo Parent element is <clustering> <#ce_default_clustering>. Attribute Type Default Description |replQueueMaxElements| |int| 1000 todo |replQueueInterval| |long| 5000 todo |useReplQueue| |boolean| false todo |asyncMarshalling| |boolean| true todo eviction todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |wakeUpInterval| |long| 5000 todo |strategy| |String|* (NONE|FIFO|LRU) NONE todo |maxEntries| |int| -1 todo expiration todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |lifespan| |long| -1 todo |maxIdle| |long| -1 todo unsafe todo Parent element is <default> <#ce_infinispan_default>. Attribute Type Default Description |unreliableReturnValues| |boolean| false todo customInterceptors todo Parent element is <default> <#ce_infinispan_default>. Child elements are <interceptor> <#ce_customInterceptors_interceptor>. loaders todo Parent element is <default> <#ce_infinispan_default>. Child elements are <loader> <#ce_loaders_loader>. Attribute Type Default Description |preload| |boolean| false todo |passivation| |boolean| false todo |shared| |boolean| false todo loader org.infinispan.loaders.bdbje.BdbjeCacheStore Parent element is <loaders> <#ce_default_loaders>. Child elements are <async> <#ce_loader_async>,<singletonStore> <#ce_loader_singletonStore>,<properties> <#ce_loader_properties>. Attribute Type Default Description |fetchPersistentState| |boolean| false If true, fetch persistent state on state transfer |ignoreModifications| |boolean| false If true, any operation that modifies the cache store (remove, clear, store...etc) won't be applied to it |purgeOnStartup| |boolean| false If true, purge node state on startup |class| |String| org.infinispan.loaders.bdbje.BdbjeCacheStore Full class name of a cache loader properties todo Parent element is <loader> <#ce_loaders_loader>. Property Description lockAcquistionTimeout todo cacheDbName todo catalogDbName todo expiryDbName todo maxTxRetries todo location todo loader org.infinispan.loaders.jdbc.stringbased.JdbcStringBasedCacheStore Parent element is <loaders> <#ce_default_loaders>. Child elements are <async> <#ce_loader_async>,<singletonStore> <#ce_loader_singletonStore>,<properties> <#ce_loader_properties>. Attribute Type Default Description |fetchPersistentState| |boolean| false If true, fetch persistent state on state transfer |ignoreModifications| |boolean| false If true, any operation that modifies the cache store (remove, clear, store...etc) won't be applied to it |purgeOnStartup| |boolean| false If true, purge node state on startup |class| |String| org.infinispan.loaders.jdbc.stringbased.JdbcStringBasedCacheStore Full class name of a cache loader properties todo Parent element is <loader> <#ce_loaders_loader>. Property Description batchSize todo fetchSize todo createTableOnStart todo dropTableOnExit todo idColumnName todo idColumnType todo dataColumnName todo dataColumnType todo timestampColumnName todo connectionUrl todo userName todo password todo driverClass todo connectionFactoryClass todo key2StringMapper todo stringsTableName todo lockConcurrencyLevel Concurrency level as integer. Default is 2048 lockAcquistionTimeout Default lock acquisition timeout as long. Default is 60000 global todo Parent element is <infinispan> <#ce__infinispan>. Child elements are <globalJmxStatistics> <#ce_global_globalJmxStatistics>,<shutdown> <#ce_global_shutdown>,<replicationQueueScheduledExecutor> <#ce_global_replicationQueueScheduledExecutor>,<evictionScheduledExecutor> <#ce_global_evictionScheduledExecutor>,<serialization> <#ce_global_serialization>,<asyncTransportExecutor> <#ce_global_asyncTransportExecutor>,<asyncListenerExecutor> <#ce_global_asyncListenerExecutor>,<transport> <#ce_global_transport>. asyncListenerExecutor todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |factory| |String| org.infinispan.executors.DefaultExecutorFactory ExecutorService factory class for asynchronous listeners Property Description maxThreads todo threadNamePrefix todo transport todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |transportClass| |String| org.infinispan.remoting.transport.jgroups.JGroupsTransport Transport class, by default null i.e. no transport |clusterName| |String| Infinispan-Cluster todo |distributedSyncTimeout| |long| 60000 todo Property Description configurationString todo configurationFile todo configurationXml todo evictionScheduledExecutor todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |factory| |String| org.infinispan.executors.DefaultScheduledExecutorFactory ExecutorService factory class for eviction threads Property Description maxThreads todo threadNamePrefix todo replicationQueueScheduledExecutor todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |factory| |String| org.infinispan.executors.DefaultScheduledExecutorFactory ExecutorService factory class for replication queue threads Property Description maxThreads todo threadNamePrefix todo globalJmxStatistics todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |enabled| |boolean| false If true, global JMX statistics are published |jmxDomain| |String| infinispan If JMX statistics are enabled then all 'published' JMX objects will appear under this name |mBeanServerLookup| |String| org.infinispan.jmx.PlatformMBeanServerLookup todo |allowDuplicateDomains| |boolean| false todo asyncTransportExecutor todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |factory| |String| org.infinispan.executors.DefaultExecutorFactory ExecutorService factory class for async transport Property Description maxThreads todo threadNamePrefix todo serialization todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |marshallerClass| |String| org.infinispan.marshall.VersionAwareMarshaller todo |version| |String| 4.0.0.SNAPSHOT todo shutdown todo Parent element is <global> <#ce_infinispan_global>. Attribute Type Default Description |hookBehavior| |String|* (DEFAULT|REGISTER|DONT_REGISTER) DEFAULT todo async todo Parent element is <loader> <#ce_loaders_loader>. Attribute Type Default Description |batchSize| |int| 100 TODO |threadPoolSize| |int| 1 TODO |enabled| |boolean| false TODO loader org.infinispan.loaders.jdbc.binary.JdbcBinaryCacheStore Parent element is <loaders> <#ce_default_loaders>. Child elements are <async> <#ce_loader_async>,<singletonStore> <#ce_loader_singletonStore>,<properties> <#ce_loader_properties>. Attribute Type Default Description |fetchPersistentState| |boolean| false If true, fetch persistent state on state transfer |ignoreModifications| |boolean| false If true, any operation that modifies the cache store (remove, clear, store...etc) won't be applied to it |purgeOnStartup| |boolean| false If true, purge node state on startup |class| |String| org.infinispan.loaders.jdbc.binary.JdbcBinaryCacheStore Full class name of a cache loader properties todo Parent element is <loader> <#ce_loaders_loader>. Property Description batchSize todo fetchSize todo createTableOnStart todo dropTableOnExit todo bucketTableName todo idColumnName todo idColumnType todo dataColumnName todo dataColumnType todo timestampColumnName todo timestampColumnType todo connectionUrl todo userName todo password todo driverClass todo connectionFactoryClass todo lockConcurrencyLevel Concurrency level as integer. Default is 2048 lockAcquistionTimeout Default lock acquisition timeout as long. Default is 60000 loader org.infinispan.loaders.file.FileCacheStore Parent element is <loaders> <#ce_default_loaders>. Child elements are <async> <#ce_loader_async>,<singletonStore> <#ce_loader_singletonStore>,<properties> <#ce_loader_properties>. Attribute Type Default Description |fetchPersistentState| |boolean| false If true, fetch persistent state on state transfer |ignoreModifications| |boolean| false If true, any operation that modifies the cache store (remove, clear, store...etc) won't be applied to it |purgeOnStartup| |boolean| false If true, purge node state on startup |class| |String| org.infinispan.loaders.file.FileCacheStore Full class name of a cache loader properties todo Parent element is <loader> <#ce_loaders_loader>. Property Description location Path to file lockConcurrencyLevel Concurrency level as integer. Default is 2048 lockAcquistionTimeout Default lock acquisition timeout as long. Default is 60000 loader org.infinispan.loaders.jdbc.mixed.JdbcMixedCacheStore Parent element is <loaders> <#ce_default_loaders>. Child elements are <async> <#ce_loader_async>,<singletonStore> <#ce_loader_singletonStore>,<properties> <#ce_loader_properties>. Attribute Type Default Description |fetchPersistentState| |boolean| false If true, fetch persistent state on state transfer |ignoreModifications| |boolean| false If true, any operation that modifies the cache store (remove, clear, store...etc) won't be applied to it |purgeOnStartup| |boolean| false If true, purge node state on startup |class| |String| org.infinispan.loaders.jdbc.mixed.JdbcMixedCacheStore Full class name of a cache loader properties todo Parent element is <loader> <#ce_loaders_loader>. Property Description batchSize todo lockAcquistionTimeout todo fetchSize todo connectionUrl todo userName todo password todo driverClass todo idColumnNameForStrings todo idColumnTypeForStrings todo tableNameForStrings todo dataColumnNameForStrings todo dataColumnTypeForStrings todo timestampColumnNameForStrings todo timestampColumnTypeForStrings todo createTableOnStartForStrings todo dropTableOnExitForStrings todo idColumnNameForBinary todo idColumnTypeForBinary todo tableNameForBinary todo dataColumnNameForBinary todo dataColumnTypeForBinary todo timestampColumnNameForBinary todo timestampColumnTypeForBinary todo createTableOnStartForBinary todo dropTableOnExitForBinary todo key2StringMapperClass todo lockConcurrencyLevelForStrings todo lockConcurrencyLevelForBinary todo singletonStore todo Parent element is <loader> <#ce_loaders_loader>. Attribute Type Default Description |enabled| |boolean| false Switch to enable singleton store |pushStateWhenCoordinator| |boolean| true TODO |pushStateTimeout| |long| 10000 TODO interceptor todo Parent element is <customInterceptors> <#ce_default_customInterceptors>. Attribute Type Default Description |class| |String| null todo |after| |String| null todo |before| |String| null todo |index| |int| -1 todo |position| |String| null todo Property Description anyCustomProperty todo ------------------------------------------------------------------------ Copyright © 2009 JBoss, a division of Red Hat <http://www.jboss.org>;. All Rights Reserved. ------------------------------------------------------------------------ _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org http://lists.jboss.org/mailman/listinfo/jboss-development

On 7/17/09 5:16 PM, Bill Burke wrote: > Wouldn't it be better to write a javadoc-like generator that > introspected for JAXB and Inifispan annotations instead of writing your > own XML parser and schema generator? Or maybe I'm misunderstanding your > post. > > In other words, use JAXB for marshalling/unmarshalling/schema > generation. Use inifinispan javadoc generator for documentation. > > I looked around a bit more to see that now in JAXB 2.x we have annotations as well :) If we annotate our configuration beans with JAXB annotations I suppose we can do exactly what you suggest - use JAXB for marshalling/unmarshalling/schema generation and at the same time use those annotation in a custom tool that creates reference documentation. > By creating your own XML parsing you've just complicated the maintenance > problems for future maintainers of infinispan. > > I agree.

We also don't generate schemas