You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@avalon.apache.org by Peter Donald <pe...@apache.org> on 2002/09/08 06:04:01 UTC
XML Conventions
Hiya,
I was wondering if anyone had any thoughts on the conventions we should use in
our xml files. Essentially when should we use attributes and when should we
use elements.
One school of thought saids we always use attributes if the value can only
appear once. The negative aspect of this is that you can get elements with
massive numbers of attributes like
<component
name="X"
impl="com.biz.X"
version="1.0.2"
displayName="The magnificent X"
description="X is a ...."
...
/>
This is fairly common in document centric descriptors.
Another school of though saids that you never use attributes. Like most of
descriptors that come out of Sun. It is easier to extend, but this ends up
with fairly verbose files like the following. The other problem is that if
you want to validate using DTDs you end up with stupid names like
<component-name> in an element <component> (see servlet/ejb descriptors for
an example).
<component>
<name>X</name>
<impl>com.biz.X</impl>
<version>1.0.2</version>
...
</component>
The other pattern I have noticed is that some people prefer to store "meta"
data about element as attributes while they store "content" data as elements.
So any preferences among these alternatives? My current thinking is that we
should probably go with the Sun-style (no attributes) just because it is more
common in java world. Thoughts?
--
Cheers,
Peter Donald
--------------------------------
These aren't the droids you're
looking for. Move along.
--------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Leo Simons <le...@apache.org>.
On Sun, 2002-09-08 at 11:28, Nicola Ken Barozzi wrote:
<snip/>
> The golden rule is that elements are for content and attributes for
> meta-content.
+1
<snippy-di-snip/>
> Now, given that xml property files are all about meta-content, I
> personally really like the all-attribute approach, using elements for
> multiplicity and containment, as in the above example.
+1
> I would also use the element contents to describe what the element is
> about; this makes it possible to have comments everywhere, and a user
> can read the descriptor as a document; it's also easy to make
> documentation out of it.
<snip example/>
> This is generally known as "literal programming".
+1.
>From the perspective of an XML file author (rather than that of a parser
builder), this is a really good idea. From the perspective of a parser
builder (my SAX knowledge is rusty though), this is also good; it is
easier than parsing <!-- --> or a multitude of extra attributes.
cheers,
Leo
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Leo Sutic wrote:
>
>>From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
>>
>>Leo Sutic wrote:
...
>>>Personally I prefer elements for multiplicity and for long text:
>>>
>>><description>
>>> This is my component. There are many like it,
>>> but this one is mine.
>>>
>>> "This is the second paragraph."
>>></description>
>>>
>>>is better than:
>>>
>>> <description text="This is my component. There are many
>>
>>like it, but
>>
>>>this one is mine. "This is the second paragraph.""/>
>>
>>Which is what I said.
>>Hey, doesn't this break DefaultConfigurationBuilder.?
>
>
> No. The DefaultConfigurationBuilder can handle elements as leaves in
> the config tree:
>
> <root>
> Illegal text. This text makes the <root/> element have mixed content.
> That is not allowed.
> <child>Legal text</child>
> </root>
Ah, ok, now I understand what you mean.
The fact that it has to be mixed or in containing elements is not a big
deal, the main content of the proposal is that element content ca be the
documentation... *shrugs* no big deal anyway.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: XML Conventions
Posted by Leo Sutic <le...@inspireinfrastructure.com>.
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
>
> Leo Sutic wrote:
> >
> >>From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
> >>
> >>Peter Donald wrote:
> >
> >
> > ...
> >
> >
> >>This is generally known as "literal programming".
> >
> >
> > And pretty much breaks the DefaultConfigurationBuilder.
> >
> > -1
>
> Too bad it is set in stone :'-(
>
> > Use comments for comments. If it isn't supposed to be given to the
> > program code for processing, keep it away from it.
>
> Which is exactly the point.
> Someone just said that documentation is as important as code, so it
> should be regarded as code. @see literal programming
I am aware of literate programming - it does not mean that documentation
*is* code, unless you give such an abstract meaning to "documentation"
and
"code" as to render both words useless. For example, you can not compile
documentation into Java bytecode. If you could, it would be code.
> > And THAT said...
> >
> > Personally I prefer elements for multiplicity and for long text:
> >
> > <description>
> > This is my component. There are many like it,
> > but this one is mine.
> >
> > "This is the second paragraph."
> > </description>
> >
> > is better than:
> >
> > <description text="This is my component. There are many
> like it, but
> > this one is mine. "This is the second paragraph.""/>
>
> Which is what I said.
> Hey, doesn't this break DefaultConfigurationBuilder.?
No. The DefaultConfigurationBuilder can handle elements as leaves in
the config tree:
<root>
Illegal text. This text makes the <root/> element have mixed content.
That is not allowed.
<child>Legal text</child>
</root>
/LS
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Leo Sutic wrote:
>
>>From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
>>
>>Peter Donald wrote:
>
>
> ...
>
>
>>This is generally known as "literal programming".
>
>
> And pretty much breaks the DefaultConfigurationBuilder.
>
> -1
Too bad it is set in stone :'-(
> Use comments for comments. If it isn't supposed to be given
> to the program code for processing, keep it away from it.
Which is exactly the point.
Someone just said that documentation is as important as code, so it
should be regarded as code. @see literal programming
...
> And THAT said...
>
> Personally I prefer elements for multiplicity and for long text:
>
> <description>
> This is my component. There are many like it,
> but this one is mine.
>
> "This is the second paragraph."
> </description>
>
> is better than:
>
> <description text="This is my component. There are many like it, but
> this one is mine. "This is the second paragraph.""/>
Which is what I said.
Hey, doesn't this break DefaultConfigurationBuilder.?
Go figure *shrugs*
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: XML Conventions
Posted by Gonzalo Diethelm <go...@aditiva.com>.
> > Another possibility would be to let the user choose. Suppose that
> > config.getPropertyValueAsString("name") -- a bit of a long name
> > -- returned "Something" for both of the following
> >
> > <component name="Something" />
> >
> > and
> >
> > <component>
> > <name>Something</name>
> > </component>
>
> This is how the XmlProperty task in Ant <shameless>that I
> wrote</shameless> deals with properties, when collapseAttributes="true".
>
> http://jakarta.apache.org/ant/manual/CoreTasks/xmlproperty.html
>
> The main reason is that it makes it easy to invent an informal DTD and
> access it easily.
Just FYI, this is the way Resin handles its configuration file,
which is quite convenient.
--
Gonzalo A. Diethelm
gonzalo.diethelm@aditiva.com
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Nicola Ken Barozzi <ni...@apache.org>.
David W. wrote:
> Another possibilty would be to let the user choose. Suppose that
> config.getPropertyValueAsString("name") -- a bit of a long name -- returned
> "Something" for both of the following
>
> <component name="Something" />
>
> and
>
> <component>
> <name>Something</name>
> </component>
>
> And threw a ConfigurationException in the case
>
> <component name="Something">
> <name>Something else</name>
> </component>
>
> It would mean a noticable change to the way DefaultConfiguration works, but
> I don't think people tend to design configuration files that would cause
> problems with the third case. It would still be good to have a standard
> format that comes with releases, but certainly the user could change things
> around if it was desirable.
This is how the XmlProperty task in Ant <shameless>that I
wrote</shameless> deals with properties, when collapseAttributes="true".
http://jakarta.apache.org/ant/manual/CoreTasks/xmlproperty.html
The main reason is that it makes it easy to invent an informal DTD and
access it easily.
But making it a "feature" for existing DTDs is probable FS, but could be
nice in the Default way configs /can/ be handled.
The only real reason why this could be needed is when you need to pass from
<element attr="a"/>
to
<element>
<attr>a</attr>
<attr>b</attr>
<attr>c</attr>
</element>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by "David W." <da...@optonline.net>.
Another possibilty would be to let the user choose. Suppose that
config.getPropertyValueAsString("name") -- a bit of a long name -- returned
"Something" for both of the following
<component name="Something" />
and
<component>
<name>Something</name>
</component>
And threw a ConfigurationException in the case
<component name="Something">
<name>Something else</name>
</component>
It would mean a noticable change to the way DefaultConfiguration works, but
I don't think people tend to design configuration files that would cause
problems with the third case. It would still be good to have a standard
format that comes with releases, but certainly the user could change things
around if it was desirable.
David Weitzman
Peter Donal wrote:
> On Mon, 9 Sep 2002 00:24, Leo Sutic wrote:
> > In short: Peter - just do what feels right. This is like the whitespace
> > style of your code (brace on same or following line?), and we can expend
> > a metric shitload of time arguing back and forth with very little of
> > actual value coming out of it.
>
> ahh - okay ;)
>
> I am using Davids suggestion and it seems to work reasonably well. In
database
> terms it boils down to;
> * normalize data
> * keys (or candidate keys) become attributes
> * repeating groups become elements
> * remaining data items become either elements (if long), attributes (if
> "salient") or I flip a coin if no other rule holds ;)
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Peter Donald <pe...@apache.org>.
On Mon, 9 Sep 2002 01:47, Leo Sutic wrote:
> > From: Peter Donald [mailto:peter@apache.org]
> >
> > On Mon, 9 Sep 2002 00:24, Leo Sutic wrote:
> > > In short: Peter - just do what feels right. This is like the
> > > whitespace style of your code (brace on same or following
> >
> > line?), and
> >
> > > we can expend a metric shitload of time arguing back and forth with
> > > very little of actual value coming out of it.
> >
> > ahh - okay ;)
> >
> > I am using Davids suggestion and it seems to work reasonably
> > well. In database
> > terms it boils down to;
> > * normalize data
> > * keys (or candidate keys) become attributes
> > * repeating groups become elements
> > * remaining data items become either elements (if long),
> > attributes (if
> > "salient") or I flip a coin if no other rule holds ;)
>
> Sounds OK. If possible - could you make it so that the resulting
> structure can be made into a Configuration? I.e. no mixed content.
No problem. At the moment I only end up with content in "long" data items.
However I have not come across any of those while I was normalizing the
config files.
--
Cheers,
Peter Donald
---------------------------------------------------
"Therefore it can be said that victorious warriors
win first, and then go to battle, while defeated
warriors go to battle first, and then seek to win."
- Sun Tzu, the Art Of War
---------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: XML Conventions
Posted by Leo Sutic <le...@inspireinfrastructure.com>.
> From: Peter Donald [mailto:peter@apache.org]
>
> On Mon, 9 Sep 2002 00:24, Leo Sutic wrote:
> > In short: Peter - just do what feels right. This is like the
> > whitespace style of your code (brace on same or following
> line?), and
> > we can expend a metric shitload of time arguing back and forth with
> > very little of actual value coming out of it.
>
> ahh - okay ;)
>
> I am using Davids suggestion and it seems to work reasonably
> well. In database
> terms it boils down to;
> * normalize data
> * keys (or candidate keys) become attributes
> * repeating groups become elements
> * remaining data items become either elements (if long),
> attributes (if
> "salient") or I flip a coin if no other rule holds ;)
Sounds OK. If possible - could you make it so that the resulting
structure can be made into a Configuration? I.e. no mixed content.
/LS
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Peter Donald <pe...@apache.org>.
On Mon, 9 Sep 2002 00:24, Leo Sutic wrote:
> In short: Peter - just do what feels right. This is like the whitespace
> style of your code (brace on same or following line?), and we can expend
> a metric shitload of time arguing back and forth with very little of
> actual value coming out of it.
ahh - okay ;)
I am using Davids suggestion and it seems to work reasonably well. In database
terms it boils down to;
* normalize data
* keys (or candidate keys) become attributes
* repeating groups become elements
* remaining data items become either elements (if long), attributes (if
"salient") or I flip a coin if no other rule holds ;)
--
Cheers,
Peter Donald
--------------------------------
These aren't the droids you're
looking for. Move along.
--------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: XML Conventions
Posted by Leo Sutic <le...@inspireinfrastructure.com>.
> From: Nicola Ken Barozzi [mailto:nicolaken@apache.org]
>
> Peter Donald wrote:
...
> This is generally known as "literal programming".
And pretty much breaks the DefaultConfigurationBuilder.
-1
Use comments for comments. If it isn't supposed to be given
to the program code for processing, keep it away from it.
That said...
Elements:
+ Rule 1: Use common sense. Taken from the C++ FAQ lite (better
stated):
http://www.parashift.com/c++-faq-lite/big-picture.html#faq-6.14
Another thing: don't assume things labeled as "evil" (macros,
arrays, pointers, etc.) are always bad in all situations. One
size does not fit all. Take out a fine-point marker and write
on the inside of your glasses, Software Development Is Decision
Making. In other words, there are very few if any "never..."
and "always..." rules in software - rules that you can apply
without thinking - rules that always work in all situations in
all markets - one-size-fits-all rules.
In plain English, you will have to make decisions, and the
quality of your decisions will effect the business value of your
software. And sometimes you will have to choose between a bunch
of bad options. When that happens, the best you can hope for is
to choose the least bad of the alternatives, the lesser of the
"evils."
http://www.parashift.com/c++-faq-lite/newbie.html#faq-28.6
Some people are so afraid of making a wrong decision that they'll
adopt a one-size-fits-all rule such as "give a name to every
number."
But if you adopt rules like that, you're guaranteed to have made
the wrong decision: those rules cost your company more than they
save. They are bad rules.
The choice is simple: use a flexible rule even though you might make
a wrong decision, or use a one-size-fits-all rule and be guaranteed
to make a wrong decision.
In short: Peter - just do what feels right. This is like the whitespace
style of your code (brace on same or following line?), and we can expend
a metric shitload of time arguing back and forth with very little of
actual value coming out of it.
Just do something and we'll see how well it holds up. That's what we'd
end
up having to do anyway (as we can only hypothesize about what should be
the
one true rule.) Chances are, it won't matter.
And THAT said...
Personally I prefer elements for multiplicity and for long text:
<description>
This is my component. There are many like it,
but this one is mine.
"This is the second paragraph."
</description>
is better than:
<description text="This is my component. There are many like it, but
this one is mine. "This is the second paragraph.""/>
Those with non-word-wrapping mail clients will appreciate why.
/LS
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Peter Donald wrote:
> On Sun, 8 Sep 2002 14:49, David W. wrote:
>
>>I tend to think of attributes as something you can identify the node with.
>>Properties like displayName, description, and version can and will change
>>over time, but if name and impl are the same, you probably haven't broken
>>anything. When you look through the entire XML file and you think, "That's
>>the record for ____", you should make whatever value you use to identify
>>the record (it's key basically) an attribute. Okay, now I think I've
>>figured out what I'm trying to say.
>>
>>The mental database approach: make something an attribute if you might want
>>to seach for it or use it as an identifier (after all, 'component' doesn't
>>tell you anything).
>
>
> I like. So say we were going to declare a dependency of one component on
> another component. You would write it something like
>
> <dependency key="some-service" type="o.a.a.SomeService" optional="true">
> <attributes>
> <attribute name="secure" value="true"/>
> </attributes>
> </dependency>
>
> Which saids that a dependency of type SomeService, looked up using key
> "some-service" is optional. It also has extra metadata associated with it
> indicating that it must be the "secure" version of this service.
The golden rule is that elements are for content and attributes for
meta-content.
This is quite easy to understand in XHTML, where the text you see is in
element content, while the attributes specify extra info.
Now, given that xml property files are all about meta-content, I
personally really like the all-attribute approach, using elements for
multiplicity and containment, as in the above example.
I would also use the element contents to describe what the element is
about; this makes it possible to have comments everywhere, and a user
can read the descriptor as a document; it's also easy to make
documentation out of it.
<dependency key="some-service"
type="o.a.a.SomeService"
optional="true">
This Component has a dependency to o.a.a.SomeService because it
need to... and this is optional because...
<attributes>
Maybe in the future it's possibel that it will
also have... but noy there is only 1 attribute.
<attribute name="secure" value="true">
It has to be secure, because...
</attribute>
</attributes>
</dependency>
This is generally known as "literal programming".
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Peter Donald <pe...@apache.org>.
On Sun, 8 Sep 2002 14:49, David W. wrote:
> I tend to think of attributes as something you can identify the node with.
> Properties like displayName, description, and version can and will change
> over time, but if name and impl are the same, you probably haven't broken
> anything. When you look through the entire XML file and you think, "That's
> the record for ____", you should make whatever value you use to identify
> the record (it's key basically) an attribute. Okay, now I think I've
> figured out what I'm trying to say.
>
> The mental database approach: make something an attribute if you might want
> to seach for it or use it as an identifier (after all, 'component' doesn't
> tell you anything).
I like. So say wwe were going to declare a dependency of one component on
another component. You would write it something like
<dependency key="some-service" type="o.a.a.SomeService" optional="true">
<attributes>
<attribute name="secure" value="true"/>
</attributes>
</dependency>
Which saids that a dependency of type SomeService, looked up using key
"some-service" is optional. It also has extra metadata associated with it
indicating that it must be the "secure" version of this service.
Any other changes you would make?
--
Cheers,
Peter Donald
"Man's mind stretched to a new idea never goes back to its original
dimensions." -Oliver Wendell Holmes
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by "David W." <da...@optonline.net>.
I like mixed, myself.
It isn't possible to use attributes for everything. They're really only
good for simple data types. Basically strings and numbers. For one to many
relationships (like declaring multiple dependancies) or complex composition
(like the configuration of an entire sub-component, or a recursive
definition) are only praticle with nested elements.
Attributes are good for simple, but important properties.
<component
name="X"
impl="com.biz.X"
>
<displayName>The magnificent X</displayName>
<description>X is a .....</description>
<version>1.0.2</version>
</component>
I tend to think of attributes as something you can identify the node with.
Properties like displayName, description, and version can and will change
over time, but if name and impl are the same, you probably haven't broken
anything. When you look through the entire XML file and you think, "That's
the record for ____", you should make whatever value you use to identify the
record (it's key basically) an attribute. Okay, now I think I've figured
out what I'm trying to say.
The mental database approach: make something an attribute if you might want
to seach for it or use it as an identifier (after all, 'component' doesn't
tell you anything).
David Weitzman
> On Sun, 8 Sep 2002 14:04, Peter Donald wrote:
> > Hiya,
> >
> > I was wondering if anyone had any thoughts on the conventions we should
use
> > in our xml files. Essentially when should we use attributes and when
should
> > we use elements.
> >
> > One school of thought saids we always use attributes if the value can
only
> > appear once. The negative aspect of this is that you can get elements
with
> > massive numbers of attributes like
> >
> > <component
> > name="X"
> > impl="com.biz.X"
> > version="1.0.2"
> > displayName="The magnificent X"
> > description="X is a ...."
> > ...
> > />
> >
> > This is fairly common in document centric descriptors.
> >
> > Another school of though saids that you never use attributes. Like most
of
> > descriptors that come out of Sun. It is easier to extend, but this ends
up
> > with fairly verbose files like the following. The other problem is that
if
> > you want to validate using DTDs you end up with stupid names like
> > <component-name> in an element <component> (see servlet/ejb descriptors
for
> > an example).
> >
> > <component>
> > <name>X</name>
> > <impl>com.biz.X</impl>
> > <version>1.0.2</version>
> > ...
> > </component>
> >
> > The other pattern I have noticed is that some people prefer to store
"meta"
> > data about element as attributes while they store "content" data as
> > elements.
> >
> > So any preferences among these alternatives? My current thinking is that
we
> > should probably go with the Sun-style (no attributes) just because it is
> > more common in java world. Thoughts?
>
> Or maybe we go with a mixed approach because that may be the most human
> readable?
>
> --
> Cheers,
>
> Peter Donald
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XML Conventions
Posted by Peter Donald <pe...@apache.org>.
On Sun, 8 Sep 2002 14:04, Peter Donald wrote:
> Hiya,
>
> I was wondering if anyone had any thoughts on the conventions we should use
> in our xml files. Essentially when should we use attributes and when should
> we use elements.
>
> One school of thought saids we always use attributes if the value can only
> appear once. The negative aspect of this is that you can get elements with
> massive numbers of attributes like
>
> <component
> name="X"
> impl="com.biz.X"
> version="1.0.2"
> displayName="The magnificent X"
> description="X is a ...."
> ...
> />
>
> This is fairly common in document centric descriptors.
>
> Another school of though saids that you never use attributes. Like most of
> descriptors that come out of Sun. It is easier to extend, but this ends up
> with fairly verbose files like the following. The other problem is that if
> you want to validate using DTDs you end up with stupid names like
> <component-name> in an element <component> (see servlet/ejb descriptors for
> an example).
>
> <component>
> <name>X</name>
> <impl>com.biz.X</impl>
> <version>1.0.2</version>
> ...
> </component>
>
> The other pattern I have noticed is that some people prefer to store "meta"
> data about element as attributes while they store "content" data as
> elements.
>
> So any preferences among these alternatives? My current thinking is that we
> should probably go with the Sun-style (no attributes) just because it is
> more common in java world. Thoughts?
Or maybe we go with a mixed approach because that may be the most human
readable?
--
Cheers,
Peter Donald
----------------------------------------
"Liberty means responsibility. That is
why most men dread it." - Locke
----------------------------------------
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>