XOM API for Processing XML with Java

[Elliotte Harold <elharo AT metalab.unc.edu>]

The public API for nu.xom.Canonicalizer is getting increasingly unwieldy 
as I add more and more options. It's time for a serious rethink. I don't 
think this will affect the public API from 1.0 in any backwards 
incompatible way. However, I do want to think about what the much more 
configurable 1.1 API will look like.

To recap, the API in 1.0 looked like this:

public Canonicalizer {

  public Canonicalizer(OutputStream out)
  public Canonicalizer(OutputStream out, boolean withComments)

  public final void write(Document doc) throws IOException

}

This supports only one option: with comments or without comments.

1.1 will add a number of features and options:

1. Document subset (with XPath) or full document (without XPath) 
canonicalization.
2. Exclusive or non-exclusive canonicalization
3. With or without an inclusive namespaces prefix list

The current API in CVS looks like this:

public Canonicalizer {

  public static final String CANONICAL_XML
  public static final String CANONICAL_XML_WITH_COMMENTS
  public static final String EXCLUSIVE_XML_CANONICALIZATION
  public static final String EXCLUSIVE_XML_CANONICALIZATION_WITH_COMMENTS

  public Canonicalizer(OutputStream out)
  public Canonicalizer(OutputStream out, boolean withComments)
  public Canonicalizer(OutputStream out, boolean withComments, boolean 
exclusive)
  public Canonicalizer(OutputStream out, String algorithm)


  public final void write(Document doc) throws IOException
  public final void write(Document doc, String xpath, XPathContext 
context)
    throws IOException
  public final void write(Document doc,
                        String xpath,
                        XPathContext context,
                        String inclusiveNamespacePrefixes)
    throws IOException

}

You can see the JavaDoc here:

http://www.xom.nu/unstable/apidocs/nu/xom/canonical/Canonicalizer.html

Also worth reading for a comparison is the Apache XML Security 
canonicalizer API:

http://xml.apache.org/security/Java/api/org/apache/xml/security/c14n/Canonicalizer.html

Some questions:

1. Should exclusive canonicalization be an option in this class, or 
should it be a separate subclass? I'd prefer to keep it in this class to 
avoid some thorny issues of privacy, but moving it is not impossible.

2. Should the Document argument just be a Node? This is an API level 
change, but it's backwards compatible, except perhaps for subclasses. 
(That's unlikely, but now I'm wishing I'd made this class final in 1.0.)

Downside: it's not clear what it means to canonicalize a node that is 
not connected to any document; or if that's even a sensible thing to do.

3. Should all the XPath functionality be pulled out of this class 
completely? Instead a Nodes object returned by the usual query method 
could be passed in. i.e. change write(Document doc, String xpath, 
XPathContext context) to write(Nodes nodes).

This is much simpler from an API perspective. It would also make 
Wolfgang happy since he could use his own XPath engine (though enabling 
this is not in itself a goal. However neither is it a non-goal. If 
support for that falls out of other considerations, that's OK with me.)

The downside is at least two fold:

A. The Nodes passed in would have to be sorted into the right document 
order. This would duplicate work, because the XPath engine already sorts 
 Nodes objects into document order.

B. A Nodes object can contain nodes from two or more documents. This 
would cause an exception when canonicalizing. If it does cause such an 
exception, what would that exception be?

C. It's not clear what it means to canonicalize a node that is not 
connected to any document (again).

Upside: this eliminates one method and makes the method signatures a lot 
nicer.

4. Is it reasonable to pass in the list of inclusive namespace prefixes 
(prefixes that are treated as in regular canonical XML even when using 
the exclusive algorithm) as a whitespace separated String? Should it be 
some kind of list instead?


All comments appreciated.

I think I'm going to bundle up the current version and call it 1.1d5, 
because this is a nice milestone, and because guest access to CVS is 
broken right now (you can download the code if you register a username 
on java.net).  All the functionality for canonical XML and exclusive 
canonicalization is now present. However, the caveat is that the 
Canonicalizer API is *very* unstable and will change. I'm just not sure 
exactly how yet.

--
Elliotte Rusty Harold  elharo AT metalab.unc.edu
XML in a Nutshell 3rd Edition Just Published!
http://www.cafeconleche.org/books/xian3/
http://www.amazon.com/exec/obidos/ISBN=0596007647/cafeaulaitA/ref=nosim