Class 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 trigged 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
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private class  NodeCreateRule.NodeBuilder
      The SAX content handler that does all the actual work of assembling the DOM node tree from the SAX events.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private javax.xml.parsers.DocumentBuilder documentBuilder
      The JAXP DocumentBuilder to use.
      private int nodeType
      The type of the node that should be created.
    • Constructor Summary

      Constructors 
      Constructor Description
      NodeCreateRule()
      Default constructor.
      NodeCreateRule​(int nodeType)
      Constructor.
      NodeCreateRule​(int nodeType, javax.xml.parsers.DocumentBuilder documentBuilder)
      Constructor.
      NodeCreateRule​(javax.xml.parsers.DocumentBuilder documentBuilder)
      Constructor.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void begin​(java.lang.String namespaceURI, java.lang.String name, org.xml.sax.Attributes attributes)
      When this method fires, the digester is told to forward all SAX ContentHandler events to the builder object, resulting in a DOM being built instead of normal digester rule-handling occurring.
      void end()
      Pop the Node off the top of the stack.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • documentBuilder

        private javax.xml.parsers.DocumentBuilder documentBuilder
        The JAXP DocumentBuilder to use.
      • nodeType

        private int nodeType
        The type of the node that should be created. Must be one of the constants defined in Node, but currently only Node.ELEMENT_NODE and Node.DOCUMENT_FRAGMENT_NODE are allowed values.
    • Constructor Detail

      • NodeCreateRule

        public NodeCreateRule()
                       throws javax.xml.parsers.ParserConfigurationException
        Default constructor. Creates an instance of this rule that will create a DOM Element.
        Throws:
        javax.xml.parsers.ParserConfigurationException
      • NodeCreateRule

        public NodeCreateRule​(javax.xml.parsers.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 javax.xml.parsers.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:
        java.lang.IllegalArgumentException - if the node type is not supported
        javax.xml.parsers.ParserConfigurationException
      • NodeCreateRule

        public NodeCreateRule​(int nodeType,
                              javax.xml.parsers.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:
        java.lang.IllegalArgumentException - if the node type is not supported
    • Method Detail

      • begin

        public void begin​(java.lang.String namespaceURI,
                          java.lang.String name,
                          org.xml.sax.Attributes attributes)
                   throws java.lang.Exception
        When this method fires, the digester is told to forward all SAX ContentHandler events to the builder object, resulting in a DOM being built instead of normal digester rule-handling occurring. When the end of the current xml element is encountered, the original content handler is restored (expected to be NULL, allowing normal Digester operations to continue).
        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:
        java.lang.Exception - indicates a JAXP configuration problem
      • end

        public void end()
                 throws java.lang.Exception
        Pop the Node off the top of the stack.
        Overrides:
        end in class Rule
        Throws:
        java.lang.Exception