FileDocCategorySizeDatePackage
NodeCreateRule.javaAPI DocApache Tomcat 6.0.1415571Fri Jul 20 04:20:30 BST 2007org.apache.tomcat.util.digester

NodeCreateRule

public class NodeCreateRule extends Rule
A rule implementation that creates a DOM {@link org.w3c.dom.Node 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 {@link org.w3c.dom.Element 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 {@link org.w3c.dom.DocumentFragment 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 {@link org.w3c.dom.Document Document}, it must be imported first, using the Document method {@link org.w3c.dom.Document#importNode(org.w3c.dom.Node, boolean) importNode()}.

Important Note: This is implemented by replacing the SAX {@link org.xml.sax.ContentHandler 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

Fields Summary
private DocumentBuilder
documentBuilder
The JAXP DocumentBuilder to use.
private int
nodeType
The type of the node that should be created. Must be one of the constants defined in {@link org.w3c.dom.Node Node}, but currently only {@link org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE} and {@link org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE} are allowed values.
Constructors Summary
public NodeCreateRule()
Default constructor. Creates an instance of this rule that will create a DOM {@link org.w3c.dom.Element Element}.


        this(Node.ELEMENT_NODE);
public NodeCreateRule(DocumentBuilder documentBuilder)
Constructor. Creates an instance of this rule that will create a DOM {@link org.w3c.dom.Element Element}, but lets you specify the JAXP DocumentBuilder that should be used when constructing the node tree.

param
documentBuilder the JAXP DocumentBuilder to use


        this(Node.ELEMENT_NODE, documentBuilder);
public NodeCreateRule(int nodeType)
Constructor. Creates an instance of this rule that will create either a DOM {@link org.w3c.dom.Element Element} or a DOM {@link org.w3c.dom.DocumentFragment DocumentFragment}, depending on the value of the nodeType parameter.

param
nodeType the type of node to create, which can be either {@link org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE} or {@link org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE}
throws
IllegalArgumentException if the node type is not supported


        this(nodeType,
             DocumentBuilderFactory.newInstance().newDocumentBuilder());
public NodeCreateRule(int nodeType, DocumentBuilder documentBuilder)
Constructor. Creates an instance of this rule that will create either a DOM {@link org.w3c.dom.Element Element} or a DOM {@link org.w3c.dom.DocumentFragment 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.

param
nodeType the type of node to create, which can be either {@link org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE} or {@link org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE}
param
documentBuilder the JAXP DocumentBuilder to use
throws
IllegalArgumentException if the node type is not supported


        if (!((nodeType == Node.DOCUMENT_FRAGMENT_NODE) ||
              (nodeType == Node.ELEMENT_NODE))) {
            throw new IllegalArgumentException(
                "Can only create nodes of type DocumentFragment and Element");
        }
        this.nodeType = nodeType;
        this.documentBuilder = documentBuilder;
Methods Summary
public voidbegin(java.lang.String namespaceURI, java.lang.String name, org.xml.sax.Attributes attributes)
Implemented to replace the content handler currently in use by a NodeBuilder.

param
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
param
name the local name if the parser is namespace aware, or just the element name otherwise
param
attributes The attribute list of this element
throws
Exception indicates a JAXP configuration problem



    // ----------------------------------------------------------- Rule Methods


                                                                                         
           
          

        XMLReader xmlReader = getDigester().getXMLReader();
        Document doc = documentBuilder.newDocument();
        NodeBuilder builder = null;
        if (nodeType == Node.ELEMENT_NODE) {
            Element element = null;
            if (getDigester().getNamespaceAware()) {
                element =
                    doc.createElementNS(namespaceURI, name);
                for (int i = 0; i < attributes.getLength(); i++) {
                    element.setAttributeNS(attributes.getURI(i),
                                           attributes.getLocalName(i),
                                           attributes.getValue(i));
                }
            } else {
                element = doc.createElement(name);
                for (int i = 0; i < attributes.getLength(); i++) {
                    element.setAttribute(attributes.getQName(i),
                                         attributes.getValue(i));
                }
            }
            builder = new NodeBuilder(doc, element);
        } else {
            builder = new NodeBuilder(doc, doc.createDocumentFragment());
        }
        xmlReader.setContentHandler(builder);
public voidend()
Pop the Node off the top of the stack.


        Object top = digester.pop();