nu.xom.converters

## Class DOMConverter

- Object
- - nu.xom.converters.DOMConverter

-     public class DOMConverter
      extends Object

  Converts XOM `Document` objects to and from DOM `Document` objects. This class can also convert many DOM node objects into the corresponding XOM node objects. However, the reverse is not possible because DOM objects cannot live outside their containing `Document`.

  Version:
    1.2d1
  Author:
    Elliotte Rusty Harold

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Attribute` | `convert(org.w3c.dom.Attr attribute)` Translates a DOM `org.w3c.dom.Attr` object into an equivalent `nu.xom.Attribute` object.
    `static Comment` | `convert(org.w3c.dom.Comment comment)` Translates a DOM `org.w3c.dom.Comment` object into an equivalent `nu.xom.Comment` object.
    `static Document` | `convert(org.w3c.dom.Document domDocument)` Translates a DOM `org.w3c.dom.Document` object into an equivalent `nu.xom.Document` object.
    `static org.w3c.dom.Document` | `convert(Document document, org.w3c.dom.DOMImplementation impl)` Translates a XOM `nu.xom.Document` object into an equivalent `org.w3c.dom.Document` object.
    `static Nodes` | `convert(org.w3c.dom.DocumentFragment fragment)` Translates a DOM `org.w3c.dom.DocumentFragment` object into an equivalent `nu.xom.Nodes` object.
    `static Nodes` | `convert(org.w3c.dom.DocumentFragment fragment, NodeFactory factory)` Translates a DOM `org.w3c.dom.DocumentFragment` object into an equivalent `nu.xom.Nodes` object, converting each DOM node as specified by a factory.
    `static Document` | `convert(org.w3c.dom.Document domDocument, NodeFactory factory)` Translates a DOM `org.w3c.dom.Document` object into an equivalent `nu.xom.Document` object as controlled by a factory.
    `static DocType` | `convert(org.w3c.dom.DocumentType doctype)` Translates a DOM `org.w3c.dom.DocumentType` object into an equivalent `nu.xom.DocType` object.
    `static Element` | `convert(org.w3c.dom.Element element)` Translates a DOM `org.w3c.dom.Element` object into an equivalent `nu.xom.Element` object.
    `static ProcessingInstruction` | `convert(org.w3c.dom.ProcessingInstruction pi)` Translates a DOM `org.w3c.dom.ProcessingInstruction` object into an equivalent `nu.xom.ProcessingInstruction` object.
    `static Text` | `convert(org.w3c.dom.Text text)` Translates a DOM `org.w3c.dom.Text` object into an equivalent `nu.xom.Text`.

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### convert

          public static Document convert(org.w3c.dom.Document domDocument)

      Translates a DOM `org.w3c.dom.Document` object into an equivalent `nu.xom.Document` object. The original DOM document is not changed. Some DOM `Document` objects cannot be serialized as namespace well-formed XML, and thus cannot be converted to XOM.

      Parameters:
        `domDocument` - the DOM document to translate
      Returns:
        a XOM document
      Throws:
        `XMLException` - if the DOM document is not a well-formed XML document

    - #### convert

          public static Document convert(org.w3c.dom.Document domDocument,
                                         NodeFactory factory)

      Translates a DOM `org.w3c.dom.Document` object into an equivalent `nu.xom.Document` object as controlled by a factory. The original DOM document is not changed. Some DOM `Document` objects cannot be serialized as namespace well-formed XML, and thus cannot be converted to XOM.

      Parameters:
        `domDocument` - the DOM document to translate
        `factory` - the factory that converts each DOM node into zero or more XOM nodes
      Returns:
        a XOM document
      Throws:
        `XMLException` - if the DOM document is not a well-formed XML document

    - #### convert

          public static Nodes convert(org.w3c.dom.DocumentFragment fragment)

      Translates a DOM `org.w3c.dom.DocumentFragment` object into an equivalent `nu.xom.Nodes` object. The original DOM document fragment is not changed. Some DOM `DocumentFragment` objects cannot be serialized as namespace well-balanced XML, and thus cannot be converted to XOM.

      Parameters:
        `fragment` - the DOM document fragment to translate
      Returns:
        a `Nodes` containing the converted fragment members
      Throws:
        `XMLException` - if the DOM object is not a well-balanced XML fragment

    - #### convert

          public static Nodes convert(org.w3c.dom.DocumentFragment fragment,
                                      NodeFactory factory)

      Translates a DOM `org.w3c.dom.DocumentFragment` object into an equivalent `nu.xom.Nodes` object, converting each DOM node as specified by a factory. The original DOM document fragment is not changed. Some DOM `DocumentFragment` objects cannot be serialized as namespace well-balanced XML, and thus cannot be converted to XOM.

      Parameters:
        `fragment` - the DOM document fragment to translate
        `factory` - the NodeFactory that converts each DOM node into a XOM node
      Returns:
        a `Nodes` containing the converted fragment members
      Throws:
        `XMLException` - if the DOM object is not a well-balanced XML fragment

    - #### convert

          public static Comment convert(org.w3c.dom.Comment comment)

      Translates a DOM `org.w3c.dom.Comment` object into an equivalent `nu.xom.Comment` object. The original DOM object is not changed. Some DOM `Comment` objects cannot be serialized as well-formed XML, and thus cannot be converted to XOM.

      Parameters:
        `comment` - the DOM comment to translate
      Returns:
        a XOM comment
      Throws:
        `XMLException` - if the DOM comment is not a well-formed XML comment

    - #### convert

          public static Text convert(org.w3c.dom.Text text)

      Translates a DOM `org.w3c.dom.Text` object into an equivalent `nu.xom.Text`. This method will also convert `org.w3c.dom.CDATA` objects. The original DOM object is not changed. Some DOM `Text` objects cannot be serialized as well-formed XML, and thus cannot be converted to XOM.

      Parameters:
        `text` - the DOM text to translate
      Returns:
        a XOM text
      Throws:
        `XMLException` - if the DOM text is not a well-formed XML text

    - #### convert

          public static Attribute convert(org.w3c.dom.Attr attribute)

      Translates a DOM `org.w3c.dom.Attr` object into an equivalent `nu.xom.Attribute` object. The original DOM object is not changed. Some DOM `Attr` objects cannot be serialized as well-formed XML, and thus cannot be converted to XOM. Furthermore, DOM uses `Attr` objects to represent namespace declarations. XOM does not. Converting an `Attr` object that represents an `xmlns` or `xmlns:prefix` attribute will cause an exception.

      Parameters:
        `attribute` - the DOM `Attr` to translate
      Returns:
        the equivalent XOM `Attribute`
      Throws:
        `XMLException` - if the DOM `Attr` is a namespace declaration or is not a well-formed XML attribute

    - #### convert

          public static ProcessingInstruction convert(org.w3c.dom.ProcessingInstruction pi)

      Translates a DOM `org.w3c.dom.ProcessingInstruction` object into an equivalent `nu.xom.ProcessingInstruction` object. The original DOM object is not changed. Some DOM `ProcessingInstruction` objects cannot be serialized as well-formed XML, and thus cannot be converted to XOM.

      Parameters:
        `pi` - the DOM `ProcessingInstruction` to convert
      Returns:
        a XOM `ProcessingInstruction`
      Throws:
        `XMLException` - if the DOM `ProcessingInstruction` is not a well-formed XML processing instruction

    - #### convert

          public static DocType convert(org.w3c.dom.DocumentType doctype)

      Translates a DOM `org.w3c.dom.DocumentType` object into an equivalent `nu.xom.DocType` object. The original DOM object is not changed. Some DOM `DocumentType` objects cannot be serialized as well-formed XML, and thus cannot be converted to XOM.

      Parameters:
        `doctype` - the DOM `DocumentType` to convert
      Returns:
        the equivalent XOM `DocType`
      Throws:
        `XMLException` - if the DOM `DocumentType` is not a well-formed XML document type declaration

    - #### convert

          public static Element convert(org.w3c.dom.Element element)

      Translates a DOM `org.w3c.dom.Element` object into an equivalent `nu.xom.Element` object. The original DOM object is not changed. Some DOM `Element` objects cannot be serialized as namespace well-formed XML, and thus cannot be converted to XOM.

      Parameters:
        `element` - the DOM `Element` to convert
      Returns:
        the equivalent XOM `Element`
      Throws:
        `XMLException` - if the DOM `Element` is not a well-formed XML element

    - #### convert

          public static org.w3c.dom.Document convert(Document document,
                                                     org.w3c.dom.DOMImplementation impl)

      Translates a XOM `nu.xom.Document` object into an equivalent `org.w3c.dom.Document` object. The original XOM document is not changed. Since DOM2 internal subsets are read-only, the internal DTD subset is not converted. All other aspects of the document should be translated without a problem.

      Parameters:
        `document` - the XOM document to translate
        `impl` - the specific DOM implementation into which this document will be converted
      Returns:
        a DOM document

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