sk.uniba.euromath.document
Class DocumentModifier

java.lang.Object
  sk.uniba.euromath.document.DocumentModifier

public final class DocumentModifier
extends Object

Serves for modifying document. Tracks changes in document, and makes them consistent with 'splitted' images of document. Accessible from out of document package. All functions work on DOM-level nodes. Thread safe.

This class is unchecked - it allows to set given text or modify document structure even if the change violates the grammar rules. Caller should make sure that the document is valid before the transformation execution.

WARNING: when modifying the document, then IDs pointing to nodes after node being modified can become invalid (may denote a wrong node) - this happens for example when the text/cdata/comment/pi node is deleted (for example, when null value is given to a setText() function).

Author:

Martin Vysny

Method Summary

String	createAttribute(Element e, QName qname, String value) Creates an attribute.
String	createAttribute(Element e, String prefix, String localName, String namespace, String value) Creates an attribute.
String	createAttribute(String id, QName qname, String value) Creates an attribute.
String	createAttribute(String id, String prefix, String localName, String namespace, String value) Creates an attribute.
void	endModify() Ends modification of document.
boolean	isModifying() Returns true, if document is being modified by caller thread.
void	remove(Node node) Removes given node from the document.
void	replaceNode(Node node, Node newNode) Replaces the node with another node.
void	setText(Node node, String value) Sets text of given node to given value.
void	startModify() Begins modification sequence.

Methods inherited from class java.lang.Object

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

Method Detail

startModify

public void startModify()

Begins modification sequence. All modifications to document must be enclosed with startModify() .. endModify() sequence. In other words, modifying document when isModifying()==false will result in IllegalStateException. startModify() calls can be nested, i.e. it is possible to call startModify() when isModifying(), but every call to startModify() should be closed with endModify(), otherwise document won't be never transformed, and other threads will block forever.

Two threads cannot modify one document concurrently. If one thread is currently modifying a document and second thread calls startModify(), the function will block until current thread finishes the modification.

endModify

public void endModify()
               throws ExportException

Ends modification of document. It may still be possible to edit document, when every call to startModify() wasn't yet accompanied by endModify() call. When last startModify() is closed by this call, transformation is performed.

Throws:

ExportException - when something goes wrong in the process of transformation.

isModifying

public boolean isModifying()

Returns true, if document is being modified by caller thread.

Returns:

true, if document is being modified, false otherwise.

setText

public void setText(Node node,
                    String value)

Sets text of given node to given value. It may be pi, comment, attribute, text or cdata node only.

Parameters:

node - the text node, that receives new value.

value - new text value. null value is equivalent to an empty string.

remove

public void remove(Node node)

Removes given node from the document. If both previous and next sibling of the node are of same text type (text or cdata) then these nodes are merged into one.

Parameters:

node - the node, that will be removed. Its id is removed aswell, but the id of descendants is not removed.

createAttribute

public String createAttribute(String id,
                              String prefix,
                              String localName,
                              String namespace,
                              String value)

Creates an attribute. If attribute with given local name and namespace is already present in context node, its value is modified instead - prefix is not changed.

Parameters:

id - id of element, that contains the attribute.

prefix - prefix of qname of attribute. See NamespaceManager for details.

localName - local name of attribute.

namespace - namespace of attribute.

value - new value for attribute.

Returns:

ID of newly created attribute.

createAttribute

public String createAttribute(String id,
                              QName qname,
                              String value)

Creates an attribute. If attribute with given local name and namespace is already present in context node, its value is modified instead - prefix is not changed.

Parameters:

id - id of element, that contains the attribute.

qname - qualified name of the attribute

value - new value for attribute.

Returns:

ID of newly created attribute.

createAttribute

public String createAttribute(Element e,
                              QName qname,
                              String value)

Creates an attribute. If attribute with given local name and namespace is already present in context node, its value is modified instead - prefix is not changed.

Parameters:

e - element, that contains the attribute.

qname - qualified name of the attribute

value - new value for attribute.

Returns:

ID of newly created attribute.

createAttribute

public String createAttribute(Element e,
                              String prefix,
                              String localName,
                              String namespace,
                              String value)

Creates an attribute. If attribute with given local name and namespace is already present in context node, its value is modified instead - prefix is not changed.

Parameters:

e - element, that contains the attribute.

prefix - prefix of qname of attribute. See NamespaceManager for details.

localName - local name of attribute.

namespace - namespace of attribute.

value - new value for attribute.

Returns:

ID of newly created attribute.

replaceNode

public void replaceNode(Node node,
                        Node newNode)

Replaces the node with another node. newNode must have null parent or it must be from another document.

Parameters:

node - the node to be replaced.

newNode - the node will be replaced with this node. If null then given node is removed. If not from our document then it is automatically imported.