[webbeans-dev] RE: XML configuration format

[Michael Keith]

> -----Original Message-----
> From: Gavin King [mailto:gavin at hibernate.org]
> Sent: Wednesday, December 24, 2008 8:01 PM
> To: Michael Keith
> Cc: Scott Ferguson; Java Community Process JSR #299 Expert List; Jim
> Knutson; Matt Drees; WebBeans
> Subject: Re: XML configuration format
> 
> 
> On Wed, Dec 24, 2008 at 12:23 PM, Michael Keith
> <MICHAEL.KEITH at oracle.com> wrote:
> 
> >> What I think we should focus on here is whether the difference in
> >> styles is going to be confusing to users, and whether the web beans
> >> style of descriptor is more difficult to understand and use.
> >
> > My personal opinion is that it is more difficult to 
> understand for beginners,
> > and that there is a steeper learning curve. Once you 
> understand the rules
> > then it has more value than the existing Java EE style 
> because not only is
> > it more terse and descriptive but it is easier to map to Java code.
> 
> Yes, I would more or less go along with that, except for one 
> important quibble:
> 
> * yes, it is probably a bit more difficult for beginners to understand
> how to configure their own web beans, since it requires a couple of
> new concepts
> 
> * but it is *not* more difficult for beginners to understand how to
> configure a third-party library containing web beans - in fact it is
> much easier since they don't need to go off and look at the Java code

I don't see that one is more or less difficult. It is the configuration 
style that we are talking about here, i.e. knowing and understanding 
how the namespaces work, how elements are named and placed and the 
general system of XML web bean configuration. 

> So from the point of view of beginner, it depends upon what they have
> as the primary usecase for the XML configuration: is it configuration
> of their own web beans, or configuration of somebody else's?
> 
> I would say that beginners (and most other web bean developers) are
> going to be using annotations to config their own classes, and XML to
> configure pre-packaged libraries created by someone else.
> 
> However, I'm aware that there are some developers who still prefer to
> use XML for everything. I'm not sure exactly how many of them there
> are, nor to what extent we should to cater to their needs, nor which
> of the XML formats they prefer.

Yeah, to be honest, I'm putting aside comparisons of how many people might use 
XML vs annotations. I believe that if we are offering XML as part of the platform, 
then if even one person must use XML to configure their web beans then they have a 
certain expectation that deserves to be met.
 
> >> There's not
> >> really anything much in the way of portable 
> knowledge/skills between
> >> writing web.xml and orm.xml and faces-config.xml.
> >
> > In fact, there *are* commonalities between these 3, with 
> simple assumptions
> > that do not hold true in web beans. For example, the 
> ability to look at a
> > schema to know the complete set of elements that may 
> possibly be specified
> > in a given XML file.
> 
> Well, I disagree with you there, Mike. The idea is that we have a
> Processor running, generating a schema when the Java code is compiled.
> So both styles of XML are schema-driven. In fact the web beans style
> is much *more* schema driven, and the schema captures much more about
> what the developer can and cannot write in their XML document. When
> authoring the XML, the developer will get a *lot* more assistance from
> their tool when using the web beans style.

Really? Is that part of the spec, or just an assumption about how it
is expected to work? I don't remember reading about a schema generation 
phase.
 
> The difference is that in the case of web.xml or orm.xml, there is
> exactly one document that contains the whole schema, and the developer
> does not need to use XML namespaces. Whereas in web beans, the schema
> is partitioned between multiple files, and there is a requirement that
> the XML author understand namespaces.

Right. I meant a single canonical specification-defined schema that can
be used as a reference by any and everyone that creates a config file.
If I correctly understand your above description/expectation of schema 
generation, then knowing the schema(s) being generated and then finding, 
referencing and using them wouuld actually add an additional level of 
difficulty, I would think.

> I can well believe that there are developers who have never used
> namespaces before, but the experience we have from Seam (and also from
> Spring, I suppose) is that in practice people don't find this to be a
> barrier.

I don't think namespaces is anything like rocket science, either, but the 
point is that namespaces have just not been utilized in JEE, and so are not 
part of the current JEE development experience. But it is more than just 
namespaces, though. It is the style and rules that describe what the schema
elements are.

