org.dom4j.io
Class SAXModifier

java.lang.Object
  org.dom4j.io.SAXModifier

public class SAXModifier

extends java.lang.Object

The SAXModifier reads, modifies and writes XML documents using SAX.
Registered 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.
The modified document is written when the XMLWriter is specified.

Author:

Wonne Keysers (Realsoftware.be)

See Also:

SAXReader, XMLWriter

Constructor Summary

SAXModifier()
Creates a new modifier.
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.

SAXModifier(boolean pruneElements)
Creates a new modifier.
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.

SAXModifier(XMLReader xmlReader)
Creates a new modifier that will the specified XMLReader to parse the source.

SAXModifier(XMLReader xmlReader, boolean pruneElements)
Creates a new modifier that will the specified XMLReader to parse the source.

Method Summary

void	addModifier(java.lang.String path, ElementModifier modifier) Adds the ElementModifier to be called when the specified element path is encounted while parsing the source.
DocumentFactory	getDocumentFactory() Get the DocumentFactory used to create the DOM4J document structure
XMLWriter	getXMLWriter() Returns the current XMLWriter.
boolean	isPruneElements() Returns true when xml elements are not kept in memory while parsing.
Document	modify(java.io.File source) Reads a Document from the given File and writes it to the specified XMLWriter using SAX.
Document	modify(InputSource source) Reads a Document from the given InputSource and writes it to the specified XMLWriter using SAX.
Document	modify(java.io.InputStream source) Reads a Document from the given InputStream and writes it to the specified XMLWriter using SAX.
Document	modify(java.io.InputStream source, java.lang.String systemId) Reads a Document from the given InputStream and writes it to the specified XMLWriter using SAX.
Document	modify(java.io.Reader source) Reads a Document from the given Reader and writes it to the specified XMLWriter using SAX.
Document	modify(java.io.Reader source, java.lang.String systemId) Reads a Document from the given Reader and writes it to the specified XMLWriter using SAX.
Document	modify(java.lang.String source) Reads a Document from the given URL or filename and writes it to the specified XMLWriter using SAX.
Document	modify(java.net.URL source) Reads a Document from the given URL and writes it to the specified XMLWriter using SAX.
void	removeModifier(java.lang.String path) Removes the ElementModifier from the event based processor, for the specified element path.
void	resetModifiers() Removes all registered ElementModifier instances from the event based processor.
void	setDocumentFactory(DocumentFactory factory) Sets the DocumentFactory used to create the DOM4J document tree.
void	setXMLWriter(XMLWriter xmlWriter) Sets the XMLWriter used to write the modified document.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SAXModifier

public SAXModifier()

Creates a new modifier.
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.

SAXModifier

public SAXModifier(boolean pruneElements)

Creates a new modifier.
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.

Parameters:

pruneElements - Set to true when the modified document must NOT be kept in memory.

SAXModifier

public SAXModifier(XMLReader xmlReader)

Creates a new modifier that will the specified XMLReader to parse the source.

Parameters:

xmlReader - The XMLReader to use

SAXModifier

public SAXModifier(XMLReader xmlReader,
                   boolean pruneElements)

Creates a new modifier that will the specified XMLReader to parse the source.

Parameters:

xmlReader - The XMLReader to use

pruneElements - Set to true when the modified document must NOT be kept in memory.

Method Detail

modify

public Document modify(java.io.File source)
                throws DocumentException

Reads a Document from the given File and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the File to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

modify

public Document modify(InputSource source)
                throws DocumentException

Reads a Document from the given InputSource and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the org.xml.sax.InputSource to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

modify

public Document modify(java.io.InputStream source)
                throws DocumentException

Reads a Document from the given InputStream and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the java.io.InputStream to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

modify

public Document modify(java.io.InputStream source,
                       java.lang.String systemId)
                throws DocumentException

Reads a Document from the given InputStream and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the java.io.InputStream to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

modify

public Document modify(java.io.Reader source)
                throws DocumentException

Reads a Document from the given Reader and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the java.io.Reader to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

modify

public Document modify(java.io.Reader source,
                       java.lang.String systemId)
                throws DocumentException

Reads a Document from the given Reader and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the java.io.Reader to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

modify

public Document modify(java.net.URL source)
                throws DocumentException

Reads a Document from the given URL and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the java.net.URL to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

modify

public Document modify(java.lang.String source)
                throws DocumentException

Reads a Document from the given URL or filename and writes it to the specified XMLWriter using SAX. Registered ElementModifier objects are invoked on the fly.

Parameters:

source - is the URL or filename to read from.

Returns:

the newly created Document instance

Throws:

{@link - org.dom4j.DocumentException} if an error occurs during parsing.

DocumentException

addModifier

public void addModifier(java.lang.String path,
                        ElementModifier modifier)

Adds the ElementModifier to be called when the specified element path is encounted while parsing the source.

Parameters:

path - The element path to be handled

resetModifiers

public void resetModifiers()

Removes all registered ElementModifier instances from the event based processor.

removeModifier

public void removeModifier(java.lang.String path)

Removes the ElementModifier from the event based processor, for the specified element path.

Parameters:

path - The path to remove the ElementModifier for.

getDocumentFactory

public DocumentFactory getDocumentFactory()

Get the DocumentFactory used to create the DOM4J document structure

Returns:

DocumentFactory that will be used

setDocumentFactory

public void setDocumentFactory(DocumentFactory factory)

Sets the DocumentFactory used to create the DOM4J document tree.

Parameters:

factory - DocumentFactory to be used

getXMLWriter

public XMLWriter getXMLWriter()

Returns the current XMLWriter.

Returns:

XMLWriter

setXMLWriter

public void setXMLWriter(XMLWriter xmlWriter)

Sets the XMLWriter used to write the modified document.

Parameters:

xmlWriter - The writer to use.

isPruneElements

public boolean isPruneElements()

Returns true when xml elements are not kept in memory while parsing. The Document returned by the modify methods will be null.

Returns:

Returns the pruneElements.