[infinispan-dev] Infinispan configuration

[Manik Surtani]

On 9 Jun 2009, at 13:43, Vladimir Blagojevic wrote:

> On 6/8/09 2:36 PM, Vladimir Blagojevic wrote:
>> On 6/8/09 6:25 AM, jason.greene at redhat.com wrote:
>>> Sure, just like it is now. Of course you don't even need Dom. The  
>>> advantage of jaxb is that it will keep the parsing logic and  
>>> schema in synch. Manual approaches tend to be a bit more brittle  
>>> and limited, just like the current approach. Unless of course you  
>>> take the time to do it right, but that is no small task.
>> Exactly. It has to be done properly. I will post details of a  
>> proposed solution for a peer review before I blindly continue on.
>>
> Hi,
>
> I looked through code, current configuration bean classes, and here  
> is what we currently have. Each complex xml element (has nested  
> elements) from configuration file is represented by one  
> configuration bean class. Furthermore, we have many cases where one  
> bean class at the same time models multiple simple child xml  
> elements (has only attributes, no nested elements). For example,  
> configuration and global xml elements are represented by  
> Configuration and GlobalConfiguration beans, while at the same time  
> both Configuration and GlobalConfiguration beans represent at least  
> a dozen other simple xml elements, children of global and  
> configuration elements. This is totally ok and probably done for  
> sake of simplicity and convenience.
>
> I think we need at least two annotations. ConfigurationElement  
> annotation matches xml element. ConfigurationElement annotating a  
> bean class captures the fact that the certain bean represents  
> certain xml element from configuration. Of course, each bean class  
> can have more than one ConfigurationElement annotation thus matching  
> our model. ConfigurationAttribute annotation matches xml attribute.  
> ConfigurationAttribute annotates setter of bean method and can only  
> annotate a method where a matching parent ConfigurationElement is  
> declared. I am not sure about the final details for attributes of  
> these annotations but here are the sketches.
>
> @Retention(RetentionPolicy.RUNTIME)
> @Target( { ElementType.TYPE})
> public @interface ConfigurationElement {
>    String parent();
>    String description() default "";
>    Class<?> readParserClass() default Void.class;
> }

A parent of "infinispan" denotes a root, I suppose?  And this would be  
hard-coded in your doclet, etc?
What about multiplicity?  E.g., you can have several <namedCache ... / 
 > elements under <infinispan ... />.

>
> @Retention(RetentionPolicy.RUNTIME)
> @Target( { ElementType.METHOD})
> public @interface ConfigurationAttribute {
>    String parentElement();
>    String name();
>    String allowedValues() default "";
>    String defaultValue() default "";
>    String description() default "";
> }

parentElement -> element?  Attributes don't have parents.  :)
AllowedValues - I am guessing this is not used for validation, but  
instead a simple message for generated docs?  Otherwise this starts to  
look a lot like JSR-303.

> Output configuration documentation algorithm
> https://jira.jboss.org/jira/browse/ISPN-89
>
> find all annotated configuration bean classes
> sort beans by path (breadth-first or whatever)
>
> for each annotated bean
>    resolve all annotated ConfigurationElement(s)
>    for each ConfigurationElement
>        output needed metadata
>        find matching ConfigurationAttribute children from annotated  
> setter methods of bean class
>        for each ConfigurationAttribute
>            output needed metadata
>        end for
>    end for
> end for

Sounds good.

> Read xml configuration algorithm
> https://jira.jboss.org/jira/browse/ISPN-96
>
> element = dom global element
> beanGlobal = visitElement(element)
>
> element = dom configuration element
> beanConfiguration = visitElement(element)
>
> ...
>
> ConfigurationBean visitElement(Dom element)
> find configuration bean with matching path name and create instance  
> of it
> reflect all bean setter methods that are annotated and store  
> annotation references
> traverse dom element children and match them to stored setter bean  
> annotations
>    - if parameter for bean setter method is a simple type
>        invoke bean setter with converted String attribute value read  
> from xml
>    - else
>        invoke bean setter with returned value of visitElement(element)
>
> return bean

Sounds good as well.  I presume you will also have a step to generate  
an XSD schema based on these rules?

Also, as a preference thing, I recommend addressing ISPN-89 first,  
since ISPN-96 seems like a lot of additional work.  With -89 in place,  
we would at least have proper generated documentation sooner.  :)

After this, you should also write a short wiki page on how to add  
configuration options.  (E.g., create getter and setter in  
Configuration, and annotate accordingly)

Cheers,
--
Manik Surtani
manik at jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org