/*
* 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 modifiers = new
HashMap();
/**
* 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 {@linkElementModifier}
* 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 {@linkElementModifier}
* 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 {@linkElementModifier}
* 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();
Iterator modifierIt = this.
modifiers.
entrySet().
iterator();
while (
modifierIt.
hasNext()) {
Map.
Entry entry = (
Map.
Entry)
modifierIt.
next();
SAXModifyElementHandler handler = new
SAXModifyElementHandler(
(
ElementModifier)
entry.
getValue());
reader.
addHandler((
String)
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.
*/