Java tutorial
/* * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. * * This software is open source. * See the bottom of this file for the licence. */ package org.dom4j.io; import java.io.File; import java.io.InputStream; import java.io.Reader; import java.net.URL; import java.util.HashMap; import java.util.Iterator; import java.util.Map; import org.dom4j.Document; import org.dom4j.DocumentException; import org.dom4j.DocumentFactory; import org.xml.sax.InputSource; import org.xml.sax.SAXException; import org.xml.sax.XMLReader; /** * The SAXModifier reads, modifies and writes XML documents using SAX. * * <p> * Registered {@link ElementModifier}objects can provide modifications to (part * of) the xml tree, while the document is still being processed. This makes it * possible to change large xml documents without having them in memory. * </p> * * <p> * The modified document is written when the {@link XMLWriter}is specified. * </p> * * @author Wonne Keysers (Realsoftware.be) * * @see org.dom4j.io.SAXReader * @see org.dom4j.io.XMLWriter */ public class SAXModifier { private XMLWriter xmlWriter; private XMLReader xmlReader; private boolean pruneElements; private SAXModifyReader modifyReader; private HashMap<String, ElementModifier> modifiers = new HashMap<String, ElementModifier>(); /** * Creates a new modifier. <br> * The XMLReader to parse the source will be created via the * org.xml.sax.driver system property or JAXP if the system property is not * set. */ public SAXModifier() { } /** * Creates a new modifier. <br> * The XMLReader to parse the source will be created via the * org.xml.sax.driver system property or JAXP if the system property is not * set. * * @param pruneElements * Set to true when the modified document must NOT be kept in * memory. */ public SAXModifier(boolean pruneElements) { this.pruneElements = pruneElements; } /** * Creates a new modifier that will the specified {@link * org.xml.sax.XMLReader} to parse the source. * * @param xmlReader * The XMLReader to use */ public SAXModifier(XMLReader xmlReader) { this.xmlReader = xmlReader; } /** * Creates a new modifier that will the specified {@link * org.xml.sax.XMLReader} to parse the source. * * @param xmlReader * The XMLReader to use * @param pruneElements * Set to true when the modified document must NOT be kept in * memory. */ public SAXModifier(XMLReader xmlReader, boolean pruneElements) { this.xmlReader = xmlReader; } /** * Reads a Document from the given {@link java.io.File}and writes it to the * specified {@link XMLWriter}using SAX. Registered {@link ElementModifier} * objects are invoked on the fly. * * @param source * is the <code>File</code> to read from. * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(File source) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Reads a Document from the given {@link org.xml.sax.InputSource}and * writes it to the specified {@link XMLWriter}using SAX. Registered * {@link ElementModifier}objects are invoked on the fly. * * @param source * is the <code>org.xml.sax.InputSource</code> to read from. * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(InputSource source) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Reads a Document from the given {@link java.io.InputStream}and writes it * to the specified {@link XMLWriter}using SAX. Registered {@link * ElementModifier} objects are invoked on the fly. * * @param source * is the <code>java.io.InputStream</code> to read from. * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(InputStream source) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Reads a Document from the given {@link java.io.InputStream}and writes it * to the specified {@link XMLWriter}using SAX. Registered {@link * ElementModifier} objects are invoked on the fly. * * @param source * is the <code>java.io.InputStream</code> to read from. * @param systemId * DOCUMENT ME! * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(InputStream source, String systemId) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Reads a Document from the given {@link java.io.Reader}and writes it to * the specified {@link XMLWriter}using SAX. Registered {@link * ElementModifier} objects are invoked on the fly. * * @param source * is the <code>java.io.Reader</code> to read from. * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(Reader source) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Reads a Document from the given {@link java.io.Reader}and writes it to * the specified {@link XMLWriter}using SAX. Registered {@link * ElementModifier} objects are invoked on the fly. * * @param source * is the <code>java.io.Reader</code> to read from. * @param systemId * DOCUMENT ME! * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(Reader source, String systemId) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Reads a Document from the given {@link java.net.URL}and writes it to the * specified {@link XMLWriter}using SAX. Registered {@link ElementModifier} * objects are invoked on the fly. * * @param source * is the <code>java.net.URL</code> to read from. * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(URL source) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Reads a Document from the given URL or filename and writes it to the * specified {@link XMLWriter}using SAX. Registered {@link ElementModifier} * objects are invoked on the fly. * * @param source * is the URL or filename to read from. * * @return the newly created Document instance * * @throws DocumentException * DocumentException org.dom4j.DocumentException} if an error * occurs during parsing. */ public Document modify(String source) throws DocumentException { try { return installModifyReader().read(source); } catch (SAXModifyException ex) { Throwable cause = ex.getCause(); throw new DocumentException(cause.getMessage(), cause); } } /** * Adds the {@link ElementModifier}to be called when the specified element * path is encounted while parsing the source. * * @param path * The element path to be handled * @param modifier * The {@link ElementModifier}to be called by the event based * processor. */ public void addModifier(String path, ElementModifier modifier) { this.modifiers.put(path, modifier); } /** * Removes all registered {@link ElementModifier}instances from the event * based processor. */ public void resetModifiers() { this.modifiers.clear(); getSAXModifyReader().resetHandlers(); } /** * Removes the {@link ElementModifier}from the event based processor, for * the specified element path. * * @param path * The path to remove the {@link ElementModifier}for. */ public void removeModifier(String path) { this.modifiers.remove(path); getSAXModifyReader().removeHandler(path); } /** * Get the {@link org.dom4j.DocumentFactory}used to create the DOM4J * document structure * * @return <code>DocumentFactory</code> that will be used */ public DocumentFactory getDocumentFactory() { return getSAXModifyReader().getDocumentFactory(); } /** * Sets the {@link org.dom4j.DocumentFactory}used to create the DOM4J * document tree. * * @param factory * <code>DocumentFactory</code> to be used */ public void setDocumentFactory(DocumentFactory factory) { getSAXModifyReader().setDocumentFactory(factory); } /** * Returns the current {@link XMLWriter}. * * @return XMLWriter */ public XMLWriter getXMLWriter() { return this.xmlWriter; } /** * Sets the {@link XMLWriter}used to write the modified document. * * @param writer * The writer to use. */ public void setXMLWriter(XMLWriter writer) { this.xmlWriter = writer; } /** * Returns true when xml elements are not kept in memory while parsing. The * {@link org.dom4j.Document}returned by the modify methods will be null. * * @return Returns the pruneElements. */ public boolean isPruneElements() { return pruneElements; } private SAXReader installModifyReader() throws DocumentException { try { SAXModifyReader reader = getSAXModifyReader(); if (isPruneElements()) { modifyReader.setDispatchHandler(new PruningDispatchHandler()); } reader.resetHandlers(); for (Map.Entry<String, ElementModifier> entry : this.modifiers.entrySet()) { SAXModifyElementHandler handler = new SAXModifyElementHandler(entry.getValue()); reader.addHandler(entry.getKey(), handler); } reader.setXMLWriter(getXMLWriter()); reader.setXMLReader(getXMLReader()); return reader; } catch (SAXException ex) { throw new DocumentException(ex.getMessage(), ex); } } private XMLReader getXMLReader() throws SAXException { if (this.xmlReader == null) { xmlReader = SAXHelper.createXMLReader(false); } return this.xmlReader; } private SAXModifyReader getSAXModifyReader() { if (modifyReader == null) { modifyReader = new SAXModifyReader(); } return modifyReader; } } /* * Redistribution and use of this software and associated documentation * ("Software"), with or without modification, are permitted provided that the * following conditions are met: * * 1. Redistributions of source code must retain copyright statements and * notices. Redistributions must also contain a copy of this document. * * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * 3. The name "DOM4J" must not be used to endorse or promote products derived * from this Software without prior written permission of MetaStuff, Ltd. For * written permission, please contact dom4j-info@metastuff.com. * * 4. Products derived from this Software may not be called "DOM4J" nor may * "DOM4J" appear in their names without prior written permission of MetaStuff, * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd. * * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org * * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved. */