Skip to Content.
Sympa Menu

xom-interest - [XOM-interest] 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] Canonicalizer API
  • Date: Sun, 06 Feb 2005 09:55:13 -0500

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





Archive powered by MHonArc 2.6.24.

Top of Page