[jdom-interest] Re: Comments on JDOM b10-rc1

[Jason Hunter]

Elliotte Rusty Harold wrote:

> At 1:09 AM -0800 2/6/04, Jason Hunter wrote:
> 
>> Good news!
>>
>> After today's work I'm proud to report there are NO known API changes 
>> required before our 1.0 release.  What we have now is my best effort 
>> at a 1.0 release API.
>>
> 
> Any chance to get CVSWeb working so we can look at the source code easily?

The box we're using is oddly configured, and that makes this difficult.

> Is there some reason Content is not called Node or perhaps Child? To my 
> way of thinking "Content" refers to a list of all the content, not one 
> node. This is in keeping with the XML spec which says:

Well, Node would work (and Parent/Node is a better split than 
Parent/Content) but if Document is not a Node that breaks the notion of 
Node.

(I'm sitting in the "XQuery for Java" expert group meeting right now and 
ironically much of our discussion time is spent selecting names too.

> If the equals semantics is the same for all Content subclasses (Node 
> identity, ==) then it could be pushed up into Content. I think it is == 
> for all such cases, but I'm not sure. The JavaDocs for some classes like 
> Comment and Attribute don't say. If it isn't the same, then it needs to 
> be spelled out in the JavaDoc.

Done.

> Does the mapping code in processing instruction actually works on cases 
> like PHP processing instructions that can contain essentially anything? 
> Is it tested? I thought we had decided to ditch all the pseudo-attribute 
> parsing code.

You can still set the data to a random string.  One the pseudo-attribute 
code I don't recall how the conversation ended.  I know we renamed the 
methods to make more clear what they did.  I have a "nomap" version 
sitting on my hard drive.  I think my opinion was that if I had it to do 
over I wouldn't waste my afternoons writing it, but since it's written, 
might as well keep it and save someone else from wasting their afternoon.

> Are all the overloaded methods in JDOMFactory really necessary? Does the 
> Builder actually call all of these, or could some of them be cut?

You raise an interesting question.  Several of the factory methods 
aren't used internally, and it's true it'd be easier to write your own 
factory if there were fewer methods to implement.  To do that we'd prume 
the interface to a single "representational method" for each type.

There are downsides.  Since our "representational method" would have to 
be the longest method signature variety, builders or others using the 
factory will have to pass nulls, Attribute.UNDECLARED_TYPE, and other 
placeholders for the unused values.  Now, factories can be called by 
users as well as builders, so this makes user code have to be more 
complicated in some cases.  I think it's better to make the factory 
implementation code just slightly more complicated in order to avoid this.

> Finally, I strongly recommend using code coverage tools like Clover or 
> Jester or both to measure the test coverage before releasing. In my 
> experience this turns up a huge amount of untested code, unreachable 
> code, and outright bugs. It's also worth hitting the code base with 
> static analysis tools like PMD.

Volunteers most welcome.

Again, I want to get the API right for 1.0.0.  We can always fix 
implementation bugs in 1.0.1.

-jh-