8:16 a.m.
Hi,
I asked to work on "Document all configuration options available in XML
and the Configuration beans on the wiki" JIRA [1] thinking that it would
be a familiar task - something similar to what Bela and I did in JGroups.
However, now, after learning a bit about how infinispan is configured,
how configuration is maintained, I would suggest we do a bit more in a
scope of this task, if possible. Being a newbie, it is highly likely
that I am overlooking some details. I would keep all current
configuration beans, that is all subclasses of AbstractConfigurationBean
but introduce annotation(s) for those beans that would:
- have some form of configuration xpath element matching xml element in
conf file
- describe each configuration option in plain english
- ref to classes to process certain complex elements
and others as the need arise.
I would also:
- remove current hand maintained schema
- create schema by automated tools given metadata in annotations
- create all human readable documentation from these annotations ; my
original JIRA [1]
- read all configuration elements from xml using metadata in annotations
thus avoiding "by hand" reading we have now
Let me know what you think and especially you, Mircea (being most
familiar with conf), if you think this is feasible.
Regards,
Vladimir
[1] https://jira.jboss.org/jira/browse/ISPN-89
8:36 a.m.
On 5 Jun 2009, at 14:16, Vladimir Blagojevic wrote:
Hi,
I asked to work on "Document all configuration options available in
XML and the Configuration beans on the wiki" JIRA [1] thinking that
it would be a familiar task - something similar to what Bela and I
did in JGroups.
However, now, after learning a bit about how infinispan is
configured, how configuration is maintained, I would suggest we do a
bit more in a scope of this task, if possible. Being a newbie, it is
highly likely that I am overlooking some details. I would keep all
current configuration beans, that is all subclasses of
AbstractConfigurationBean but introduce annotation(s) for those
beans that would:
- have some form of configuration xpath element matching xml element
in conf file
- describe each configuration option in plain english
- ref to classes to process certain complex elements
Yes, this is what I had in mind, except that since there is to 1 to 1
mapping between config bean and XML element, I would annotate each
method (setter?) with a reference to the XML element in question (full
path to it - e.g., infinispan/namedCache/cluster/sync) as well as
default value, allowed values and a plain-English description.
and others as the need arise.
I would also:
- remove current hand maintained schema
+1
- create schema by automated tools given metadata in annotations
+1
- create all human readable documentation from these annotations ;
my original JIRA [1]
- read all configuration elements from xml using metadata in
annotations thus avoiding "by hand" reading we have now
+1.
Let me know what you think and especially you, Mircea (being most
familiar with conf), if you think this is feasible.
All sounds great, however I would break this up into a 2-step process
with 2 separate JIRAs. The current JIRA - just annotate the config
beans and generate documentation, and the 2nd JIRA to use this
metadata to generate XSD and parse XML.
Cheers
Manik
--
Manik Surtani
manik(a)jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org
8:48 a.m.
On 6/5/09 3:36 PM, Manik Surtani wrote:
All sounds great, however I would break this up into a 2-step process
with 2 separate JIRAs. The current JIRA - just annotate the config
beans and generate documentation, and the 2nd JIRA to use this
metadata to generate XSD and parse XML.
Deal! This will keep me very busy and having fun at work entire next
week! Cheers
9:23 a.m.
On 5 Jun 2009, at 14:48, Vladimir Blagojevic wrote:
On 6/5/09 3:36 PM, Manik Surtani wrote:
>
> All sounds great, however I would break this up into a 2-step
> process with 2 separate JIRAs. The current JIRA - just annotate
> the config beans and generate documentation, and the 2nd JIRA to
> use this metadata to generate XSD and parse XML.
>
Deal! This will keep me very busy and having fun at work entire next
week! Cheers
Sounds great!
--
Manik Surtani
manik(a)jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org
10:01 a.m.
Vladimir Blagojevic wrote:
I would also:
- remove current hand maintained schema
- create schema by automated tools given metadata in annotations
- create all human readable documentation from these annotations ; my
original JIRA [1]
- read all configuration elements from xml using metadata in annotations
thus avoiding "by hand" reading we have now
Sounds like JAXB :) Although the issue with that, from the last time I
suggested it is that it brings in an extra dep on JDK5. JDK5 will be
end-of-life soon though.
--
Jason T. Greene
JBoss, a division of Red Hat
10:20 a.m.
On Fri, Jun 5, 2009 at 11:01 AM, Jason T. Greene <jason.greene(a)redhat.com>wrote:
Vladimir Blagojevic wrote:
> I would also:
>
> - remove current hand maintained schema
> - create schema by automated tools given metadata in annotations
> - create all human readable documentation from these annotations ; my
> original JIRA [1]
> - read all configuration elements from xml using metadata in annotations
> thus avoiding "by hand" reading we have now
>
Sounds like JAXB :) Although the issue with that, from the last time I
suggested it is that it brings in an extra dep on JDK5. JDK5 will be
end-of-life soon though.
by my understanding is not JAXB, but homemade annotations as the ones made
in jgroups, that will be able to create all human readable documentation..
--
Jason T. Greene
JBoss, a division of Red Hat
_______________________________________________
infinispan-dev mailing list
infinispan-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev
--
Alejandro Montenegro del Pino.
Viña del Mar - Chile
phone: (+56) 9-68358690
9:35 a.m.
On 5 Jun 2009, at 16:20, Alejandro Montenegro wrote:
On Fri, Jun 5, 2009 at 11:01 AM, Jason T. Greene
<jason.greene(a)redhat.com
> wrote:
Vladimir Blagojevic wrote:
I would also:
- remove current hand maintained schema
- create schema by automated tools given metadata in annotations
- create all human readable documentation from these annotations ;
my original JIRA [1]
- read all configuration elements from xml using metadata in
annotations thus avoiding "by hand" reading we have now
Sounds like JAXB :) Although the issue with that, from the last time
I suggested it is that it brings in an extra dep on JDK5. JDK5 will
be end-of-life soon though.
by my understanding is not JAXB, but homemade annotations as the
ones made in jgroups, that will be able to create all human readable
documentation..
Well, the bit about parsing XML into the Configuration bean is very
JAXB-like. This is why I suggested that Vladimir splits this up into
2 separate JIRAs - one to annotate the Configuration bean so that we
can generate meaningful documentation from it - and to actually write
the custom Doclet to do so, and the second to generate the XSD and
parse configuration XML files. Which may well end up using JAXB,
especially since, as Jason pointed out, JAXB is in Java6.
Cheers
--
Manik Surtani
manik(a)jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org
4:06 p.m.
On 6/5/09 5:01 PM, Jason T. Greene wrote:
Vladimir Blagojevic wrote:
> I would also:
>
> - remove current hand maintained schema
> - create schema by automated tools given metadata in annotations
> - create all human readable documentation from these annotations ; my
> original JIRA [1]
> - read all configuration elements from xml using metadata in
> annotations thus avoiding "by hand" reading we have now
Sounds like JAXB :) Although the issue with that, from the last time I
suggested it is that it brings in an extra dep on JDK5. JDK5 will be
end-of-life soon though.
This can be done without JAXB, plain old DOM reading/writing.
11:25 p.m.
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.
Sent from my iPhone
On Jun 7, 2009, at 4:06 PM, Vladimir Blagojevic <vblagoje(a)redhat.com>
wrote:
On 6/5/09 5:01 PM, Jason T. Greene wrote:
> Vladimir Blagojevic wrote:
>> I would also:
>>
>> - remove current hand maintained schema
>> - create schema by automated tools given metadata in annotations
>> - create all human readable documentation from these annotations ;
>> my original JIRA [1]
>> - read all configuration elements from xml using metadata in
>> annotations thus avoiding "by hand" reading we have now
>
> Sounds like JAXB :) Although the issue with that, from the last
> time I suggested it is that it brings in an extra dep on JDK5. JDK5
> will be end-of-life soon though.
>
This can be done without JAXB, plain old DOM reading/writing.
7:36 a.m.
On 6/8/09 6:25 AM, jason.greene(a)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.
7:43 a.m.
On 6/8/09 2:36 PM, Vladimir Blagojevic wrote:
On 6/8/09 6:25 AM, jason.greene(a)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;
}
@Retention(RetentionPolicy.RUNTIME)
@Target( { ElementType.METHOD})
public @interface ConfigurationAttribute {
String parentElement();
String name();
String allowedValues() default "";
String defaultValue() default "";
String description() default "";
}
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
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
8:11 a.m.
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(a)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(a)jboss.org
Lead, Infinispan
Lead, JBoss Cache
http://www.infinispan.org
http://www.jbosscache.org
10:20 a.m.
On 6/9/09 3:11 PM, Manik Surtani wrote:
> @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 ... />.
Yeah, sorry forgot name() attribute here. We might not need parent. Will
see.
>
> @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.
I meant containing element, an element that attribute belongs to. Yes
for allowedValues.
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. :)
Yes, 96 is a lot
of work. WIll first finish 89 and by the time we are
done with 89 more details about 96 will crystallize.
Vladimir
5754
days inactive
5758
days old
infinispan-dev@lists.jboss.org
12 comments
5 participants
participants (5)
-
Alejandro Montenegro -
Jason T. Greene -
jason.greene＠redhat.com
-
Manik Surtani -
Vladimir Blagojevic