Skip to Content.
Sympa Menu

xom-interest - [XOM-interest] Improved? Canonicalizer API

xom-interest AT lists.ibiblio.org

Subject: XOM API for Processing XML with Java

List archive

Chronological Thread  
  • From: Elliotte Harold <elharo AT metalab.unc.edu>
  • To: xom-interest <xom-interest AT lists.ibiblio.org>
  • Subject: [XOM-interest] Improved? Canonicalizer API
  • Date: Tue, 15 Feb 2005 10:16:14 -0500

I've now checked in what I think is an improved Canonicalizer API. It's quite a bit simpler, and offers somewhat more flexibility. The downside is that it may be doing extra work the previous implementation didn't do. In particular, there's now a second complete walk of the tree every time a subset is canonicalized.

The new API 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, String algorithm)

public final void write(Node node) throws IOException
public final void write(Nodes documentSubset) throws IOException
public final void write(Nodes documentSubset, String inclusiveNamespacePrefixes)
throws IOException

}

The write(Node) method takes the place of the old write(Document) method, and canonicalizes an entire subtree. The other two methods canonicalize a document subset constructed by XPath or other means.

In addition, there's now a specific CanonicalizationException class that is thrown for problems like unrecognized algorithms, document subsets that contain nodes from multiple documents, and the like.

This is noticeably simpler than the old API, and it lets Wolfgang plug in his alternate XPath implementation.

It's arguably more less obvious than the old API. In particular, there's no place to just plug-in a document and an XPath expression. However, most non-trivial use cases required a namespace context as well. Throw in the inclusiveNamespacePrefixes string and the argument list was just getting too long for comfort. Passing in a Nodes argument reduced three arguments to one, and I like that. It also enables clients to use something other than XPath to create the subset they want to canonicalize, and that may support some interesting use cases.

If document subset canonicalization using XPath becomes a FAQ, then I can consider adding back the old API as convenience methods. However, I think I'll first try to make this clear enough in the API documentation that this won't be an issue.

Comments appreciated.

--
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




  • [XOM-interest] Improved? Canonicalizer API, Elliotte Harold, 02/15/2005

Archive powered by MHonArc 2.6.24.

Top of Page