org.apache.commons.digester

Class NodeCreateRule

public class NodeCreateRule extends Rule

A rule implementation that creates a DOM 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 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 org.w3c.dom.Document Document, it must be imported first, using the Document method org.w3c.dom.Document#importNode(org.w3c.dom.Node, boolean) importNode().

Important Note: This is implemented by replacing the SAX 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

Nested Class Summary
classNodeCreateRule.NodeBuilder
The SAX content handler that does all the actual work of assembling the DOM node tree from the SAX events.
Field Summary
DocumentBuilderdocumentBuilder
The JAXP DocumentBuilder to use.
intnodeType
The type of the node that should be created.
Constructor Summary
NodeCreateRule()
Default constructor.
NodeCreateRule(DocumentBuilder documentBuilder)
Constructor.
NodeCreateRule(int nodeType)
Constructor.
NodeCreateRule(int nodeType, DocumentBuilder documentBuilder)
Constructor.
Method Summary
voidbegin(String namespaceURI, String name, 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.
voidend()
Pop the Node off the top of the stack.

Field Detail

documentBuilder

private 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 org.w3c.dom.Node Node, but currently only org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE and org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE are allowed values.

Constructor Detail

NodeCreateRule

public NodeCreateRule()
Default constructor. Creates an instance of this rule that will create a DOM org.w3c.dom.Element Element.

NodeCreateRule

public NodeCreateRule(DocumentBuilder documentBuilder)
Constructor. Creates an instance of this rule that will create a DOM org.w3c.dom.Element 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)
Constructor. Creates an instance of this rule that will create either a DOM org.w3c.dom.Element Element or a DOM org.w3c.dom.DocumentFragment DocumentFragment, depending on the value of the nodeType parameter.

Parameters: nodeType the type of node to create, which can be either org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE or org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE

Throws: IllegalArgumentException if the node type is not supported

NodeCreateRule

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

Parameters: nodeType the type of node to create, which can be either org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE or org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE 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)
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).

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()
Pop the Node off the top of the stack.
Copyright 2001-2005 The Apache Software Foundation.