[jdom-interest] Philosophical XML (was API Inertia)

[Paul Philion]

In my mind, XML is very simple: It is a tree of elements; elements that
contain other elements and elements that contain text. Each element has a
namespace and a set of attributes. A document contains a root element and
other XML stuff (which isn't important in this discussion). XML is
structured data with a few conventions. Everything else is helper code,
because it is independent of the data in the element tree.

I think JDOM can be, and should be, this simple.

If I were to do a little analysis on the above, I would derive actors like
Document and Element (with a specialization called TextElement). I would not
have an Attribute class, as I don't think Attributes exist independently of
Elements. I would distinguish between Element and MutableElement, as I think
there are enough examples of "read-only" XML documents and enough memory and
processing saving to justify it: My own experience says that about 75% of
the XML documents I deal with are only read, not modified.

I think JDOM should represent as simple a document tree as possible (using
interfaces in key places, like "Element"), and provide a number of utility
and strategy classes to operate on that standard tree.

I have some detailed ideas about these classes and interfaces, but I have
not included them here because I want to encourage discussion about what
features should be available in a simple, intuitive API.

- Paul Philion

----- Original Message -----
From: "Brett McLaughlin" <brett at newInstance.com>
To: <jdom-interest at jdom.org>
Sent: Sunday, April 29, 2001 10:54 PM
Subject: [jdom-interest] API Inertia


> All-
>
>   I want to make a sort of "State of the Union" in regards to what I'm
> seeing in JDOM and the discussions going on right now. I want to couch
this
> in reminding people that I was one of the original JDOM authors, so any
> problems I identify in JDOM today are at least partially my fault ;-)
>   I also want to preface this with saying that it's absolutely true that
> Jason has more or less taken over coding JDOM the last 6 months or so.
I've
> been swamped with work, and he's done the lion's share with help from
folks
> like Elliotte, Alex, Philip, et. al. However, I'm seeing some alarming
> things.
>   What I see right now is a lot of API inertia. The idea that if things
work
> well for the user class you are in, or that you forecast, things are OK.
The
> first assumption here that is bad is that you are pre-supposing that you
can
> project what a large group of people want. "Most users would find this..."
> "This is too complex..." "Nobody would..." I really don't think that these
> statements have much place here; we have a community. If we, the
community,
> all want or don't want something, that's really it. The idea that there is
a
> group of users outside this community that we can project wants and needs
> for is, IMO, false. It's certainly true that early on we had to do that,
> because the community was so small. But now, we've got a decent sampling.
>   The second assumption is that even in the case of good solutions based
on
> the current status, we need to maintain the current status. As a
corrollary,
> I'd say that it seems with the JSR starting, there is a sort of "we're
> getting to the last of the needed changes, and they are probably minor." I
> think this is completely wrong. I think it should be "This is our last
> chance to make this API what it should be, so big or small, let's change
now
> while we can." I'm not suggesting that we change for the sake of change;
I'm
> saying that we make the API as right as we can now. Suffer the short-term
> problems for the long term win. Once it goes 1.0, we have to live with it.
> And right now, we're not ready to go 1.0, for more than just small issues,
> IMO.
>   So, things like the common interface/base class thing. After over two
> years of being a Java and XML guy, I think we NEED a commonality in JDOM.
> This idea that it isn't any better is not valid; I'm not saying it's
better
> or worse than the current API. I'm saying if I could go back and do JDOM
> again, there's no way in the world I'd do it without this. It makes too
many
> things a pain. Traversing a tree, which is a 50 line example in DOM (weird
> structures and all) becomes a tremendous pain in JDOM; I know, because I'm
> writing the chapters on it. Additionally, with SOAP and things like that,
I
> really am annoyed in having to get an "Object" back over the wire. I can't
> count on it being something that I can feed to, say, XMLOutputter. How
nice
> would it be to pass a Node, or Item, or whatever, to the print() method of
> XMLOutputter? Pretty darn sweet. Gets rid of all that serialized form
crap,
> for one thing.
>   Things like detach(). This would have never made it into the original
API,
> because we looked at it and said "Oh, here's how you remove content:
> removeContent()." Now I know we didn't see that problem, but I just don't
> see how detach() would have made it in anyway; esp. when 2 of the 3
original
> brains (James Davidson and I) both look at that and go "That's backwards."
> It really feels like a band-aid, not a real fix.
>   So I simply want to encourage everyone, myself included, to stop
assuming
> that we are so close that big changes (like namespace handling and
> entities?!?) are bad. I also think that because Jason has done so much
work
> on the API, it has lost some of the XML balance that I think was once
there;
> that's not because Jason doesn't know XML (hardly... he clues me in from
> time to time!), but because he's a completely Java guy. Elliotte, for
> example though, is much more in the XML side... and that balance helps.
For
> things like Item/Node/whatever. For things like namespaces. I don't want
to
> lose the XML-sense that we have, any more than I would want to go the DOM
> way and lose, IMO, the Java-sense of things. Hope that makes sense, and I
> haven't offended or hacked off anyone... but I thought a breath of fresh
air
> might clear the air and kickstart some lurkers who have good ideas.
>
> -Brett
>
> ----
> Brett McLaughlin
>
> Enhydra Strategist
>   * http://www.enhydra.org
>   * http://www.lutris.com
> O'Reilly Author - Java and XML
>   * http://www.oreilly.com/catalog/javaxml
>   * http://www1.fatbrain.com/asp/bookinfo/bookinfo.asp?theisbn=0596000162
>
>
> _______________________________________________
> To control your jdom-interest membership:
>
http://lists.denveronline.net/mailman/options/jdom-interest/youraddr@yourhos
t.com
>