## org.dom4j.io
Class SAXModifier

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

public class SAXModifier
extends 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.
`SAXModifier(boolean pruneElements)` Creates a new modifier.
`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(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(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(InputStream source)` Reads a Document from the given `InputStream`and writes it to the specified `XMLWriter`using SAX.
`Document` `modify(InputStream source, String systemId)` Reads a Document from the given `InputStream`and writes it to the specified `XMLWriter`using SAX.
`Document` `modify(Reader source)` Reads a Document from the given `Reader`and writes it to the specified `XMLWriter`using SAX.
`Document` `modify(Reader source, String systemId)` Reads a Document from the given `Reader`and writes it to the specified `XMLWriter`using SAX.
`Document` `modify(String source)` Reads a Document from the given URL or filename and writes it to the specified `XMLWriter`using SAX.
`Document` `modify(URL source)` Reads a Document from the given `URL`and writes it to the specified `XMLWriter`using SAX.
`void` `removeModifier(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 writer)` 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(File source)
                    throws DocumentException

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

  Parameters:
    `source` - is the `File` to read from.
  Returns:
    the newly created Document instance
  Throws:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### 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:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### modify

    public Document modify(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:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### modify

    public Document modify(InputStream source,
                           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.
    `systemId` - DOCUMENT ME!
  Returns:
    the newly created Document instance
  Throws:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### modify

    public Document modify(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:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### modify

    public Document modify(Reader source,
                           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.
    `systemId` - DOCUMENT ME!
  Returns:
    the newly created Document instance
  Throws:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### modify

    public Document modify(URL source)
                    throws DocumentException

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

  Parameters:
    `source` - is the `java.net.URL` to read from.
  Returns:
    the newly created Document instance
  Throws:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### modify

    public Document modify(String source)
                    throws DocumentException

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

  Parameters:
    `source` - is the URL or filename to read from.
  Returns:
    the newly created Document instance
  Throws:
    `DocumentException` - DocumentException org.dom4j.DocumentException} if an error occurs during parsing.

### addModifier

    public void addModifier(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
    `modifier` - The `ElementModifier`to be called by the event based processor.

### resetModifiers

    public void resetModifiers()

  Removes all registered `ElementModifier`instances from the event based processor.

### removeModifier

    public void removeModifier(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 writer)

  Sets the `XMLWriter`used to write the modified document.

  Parameters:
    `writer` - 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.

Copyright © 2001-2005 MetaStuff Ltd.. All Rights Reserved.