001: /* $Id: NodeCreateRule.java 467222 2006-10-24 03:17:11Z markt $
002: *
003: * Licensed to the Apache Software Foundation (ASF) under one or more
004: * contributor license agreements. See the NOTICE file distributed with
005: * this work for additional information regarding copyright ownership.
006: * The ASF licenses this file to You under the Apache License, Version 2.0
007: * (the "License"); you may not use this file except in compliance with
008: * the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing, software
013: * distributed under the License is distributed on an "AS IS" BASIS,
014: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015: * See the License for the specific language governing permissions and
016: * limitations under the License.
017: */
018:
019: package org.apache.tomcat.util.digester;
020:
021: import javax.xml.parsers.DocumentBuilder;
022: import javax.xml.parsers.DocumentBuilderFactory;
023: import javax.xml.parsers.ParserConfigurationException;
024:
025: import org.w3c.dom.Attr;
026: import org.w3c.dom.DOMException;
027: import org.w3c.dom.Document;
028: import org.w3c.dom.Element;
029: import org.w3c.dom.Node;
030: import org.xml.sax.Attributes;
031: import org.xml.sax.ContentHandler;
032: import org.xml.sax.SAXException;
033: import org.xml.sax.XMLReader;
034: import org.xml.sax.helpers.DefaultHandler;
035:
036: /**
037: * A rule implementation that creates a DOM
038: * {@link org.w3c.dom.Node Node} containing the XML at the element that matched
039: * the rule. Two concrete types of nodes can be created by this rule:
040: * <ul>
041: * <li>the default is to create an {@link org.w3c.dom.Element Element} node.
042: * The created element will correspond to the element that matched the rule,
043: * containing all XML content underneath that element.</li>
044: * <li>alternatively, this rule can create nodes of type
045: * {@link org.w3c.dom.DocumentFragment DocumentFragment}, which will contain
046: * only the XML content under the element the rule was trigged on.</li>
047: * </ul>
048: * The created node will be normalized, meaning it will not contain text nodes
049: * that only contain white space characters.
050: *
051:
052: *
053: * <p>The created <code>Node</code> will be pushed on Digester's object stack
054: * when done. To use it in the context of another DOM
055: * {@link org.w3c.dom.Document Document}, it must be imported first, using the
056: * Document method
057: * {@link org.w3c.dom.Document#importNode(org.w3c.dom.Node, boolean) importNode()}.
058: * </p>
059: *
060: * <p><strong>Important Note:</strong> This is implemented by replacing the SAX
061: * {@link org.xml.sax.ContentHandler ContentHandler} in the parser used by
062: * Digester, and resetting it when the matched element is closed. As a side
063: * effect, rules that would match XML nodes under the element that matches
064: * a <code>NodeCreateRule</code> will never be triggered by Digester, which
065: * usually is the behavior one would expect.</p>
066: *
067: * <p><strong>Note</strong> that the current implementation does not set the namespace prefixes
068: * in the exported nodes. The (usually more important) namespace URIs are set,
069: * of course.</p>
070: *
071: * @since Digester 1.4
072: */
073:
074: public class NodeCreateRule extends Rule {
075:
076: // ---------------------------------------------------------- Inner Classes
077:
078: /**
079: * The SAX content handler that does all the actual work of assembling the
080: * DOM node tree from the SAX events.
081: */
082: private class NodeBuilder extends DefaultHandler {
083:
084: // ------------------------------------------------------- Constructors
085:
086: /**
087: * Constructor.
088: *
089: * <p>Stores the content handler currently used by Digester so it can
090: * be reset when done, and initializes the DOM objects needed to
091: * build the node.</p>
092: *
093: * @param doc the document to use to create nodes
094: * @param root the root node
095: * @throws ParserConfigurationException if the DocumentBuilderFactory
096: * could not be instantiated
097: * @throws SAXException if the XMLReader could not be instantiated by
098: * Digester (should not happen)
099: */
100: public NodeBuilder(Document doc, Node root)
101: throws ParserConfigurationException, SAXException {
102:
103: this .doc = doc;
104: this .root = root;
105: this .top = root;
106:
107: oldContentHandler = digester.getXMLReader()
108: .getContentHandler();
109:
110: }
111:
112: // ------------------------------------------------- Instance Variables
113:
114: /**
115: * The content handler used by Digester before it was set to this
116: * content handler.
117: */
118: protected ContentHandler oldContentHandler = null;
119:
120: /**
121: * Depth of the current node, relative to the element where the content
122: * handler was put into action.
123: */
124: protected int depth = 0;
125:
126: /**
127: * A DOM Document used to create the various Node instances.
128: */
129: protected Document doc = null;
130:
131: /**
132: * The DOM node that will be pushed on Digester's stack.
133: */
134: protected Node root = null;
135:
136: /**
137: * The current top DOM mode.
138: */
139: protected Node top = null;
140:
141: // --------------------------------------------- ContentHandler Methods
142:
143: /**
144: * Appends a {@link org.w3c.dom.Text Text} node to the current node.
145: *
146: * @param ch the characters from the XML document
147: * @param start the start position in the array
148: * @param length the number of characters to read from the array
149: * @throws SAXException if the DOM implementation throws an exception
150: */
151: public void characters(char[] ch, int start, int length)
152: throws SAXException {
153:
154: try {
155: String str = new String(ch, start, length);
156: if (str.trim().length() > 0) {
157: top.appendChild(doc.createTextNode(str));
158: }
159: } catch (DOMException e) {
160: throw new SAXException(e.getMessage());
161: }
162:
163: }
164:
165: /**
166: * Checks whether control needs to be returned to Digester.
167: *
168: * @param namespaceURI the namespace URI
169: * @param localName the local name
170: * @param qName the qualified (prefixed) name
171: * @throws SAXException if the DOM implementation throws an exception
172: */
173: public void endElement(String namespaceURI, String localName,
174: String qName) throws SAXException {
175:
176: try {
177: if (depth == 0) {
178: getDigester().getXMLReader().setContentHandler(
179: oldContentHandler);
180: getDigester().push(root);
181: getDigester().endElement(namespaceURI, localName,
182: qName);
183: }
184:
185: top = top.getParentNode();
186: depth--;
187: } catch (DOMException e) {
188: throw new SAXException(e.getMessage());
189: }
190:
191: }
192:
193: /**
194: * Adds a new
195: * {@link org.w3c.dom.ProcessingInstruction ProcessingInstruction} to
196: * the current node.
197: *
198: * @param target the processing instruction target
199: * @param data the processing instruction data, or null if none was
200: * supplied
201: * @throws SAXException if the DOM implementation throws an exception
202: */
203: public void processingInstruction(String target, String data)
204: throws SAXException {
205:
206: try {
207: top.appendChild(doc.createProcessingInstruction(target,
208: data));
209: } catch (DOMException e) {
210: throw new SAXException(e.getMessage());
211: }
212:
213: }
214:
215: /**
216: * Adds a new child {@link org.w3c.dom.Element Element} to the current
217: * node.
218: *
219: * @param namespaceURI the namespace URI
220: * @param localName the local name
221: * @param qName the qualified (prefixed) name
222: * @param atts the list of attributes
223: * @throws SAXException if the DOM implementation throws an exception
224: */
225: public void startElement(String namespaceURI, String localName,
226: String qName, Attributes atts) throws SAXException {
227:
228: try {
229: Node previousTop = top;
230: if ((localName == null) || (localName.length() == 0)) {
231: top = doc.createElement(qName);
232: } else {
233: top = doc.createElementNS(namespaceURI, localName);
234: }
235: for (int i = 0; i < atts.getLength(); i++) {
236: Attr attr = null;
237: if ((atts.getLocalName(i) == null)
238: || (atts.getLocalName(i).length() == 0)) {
239: attr = doc.createAttribute(atts.getQName(i));
240: attr.setNodeValue(atts.getValue(i));
241: ((Element) top).setAttributeNode(attr);
242: } else {
243: attr = doc.createAttributeNS(atts.getURI(i),
244: atts.getLocalName(i));
245: attr.setNodeValue(atts.getValue(i));
246: ((Element) top).setAttributeNodeNS(attr);
247: }
248: }
249: previousTop.appendChild(top);
250: depth++;
251: } catch (DOMException e) {
252: throw new SAXException(e.getMessage());
253: }
254:
255: }
256:
257: }
258:
259: // ----------------------------------------------------------- Constructors
260:
261: /**
262: * Default constructor. Creates an instance of this rule that will create a
263: * DOM {@link org.w3c.dom.Element Element}.
264: */
265: public NodeCreateRule() throws ParserConfigurationException {
266:
267: this (Node.ELEMENT_NODE);
268:
269: }
270:
271: /**
272: * Constructor. Creates an instance of this rule that will create a DOM
273: * {@link org.w3c.dom.Element Element}, but lets you specify the JAXP
274: * <code>DocumentBuilder</code> that should be used when constructing the
275: * node tree.
276: *
277: * @param documentBuilder the JAXP <code>DocumentBuilder</code> to use
278: */
279: public NodeCreateRule(DocumentBuilder documentBuilder) {
280:
281: this (Node.ELEMENT_NODE, documentBuilder);
282:
283: }
284:
285: /**
286: * Constructor. Creates an instance of this rule that will create either a
287: * DOM {@link org.w3c.dom.Element Element} or a DOM
288: * {@link org.w3c.dom.DocumentFragment DocumentFragment}, depending on the
289: * value of the <code>nodeType</code> parameter.
290: *
291: * @param nodeType the type of node to create, which can be either
292: * {@link org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE} or
293: * {@link org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE}
294: * @throws IllegalArgumentException if the node type is not supported
295: */
296: public NodeCreateRule(int nodeType)
297: throws ParserConfigurationException {
298:
299: this (nodeType, DocumentBuilderFactory.newInstance()
300: .newDocumentBuilder());
301:
302: }
303:
304: /**
305: * Constructor. Creates an instance of this rule that will create either a
306: * DOM {@link org.w3c.dom.Element Element} or a DOM
307: * {@link org.w3c.dom.DocumentFragment DocumentFragment}, depending on the
308: * value of the <code>nodeType</code> parameter. This constructor lets you
309: * specify the JAXP <code>DocumentBuilder</code> that should be used when
310: * constructing the node tree.
311: *
312: * @param nodeType the type of node to create, which can be either
313: * {@link org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE} or
314: * {@link org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE}
315: * @param documentBuilder the JAXP <code>DocumentBuilder</code> to use
316: * @throws IllegalArgumentException if the node type is not supported
317: */
318: public NodeCreateRule(int nodeType, DocumentBuilder documentBuilder) {
319:
320: if (!((nodeType == Node.DOCUMENT_FRAGMENT_NODE) || (nodeType == Node.ELEMENT_NODE))) {
321: throw new IllegalArgumentException(
322: "Can only create nodes of type DocumentFragment and Element");
323: }
324: this .nodeType = nodeType;
325: this .documentBuilder = documentBuilder;
326:
327: }
328:
329: // ----------------------------------------------------- Instance Variables
330:
331: /**
332: * The JAXP <code>DocumentBuilder</code> to use.
333: */
334: private DocumentBuilder documentBuilder = null;
335:
336: /**
337: * The type of the node that should be created. Must be one of the
338: * constants defined in {@link org.w3c.dom.Node Node}, but currently only
339: * {@link org.w3c.dom.Node#ELEMENT_NODE Node.ELEMENT_NODE} and
340: * {@link org.w3c.dom.Node#DOCUMENT_FRAGMENT_NODE Node.DOCUMENT_FRAGMENT_NODE}
341: * are allowed values.
342: */
343: private int nodeType = Node.ELEMENT_NODE;
344:
345: // ----------------------------------------------------------- Rule Methods
346:
347: /**
348: * Implemented to replace the content handler currently in use by a
349: * NodeBuilder.
350: *
351: * @param namespaceURI the namespace URI of the matching element, or an
352: * empty string if the parser is not namespace aware or the element has
353: * no namespace
354: * @param name the local name if the parser is namespace aware, or just
355: * the element name otherwise
356: * @param attributes The attribute list of this element
357: * @throws Exception indicates a JAXP configuration problem
358: */
359: public void begin(String namespaceURI, String name,
360: Attributes attributes) throws Exception {
361:
362: XMLReader xmlReader = getDigester().getXMLReader();
363: Document doc = documentBuilder.newDocument();
364: NodeBuilder builder = null;
365: if (nodeType == Node.ELEMENT_NODE) {
366: Element element = null;
367: if (getDigester().getNamespaceAware()) {
368: element = doc.createElementNS(namespaceURI, name);
369: for (int i = 0; i < attributes.getLength(); i++) {
370: element.setAttributeNS(attributes.getURI(i),
371: attributes.getLocalName(i), attributes
372: .getValue(i));
373: }
374: } else {
375: element = doc.createElement(name);
376: for (int i = 0; i < attributes.getLength(); i++) {
377: element.setAttribute(attributes.getQName(i),
378: attributes.getValue(i));
379: }
380: }
381: builder = new NodeBuilder(doc, element);
382: } else {
383: builder = new NodeBuilder(doc, doc.createDocumentFragment());
384: }
385: xmlReader.setContentHandler(builder);
386:
387: }
388:
389: /**
390: * Pop the Node off the top of the stack.
391: */
392: public void end() throws Exception {
393:
394: Object top = digester.pop();
395:
396: }
397:
398: }
|