XOM API for Processing XML with Java

[jcowan AT reutershealth.com]

Elliotte Rusty Harold scripsit:

> This is the *LAST CALL* development release of XOM 1.0.   

When you announce a last call, you usually should mention the deadline
for reviews, so people know how long they have.

Node:

1) I'm now going to argue that hasChildren should be removed in favor of
   using getChildCount() == 0.  In a proper JIT they should be exactly
   the same at run time, and it's really trivial to write one's own
   method hasChildren(Node n) if you must have it.

Nodes:

1) I think it's worth having a put method to complement get.  The only
   way to replace a single Node in the list currently is either to copy
   it, which does not preserve object identity, or else to remove and
   then insert/append, which involves copying the list anywhere up to
   twice internally (if you want to replace the zeroth node), and requires
   getting the insert vs. append choice correct.

Attribute:

1) The four-argument constructor has the wrong summary.

2) Consider flushing the no-namespace constructors: they save only 3 
characters
   (plus optional whitespace) over the corresponding namespace constructors.
   Trying to let people use a namespaceless subset of XOM really doesn't save
   much mental space, I don't think; DOM has these things because Level 1
   predates namespaces.

Attribute.Type

1) I think the distinction between UNDECLARED and CDATA is unmotivated, since
SAX parsers are required to return undeclared attributes as of type CDATA 
anyhow.
The only way AFAICT to get UNDECLARED attributes in is to add them yourself.
I suggest using CDATA only and then switching the three-argument constructor
of Attribute to imply it.

ParentNode:

1) Add putChild() and putAttribute(); see Nodes for rationale

Element:

1) Remove no-namespace constructor: see Attribute for rationale.

2) Unify all namespace checking on a single routine, checkNamespace(String
   prefix, String URI), to be called in place of checkNamespacePrefix,
   checkNamespaceURI, and checkAddNamespaceDeclaration.  In the first two
   cases, the existing URI or prefix is passed.  This allows applications
   to enforce rules about prefix mapping.  It also increases conceptual
   compatibility with Attribute, which already has checkNamespace.

3) Remove no-namespace versions of getAttribute, getAttributeValue,
   getChildElements, getFirstChildElement; see Attribute for rationale.

4) Document interaction of getAttribute(int) and removeAttribute.

Elements:

No comments.

Comment:

1) Comment copy constructor doco: for "a Comment object" read "a copy".

DocType:

1) Rename systemID and publicID to systemIdentifier and publicIdentifier,
   for conformity to the XML Rec, which does not use "ID" in these names.
   Yes, it's verbose.

Builder:

1) 3-argument constructor doco doesn't mention NodeFactory.  Also, the 
constructors
   should have consistent doco:  all should read "Creates a new".

2) Consider dropping Builder(XMLReader parser, boolean validate); it's 
clutter,
   and it's very easy to ask the XMLReader for validation before passing it.

3) There should be a flavor of build() that accepts a org.xml.sax.InputSource.

4) Expose the chosen parser with a getXMLReader method, so that you can let
   XOM choose the parser but still set properties on it before calling 
build().

NodeFactory:

1) Point out that NF doesn't do anything unless subclassed.  For each call, 
make
   sure the default result is explained.

2) Initial text refers to non-existent makeDocTypeDeclaration().

3) It's asymmetrical that makeDocType can't return an Element, whereas
   finishMakingElement (of the root element) can return a DocType.
   Make it one way or the other.

4) In finishMakingElement, it's better to ignore attempts to detach
   the root rather than to simply warn against doing so.
   That way, the root need not be treated specially (good for recursive
   doctypes).

5) Consider handing makeDocType the internal subset so it can look inside,
   but except on attempts to change it.

6) makeDocument needs better doco; I don't understand what it does.

Serializer:

1) Consider renaming writeEscaped to just write, as it basically does
   the same thing (but more efficiently) as write(new Text(string)).
   This is conceptually compatible with Element.insertChild(string, int).

Canonicalizer:

1) Constructor doco claims to create a Serializer.

DOMConverter:

1) Consider renaming 2-argument convert, as it is conceptually separate from
   the others.

SAXConverter:

No comments.

XIncluder:

No comments.

XSLTransform:

No comments.

> release will be 1.0 alpha 1, 

I think "alpha" has the wrong semantics here.  This is much more than alpha
code; I think it should be 1.0rc1.

-- 
It was impossible to inveigle           John Cowan <jcowan AT reutershealth.com>
Georg Wilhelm Friedrich Hegel           http://www.ccil.org/~cowan
Into offering the slightest apology     http://www.reutershealth.com
For his Phenomenology.                      --W. H. Auden, from "People" 
(1953)