> > I would say that writing web beans XML, which is more
> > like code, requires a rather different mindset than what is 
> applied when
> > writing traditional Java EE descriptors.
> 
> Again, I disagree. For a developer configuring a pre-packaged library,
> the "traditional" XML style requires a lot more knowledge of the code
> (Java class, method names, etc) than the "web beans" style does. With
> the web beans style, the configuration author doesn't see anything
> about Java - everything they need to know is completely encapsulated
> in the schema for the library.

It is "more like code" because of the structure, not because you do or do not
require knowedge of the Java code. The names of the web bean classes are the 
exact names of the web bean elements (as opposed to the current pre-assigned 
element metadata names), the names of the annotations and attributes of a class 
are the exact names of the sub elements, and are direct child elements of the 
class element, and so on. There is a very concrete relationship between the 
XML elements and the Java classes, which makes the XML look very code-like, 
and as I said, requires a different mindset (more like coding than writing XML).
Again, this might be viewed as a strength. I am just saying that it represents
a change.

> 
> >> What I want to know is whether there are specific reasons why the
> >> current proposal is going to cause serious confusion or ease of use
> >> issues.
> >
> > Learning a whole new way of writing XML is an ease of use issue.
> 
> I don't know what you mean. How is it a "whole new way of 
> writing XML"?
> 
> Because it uses namespaces?
> 
> Say I'm using a library written by someone else, that can be
> configured using a web beans XML schema. How is this schema any
> different from any other XML schema that is used by developers today
> to configure stuff? Remember, the XML author is not required to know
> anything at all about the underlying Java classes and methods to
> author this configuration document. They get a schema, and they write
> XML using the elements defined by that schema. They don't know that
> the element names are actually Java class and method names.

You keep referring to the use case of a pre-existing library that is then
further configured using a web beans schema. I am new to the group, so I
don't know how much this has entered into your discussions, but my 
experience is that more often than not, the configuration of those 
components is generally written by the component developer, not some 
additional layer developer. Although it does happen, it isn't very common,
at least with the applications that I see.

> > If you don't know the rules then this new style of XML is 
> definitely confusing.
> 
> How? Again, you don't need to know the rules to author the document.
> 
> If you're a *user* of the XML schema, a document author, you don't
> need to know anything at all about how the Java classes relate to the
> XML schema. If you're the provider of the XML schema, you also don't
> need to know much about the rules, since the schema will be generated
> for you.
> 
> The only people who really need to know the rules in great detail are
> the folks implementing Web Beans and implementing the schema
> generation tool :-)

I would like to make sure I understand this whole schema generation
process because, as I mentioned, I was not aware of this aspect.
However, putting that aside, I would find it odd that a web beans 
developer would not need to understand or know anything about the component 
class that they are configuring, since they are typically going to be 
invoking the component, etc. in their application code.

> That's the real beauty of this mechanism!
> 
> > Is it a better way going forward? Probably, but if web 
> beans is being advertised
> > as a layer of services over existing Java EE technologies 
> then one would assume
> > that it will be specified in a way that is natural and 
> easily understood by the users
> > of those technologies. That "naturalness" is worth more 
> than what is gained by a
> > slightly improved XML style that is limited to one specific area.
> 
> I don't believe that the additional typesafety and tool-ability
> (authoring support) amounts to only a slight improvement, though of
> course this view is influenced by the fact that I, like most Java
> developers, always use an IDE for everything. Developers who don't use
> an IDE won't see the same level of improvement.
> 
> In fact, for developers who don't use tools, there is no great
> advantage to the web beans style of XML. This stuff was designed for
> IDE users.

We have to make sure that an IDE is not assumed. That strategic error 
has been made before... 
 
> > Of course, consistency can be achieved from either 
> direction, and the alternative to
> > web beans adopting the style of those technologies is for 
> the technologies to adopt
> > the web beans style of XML. As I mentioned, for that 
> direction to change there must
> > be a platform-level directive.
> 
> I will ask Roberto and Bill about this, but in the past I have not
> heard from them that there was a platform-level requirement for
> consistency here. Certainly they've both read the spec and have not
> yet raised this as an issue with me. So, again, I would like to focus
> on the question of ease-of-use and reuse.

I believe this is a big issue, and is the crux of our concern. "Ease 
of use" of one technology is not necessarily easy to use if it is
radically different from every other technology in the platform.
I would like to have this discussion with Bill and Roberto.