[webbeans-dev] Re: XML configuration format

[Gavin King]

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

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.


>> 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.

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.

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 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.


>> 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.

> 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 :-)

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.

> 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.


-- 
Gavin King
gavin.king at gmail.com
http://in.relation.to/Bloggers/Gavin
http://hibernate.org
http://seamframework.org