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 */ public class NodeCreateRule extends Rule { // ---------------------------------------------------------- Inner Classes /** * The SAX content handler that does all the actual work of assembling the * DOM node tree from the SAX events. */ private class NodeBuilder extends DefaultHandler { // ------------------------------------------------------- Constructors /** * Constructor. * *Stores the content handler currently used by Digester so it can * be reset when done, and initializes the DOM objects needed to * build the node.
* * @param doc the document to use to create nodes * @param root the root node * @throws ParserConfigurationException if the DocumentBuilderFactory * could not be instantiated * @throws SAXException if the XMLReader could not be instantiated by * Digester (should not happen) */ public NodeBuilder(Document doc, Node root) throws ParserConfigurationException, SAXException { this.doc = doc; this.root = root; this.top = root; oldContentHandler = digester.getCustomContentHandler(); } // ------------------------------------------------- Instance Variables /** * The content handler used by Digester before it was set to this * content handler. */ protected ContentHandler oldContentHandler = null; /** * Depth of the current node, relative to the element where the content * handler was put into action. */ protected int depth = 0; /** * A DOM Document used to create the various Node instances. */ protected Document doc = null; /** * The DOM node that will be pushed on Digester's stack. */ protected Node root = null; /** * The current top DOM mode. */ protected Node top = null; /** * The text content of the current top DOM node. */ protected StringBuffer topText = new StringBuffer(); // --------------------------------------------- Helper Methods /** * Appends a {@link org.w3c.dom.Text Text} node to the current node * if the content reported by the parser is not purely whitespace. */ private void addTextIfPresent() throws SAXException { if (topText.length() > 0) { String str = topText.toString(); topText.setLength(0); if (str.trim().length() > 0) { // The contained text is not *pure* whitespace, so create // a text node to hold it. Note that the "untrimmed" text // is stored in the node. try { top.appendChild(doc.createTextNode(str)); } catch (DOMException e) { throw new SAXException(e.getMessage()); } } } } // --------------------------------------------- ContentHandler Methods /** * Handle notification about text embedded within the current node. ** An xml parser calls this when text is found. We need to ensure that this * text gets attached to the new Node we are creating - except in the case * where the only text in the node is whitespace. *
* There is a catch, however. According to the sax specification, a parser * does not need to pass all of the text content of a node in one go; it can * make multiple calls passing part of the data on each call. In particular, * when the body of an element includes xml entity-references, at least some * parsers make a separate call to this method to pass just the entity content. *
* In this method, we therefore just append the provided text to a
* "current text" buffer. When the element end is found, or a child element
* is found then we can check whether we have all-whitespace. See method
* addTextIfPresent.
*
* @param ch the characters from the XML document
* @param start the start position in the array
* @param length the number of characters to read from the array
* @throws SAXException if the DOM implementation throws an exception
*/
@Override
public void characters(char[] ch, int start, int length)
throws SAXException {
topText.append(ch, start, length);
}
/**
* Checks whether control needs to be returned to Digester.
*
* @param namespaceURI the namespace URI
* @param localName the local name
* @param qName the qualified (prefixed) name
* @throws SAXException if the DOM implementation throws an exception
*/
@Override
public void endElement(String namespaceURI, String localName,
String qName)
throws SAXException {
addTextIfPresent();
try {
if (depth == 0) {
getDigester().setCustomContentHandler(oldContentHandler);
getDigester().push(root);
getDigester().endElement(namespaceURI, localName, qName);
}
top = top.getParentNode();
depth--;
} catch (DOMException e) {
throw new SAXException(e.getMessage());
}
}
/**
* Adds a new
* {@link org.w3c.dom.ProcessingInstruction ProcessingInstruction} to
* the current node.
*
* @param target the processing instruction target
* @param data the processing instruction data, or null if none was
* supplied
* @throws SAXException if the DOM implementation throws an exception
*/
@Override
public void processingInstruction(String target, String data)
throws SAXException {
try {
top.appendChild(doc.createProcessingInstruction(target, data));
} catch (DOMException e) {
throw new SAXException(e.getMessage());
}
}
/**
* Adds a new child {@link org.w3c.dom.Element Element} to the current
* node.
*
* @param namespaceURI the namespace URI
* @param localName the local name
* @param qName the qualified (prefixed) name
* @param atts the list of attributes
* @throws SAXException if the DOM implementation throws an exception
*/
@Override
public void startElement(String namespaceURI, String localName,
String qName, Attributes atts)
throws SAXException {
addTextIfPresent();
try {
Node previousTop = top;
if ((localName == null) || (localName.length() == 0)) {
top = doc.createElement(qName);
} else {
top = doc.createElementNS(namespaceURI, localName);
}
for (int i = 0; i < atts.getLength(); i++) {
Attr attr = null;
if ((atts.getLocalName(i) == null) ||
(atts.getLocalName(i).length() == 0)) {
attr = doc.createAttribute(atts.getQName(i));
attr.setNodeValue(atts.getValue(i));
((Element)top).setAttributeNode(attr);
} else {
attr = doc.createAttributeNS(atts.getURI(i),
atts.getLocalName(i));
attr.setNodeValue(atts.getValue(i));
((Element)top).setAttributeNodeNS(attr);
}
}
previousTop.appendChild(top);
depth++;
} catch (DOMException e) {
throw new SAXException(e.getMessage());
}
}
}
// ----------------------------------------------------------- Constructors
/**
* Default constructor. Creates an instance of this rule that will create a
* DOM {@link org.w3c.dom.Element Element}.
*/
public NodeCreateRule() throws ParserConfigurationException {
this(Node.ELEMENT_NODE);
}
/**
* 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
*/
public NodeCreateRule(DocumentBuilder documentBuilder) {
this(Node.ELEMENT_NODE, 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.
*
* @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
*/
public NodeCreateRule(int nodeType) throws ParserConfigurationException {
this(nodeType,
DocumentBuilderFactory.newInstance().newDocumentBuilder());
}
/**
* 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
*/
public NodeCreateRule(int nodeType, DocumentBuilder documentBuilder) {
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;
}
// ----------------------------------------------------- Instance Variables
/**
* The JAXP DocumentBuilder to use.
*/
private DocumentBuilder documentBuilder = null;
/**
* 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.
*/
private int nodeType = Node.ELEMENT_NODE;
// ----------------------------------------------------------- Rule Methods
/**
* 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).
*
* @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
*/
@Override
public void begin(String namespaceURI, String name, Attributes attributes)
throws Exception {
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.getQName(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());
}
// the NodeBuilder constructor has already saved the original
// value of the digester's custom content handler (expected to
// be null, but we save it just in case). So now we just
// need to tell the digester to forward events to the builder.
getDigester().setCustomContentHandler(builder);
}
/**
* Pop the Node off the top of the stack.
*/
@Override
public void end() throws Exception {
digester.pop();
}
}