NodeCreateRule (Apache Tomcat 7.0.108 API Documentation)

org.apache.tomcat.util.digester

## Class NodeCreateRule

- java.lang.Object
- - org.apache.tomcat.util.digester.Rule
  - - org.apache.tomcat.util.digester.NodeCreateRule

-     public class NodeCreateRule
      extends Rule

  A rule implementation that creates a DOM `Node` containing the XML at the element that matched the rule. Two concrete types of nodes can be created by this rule:
  - the default is to create an `Element` node. The created element will correspond to the element that matched the rule, containing all XML content underneath that element.
  - alternatively, this rule can create nodes of type `DocumentFragment`, which will contain only the XML content under the element the rule was triggered on.
  The created node will be normalized, meaning it will not contain text nodes that only contain white space characters.

  The created `Node` will be pushed on Digester's object stack when done. To use it in the context of another DOM `Document`, it must be imported first, using the Document method `importNode()`.

  Important Note: This is implemented by replacing the SAX `ContentHandler` in the parser used by Digester, and resetting it when the matched element is closed. As a side effect, rules that would match XML nodes under the element that matches a `NodeCreateRule` will never be triggered by Digester, which usually is the behavior one would expect.

  Note that the current implementation does not set the namespace prefixes in the exported nodes. The (usually more important) namespace URIs are set, of course.

  Since:
    Digester 1.4

- - ### Field Summary

    - ### Fields inherited from class org.apache.tomcat.util.digester.Rule

      `digester, namespaceURI`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NodeCreateRule()` Default constructor.
    `NodeCreateRule(DocumentBuilder documentBuilder)` Constructor.
    `NodeCreateRule(int nodeType)` Constructor.
    `NodeCreateRule(int nodeType, DocumentBuilder documentBuilder)` Constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `begin(String namespaceURI, String name, Attributes attributes)` Implemented to replace the content handler currently in use by a NodeBuilder.
    `void` | `end(String namespace, String name)` Pop the Node off the top of the stack.

    - ### Methods inherited from class org.apache.tomcat.util.digester.Rule

      `begin, body, body, end, finish, getDigester, getNamespaceURI, setDigester, setNamespaceURI`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### NodeCreateRule

          public NodeCreateRule()
                         throws ParserConfigurationException

      Default constructor. Creates an instance of this rule that will create a DOM `Element`.
      Throws:
        `ParserConfigurationException`

    - #### NodeCreateRule

          public NodeCreateRule(DocumentBuilder documentBuilder)

      Constructor. Creates an instance of this rule that will create a DOM `Element`, but lets you specify the JAXP `DocumentBuilder` that should be used when constructing the node tree.
      Parameters:
        `documentBuilder` - the JAXP `DocumentBuilder` to use

    - #### NodeCreateRule

          public NodeCreateRule(int nodeType)
                         throws ParserConfigurationException

      Constructor. Creates an instance of this rule that will create either a DOM `Element` or a DOM `DocumentFragment`, depending on the value of the `nodeType` parameter.
      Parameters:
        `nodeType` - the type of node to create, which can be either `Node.ELEMENT_NODE` or `Node.DOCUMENT_FRAGMENT_NODE`
      Throws:
        `IllegalArgumentException` - if the node type is not supported
        `ParserConfigurationException`

    - #### NodeCreateRule

          public NodeCreateRule(int nodeType,
                        DocumentBuilder documentBuilder)

      Constructor. Creates an instance of this rule that will create either a DOM `Element` or a DOM `DocumentFragment`, depending on the value of the `nodeType` parameter. This constructor lets you specify the JAXP `DocumentBuilder` that should be used when constructing the node tree.
      Parameters:
        `nodeType` - the type of node to create, which can be either `Node.ELEMENT_NODE` or `Node.DOCUMENT_FRAGMENT_NODE`
        `documentBuilder` - the JAXP `DocumentBuilder` to use
      Throws:
        `IllegalArgumentException` - if the node type is not supported

  - ### Method Detail

    - #### begin

          public void begin(String namespaceURI,
                   String name,
                   Attributes attributes)
                     throws Exception

      Implemented to replace the content handler currently in use by a NodeBuilder.
      Overrides:
        `begin` in class `Rule`
      Parameters:
        `namespaceURI` - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        `name` - the local name if the parser is namespace aware, or just the element name otherwise
        `attributes` - The attribute list of this element
      Throws:
        `Exception` - indicates a JAXP configuration problem

    - #### end

          public void end(String namespace,
                 String name)
                   throws Exception

      Pop the Node off the top of the stack.
      Overrides:
        `end` in class `Rule`
      Parameters:
        `namespace` - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        `name` - the local name if the parser is namespace aware, or just the element name otherwise
      Throws:
        `Exception`

Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.