nu.xom

## Class NodeFactory

- Object
- - nu.xom.NodeFactory

-     public class NodeFactory
      extends Object

  Builders use a `NodeFactory` object to construct each `Node` object (`Element`, `Text`, `Attribute`, etc.) they add to the tree. The default implementation simply calls the relevant constructor, stuffs the resulting `Node` object in a length one `Nodes` object, and returns it.

  Subclassing this class allows builders to produce instance of subclasses (for example, `HTMLElement`) instead of the base classes.

  Subclasses can also filter content while building. For example, namespaces could be added to or changed on all elements. Comments could be deleted. Processing instructions can be changed into elements. An `xinclude:include` element could be replaced with the content it references. All such changes must be consistent with the usual rules of well-formedness. For example, the `makeDocType()` method should not return a list containing two `DocType` objects because an XML document can have at most one document type declaration. Nor should it return a list containing an element, because an element cannot appear in a document prolog. However, it could return a list containing any number of comments and processing instructions, and not more than one `DocType` object.

  Version:
    1.3.1
  Author:
    Elliotte Rusty Harold

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `NodeFactory()` Constructs a new node factory.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `finishMakingDocument(Document document)` Signals the end of a document.
    `Nodes` | `finishMakingElement(Element element)` Signals the end of an element.
    `Nodes` | `makeAttribute(String name, String URI, String value, Attribute.Type type)` Returns a new `Nodes` object containing an attribute in the specified namespace with the specified name and type.
    `Nodes` | `makeComment(String data)` Returns a new `Nodes` object containing a comment with the specified text.
    `Nodes` | `makeDocType(String rootElementName, String publicID, String systemID)` Returns a new `Nodes` object containing a `DocType` object with the specified root element name, system ID, and public ID.
    `Nodes` | `makeProcessingInstruction(String target, String data)` Returns a new `Nodes` object containing a new `ProcessingInstruction` object with the specified target and data.
    `Element` | `makeRootElement(String name, String namespace)` Creates a new element in the specified namespace with the specified name.
    `Nodes` | `makeText(String data)` Returns a new `Nodes` object containing a text node with the specified content.
    `Document` | `startMakingDocument()` Creates a new `Document` object.
    `Element` | `startMakingElement(String name, String namespace)` Creates a new `Element` in the specified namespace with the specified name.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### NodeFactory

          public NodeFactory()

      Constructs a new node factory.

  - ### Method Detail

    - #### makeRootElement

          public Element makeRootElement(String name,
                                         String namespace)

      Creates a new element in the specified namespace with the specified name. The builder calls this method to make the root element of the document.

      Subclasses may change the name, namespace, content, or other characteristics of the element returned. The default implementation merely calls `startMakingElement`. However, when subclassing, it is often useful to be able to easily distinguish between the root element and a non-root element because the root element cannot be detached. Therefore, subclasses must not return null from this method. Doing so will cause a `NullPointerException`.

      Parameters:
        `name` - the qualified name of the element
        `namespace` - the namespace URI of the element
      Returns:
        the new root element

    - #### startMakingElement

          public Element startMakingElement(String name,
                                            String namespace)

      Creates a new `Element` in the specified namespace with the specified name.

      Subclasses may change the name, namespace, content, or other characteristics of the `Element` returned. Subclasses may return null to indicate the `Element` should not be created. However, doing so will only remove the element's start-tag and end-tag from the result tree. Any content inside the element will be attached to the element's parent by default, unless it too is filtered. To remove an entire element, return an empty `Nodes` object from the `finishMakingElement()` method.

      Parameters:
        `name` - the qualified name of the element
        `namespace` - the namespace URI of the element
      Returns:
        the new element

    - #### finishMakingElement

          public Nodes finishMakingElement(Element element)

      Signals the end of an element. This method should return the `Nodes` to be added to the tree. They need not contain the `Element` that was passed to this method, though most often they will. By default the `Nodes` returned contain only the built element. However, subclasses may return a list containing any number of nodes, all of which will be added to the tree at the current position in the order given by the list (subject to the usual well-formedness constraints, of course. For instance, the list should not contain a `DocType` object unless the element is the root element, and the document does not already have a `DocType`). All of the nodes returned must be parentless. If this method returns an empty list, then the element (including all its contents) is not included in the finished document.

      To process an element at a time, override this method in a subclass so that it functions as a callback. When you're done processing the `Element`, return an empty list so that it will be removed from the tree and garbage collected. Be careful not to return an empty list for the root element though. That is, when the element passed to this method is the root element, the list returned must contain exactly one `Element` object. The simplest way to check this is testing if `element.getParent() instanceof Document`.

      Do not detach `element` or any of its ancestors while inside this method. Doing so can royally muck up the build.

      Parameters:
        `element` - the finished `Element`
      Returns:
        the nodes to be added to the tree

    - #### startMakingDocument

          public Document startMakingDocument()

      Creates a new `Document` object. The root element of this document is initially set to `<root xmlns="https://xom.nu/fakeRoot"/>`. This is only temporary. As soon as the real root element's start-tag is read, this element is replaced by the real root. This fake root should never be exposed.

      The builder calls this method at the beginning of each document, before it calls any other method in this class. Thus this is a useful place to perform per-document initialization tasks.

      Subclasses may change the root element, content, or other characteristics of the document returned. However, this method must not return null or the builder will throw a `ParsingException`.

      Returns:
        the newly created `Document`

    - #### finishMakingDocument

          public void finishMakingDocument(Document document)

      Signals the end of a document. The default implementation of this method does nothing. The builder does not call this method if an exception is thrown while building a document.

      Parameters:
        `document` - the completed `Document`

    - #### makeAttribute

          public Nodes makeAttribute(String name,
                                     String URI,
                                     String value,
                                     Attribute.Type type)

      Returns a new `Nodes` object containing an attribute in the specified namespace with the specified name and type.

      Subclasses may change the nodes returned from this method. They may return a `Nodes` object containing any number of children and attributes which are appended and added to the current parent element. This `Nodes` object may not contain any `Document` objects. All of the nodes returned must be parentless. Subclasses may return an empty `Nodes` to indicate the attribute should not be created.

      Parameters:
        `name` - the prefixed name of the attribute
        `URI` - the namespace URI
        `value` - the attribute value
        `type` - the attribute type
      Returns:
        the nodes to be added to the tree

    - #### makeComment

          public Nodes makeComment(String data)

      Returns a new `Nodes` object containing a comment with the specified text.

      Subclasses may change the content or other characteristics of the comment returned. Subclasses may change the nodes returned from this method. They may return a `Nodes` object containing any number of children and attributes which are appended and added to the current parent element. This `Nodes` object should not contain any `Document` objects. All of the nodes returned must be parentless. Subclasses may return an empty `Nodes` to indicate the comment should not be included in the finished document.

      Parameters:
        `data` - the complete text content of the comment
      Returns:
        the nodes to be added to the tree

    - #### makeDocType

          public Nodes makeDocType(String rootElementName,
                                   String publicID,
                                   String systemID)

      Returns a new `Nodes` object containing a `DocType` object with the specified root element name, system ID, and public ID.

      Subclasses may change the root element name, public ID, system ID, or other characteristics of the `DocType` returned. Subclasses may change the nodes returned from this method. They may return a `Nodes` object containing any number of comments and processing instructions which are appended to the current parent node. This `Nodes` object may not contain any `Document`, `Element`, `Attribute`, or `Text` objects. All of the nodes returned must be parentless. Subclasses may return an empty `Nodes` to indicate the `DocType` should not be included in the finished document.

      Parameters:
        `rootElementName` - the declared, qualified name for the root element
        `publicID` - the public ID of the external DTD subset
        `systemID` - the URL of the external DTD subset
      Returns:
        the nodes to be added to the document

    - #### makeText

          public Nodes makeText(String data)

      Returns a new `Nodes` object containing a text node with the specified content.

      Subclasses may change the content or other characteristics of the text returned. Subclasses may also change the nodes returned from this method. They may return a `Nodes` object containing any number of nodes which are added or appended to the current parent node. This `Nodes` object must not contain any `Document` nodes. All of the nodes returned must be parentless. Subclasses may return an empty `Nodes` to indicate the text should not be included in the finished document.

      Parameters:
        `data` - the complete text content of the node
      Returns:
        the nodes to be added to the tree

    - #### makeProcessingInstruction

          public Nodes makeProcessingInstruction(String target,
                                                 String data)

      Returns a new `Nodes` object containing a new `ProcessingInstruction` object with the specified target and data.

      Subclasses may change the target, data, or other characteristics of the `ProcessingInstruction` returned. Subclasses may change the nodes returned from this method. They may return a `Nodes` object containing any number of nodes which are added or appended to the current parent node. This `Nodes` object must not contain any `Document` nodes. If the processing instruction appears in the prolog or epilog of the document, then it must also not contain any `Element`, `Attribute`, or `Text` objects. All of the nodes returned must be parentless. Subclasses may return an empty `Nodes` to indicate the processing instruction should not be included in the finished document.

      Parameters:
        `target` - the target of the processing instruction
        `data` - the data of the processing instruction
      Returns:
        the nodes to be added to the tree

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