nu.xom.canonical

## Class Canonicalizer

- Object
- - nu.xom.canonical.Canonicalizer

-     public class Canonicalizer
      extends Object

  Writes XML in the format specified by Canonical XML Version 1.0 or Exclusive XML Canonicalization Version 1.0. Canonical XML 1.1 support is in progress.

  Version:
    1.3.1
  Author:
    Elliotte Rusty Harold

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CANONICAL_XML`
    `static String` | `CANONICAL_XML_11`
    `static String` | `CANONICAL_XML_11_WITH_COMMENTS`
    `static String` | `CANONICAL_XML_WITH_COMMENTS`
    `static String` | `EXCLUSIVE_XML_CANONICALIZATION`
    `static String` | `EXCLUSIVE_XML_CANONICALIZATION_WITH_COMMENTS`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Canonicalizer(OutputStream out)` Creates a `Canonicalizer` that outputs a canonical XML document with comments.
    `Canonicalizer(OutputStream out, boolean withComments)` Creates a `Canonicalizer` that outputs a canonical XML document with or without comments.
    `Canonicalizer(OutputStream out, String algorithm)` Creates a `Canonicalizer` that outputs a canonical XML document using the specified algorithm.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `setInclusiveNamespacePrefixList(String inclusiveNamespacePrefixes)` Specifies the prefixes that will be output as specified in regular canonical XML, even when doing exclusive XML canonicalization.
    `void` | `write(Node node)` Serializes a node onto the output stream using the specified canonicalization algorithm.
    `void` | `write(Nodes documentSubset)` Serializes a document subset onto the output stream using the canonical XML algorithm.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### CANONICAL_XML

          public static final String CANONICAL_XML

      See Also:
        Constant Field Values

    - #### CANONICAL_XML_WITH_COMMENTS

          public static final String CANONICAL_XML_WITH_COMMENTS

      See Also:
        Constant Field Values

    - #### EXCLUSIVE_XML_CANONICALIZATION

          public static final String EXCLUSIVE_XML_CANONICALIZATION

      See Also:
        Constant Field Values

    - #### EXCLUSIVE_XML_CANONICALIZATION_WITH_COMMENTS

          public static final String EXCLUSIVE_XML_CANONICALIZATION_WITH_COMMENTS

      See Also:
        Constant Field Values

    - #### CANONICAL_XML_11

          public static final String CANONICAL_XML_11

      See Also:
        Constant Field Values

    - #### CANONICAL_XML_11_WITH_COMMENTS

          public static final String CANONICAL_XML_11_WITH_COMMENTS

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Canonicalizer

          public Canonicalizer(OutputStream out)

      Creates a `Canonicalizer` that outputs a canonical XML document with comments.

      Parameters:
        `out` - the output stream the document is written onto

    - #### Canonicalizer

          public Canonicalizer(OutputStream out,
                               boolean withComments)

      Creates a `Canonicalizer` that outputs a canonical XML document with or without comments.

      Parameters:
        `out` - the output stream the document is written onto
        `withComments` - true if comments should be included in the output, false otherwise

    - #### Canonicalizer

          public Canonicalizer(OutputStream out,
                               String algorithm)

      Creates a `Canonicalizer` that outputs a canonical XML document using the specified algorithm. Currently, four algorithms are defined and supported:

      - Canonical XML without comments: `http://www.w3.org/TR/2001/REC-xml-c14n-20010315`
      - Canonical XML with comments: `http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments`
      - Exclusive XML canonicalization without comments: `http://www.w3.org/2001/10/xml-exc-c14n#`
      - Exclusive XML canonicalization with comments: `http://www.w3.org/2001/10/xml-exc-c14n#WithComments`
      Parameters:
        `out` - the output stream the document is written onto
        `algorithm` - the URI for the canonicalization algorithm
      Throws:
        `CanonicalizationException` - if the algorithm is not recognized
        `NullPointerException` - if the algorithm is null

  - ### Method Detail

    - #### write

          public final void write(Node node)
                           throws IOException

      Serializes a node onto the output stream using the specified canonicalization algorithm. If the node is a document or an element, then the node's entire subtree is written out.

      Parameters:
        `node` - the node to canonicalize
      Throws:
        `IOException` - if the underlying `OutputStream` encounters an I/O error

    - #### write

          public final void write(Nodes documentSubset)
                           throws IOException

      Serializes a document subset onto the output stream using the canonical XML algorithm. All nodes in the list must come from same document. Furthermore, they must come from a document. They cannot be detached. The nodes need not be sorted. This method will sort them into the appropriate order for canonicalization.

      In most common use cases, these nodes will be the result of evaluating an XPath expression. For example,

           Canonicalizer canonicalizer
             = new Canonicalizer(System.out, Canonicalizer.CANONICAL_XML);
           Nodes result = doc.query("//. | //@* | //namespace::*");
           canonicalizer.write(result);

      Children are not output unless the subset also includes them. Including an element in the subset does not automatically select all the element's children, attributes, and namespaces. Furthermore, not selecting an element does not imply that its children, namespaces, attributes will not be output.

      Parameters:
        `documentSubset` - the nodes to serialize
      Throws:
        `IOException` - if the underlying `OutputStream` encounters an I/O error
        `CanonicalizationException` - if the nodes come from more than one document; or if a detached node is in the list

    - #### setInclusiveNamespacePrefixList

          public final void setInclusiveNamespacePrefixList(String inclusiveNamespacePrefixes)

      Specifies the prefixes that will be output as specified in regular canonical XML, even when doing exclusive XML canonicalization.

      Parameters:
        `inclusiveNamespacePrefixes` - a whitespace separated list of namespace prefixes that will always be included in the output, even in exclusive canonicalization

Copyright 2002-2020 Elliotte Rusty Harold
elharo@ibiblio.org