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.
DocumentFragment	cut(sk.baka.ikslibs.ptr.DomPointer from, sk.baka.ikslibs.ptr.DomPointer to) Deprecated.
sk.baka.ikslibs.levelmapper.NodeListID	delete(sk.baka.ikslibs.levelmapper.NodeListID list, int fromPos, int toPos) Deprecated.
void	endModify() Ends modification of document.
sk.baka.ikslibs.levelmapper.NodeListID	insertEntity(sk.baka.ikslibs.levelmapper.NodeListID list, int pos, String entityName) Deprecated.
void	insertFragment(DocumentFragment frag, sk.baka.ikslibs.ptr.DomPointer ptr) Deprecated.
void	insertNode(Node node, sk.baka.ikslibs.ptr.DomPointer ptr, boolean merge) Deprecated.
String	insertText(sk.baka.ikslibs.ptr.DOMPoint ip, Element contextElement, String value, short type) Deprecated.
String	insertText(sk.baka.ikslibs.ptr.DomPointer point, String value, short type) Deprecated.
String	insertText(sk.baka.ikslibs.ptr.DOMPoint ip, String contextId, String value, short type) Deprecated.
sk.baka.ikslibs.levelmapper.NodeListID	insertText(sk.baka.ikslibs.levelmapper.NodeListID list, int pos, String text, short type) Deprecated.
boolean	isModifying() Returns true, if document is being modified by caller thread.
boolean	isRemovable(sk.baka.ikslibs.ptr.DomPointer from, sk.baka.ikslibs.ptr.DomPointer to) Checks whether all nodes from specified range can be deleted - i.e.
void	remove(sk.baka.ikslibs.ptr.DomPointer from, sk.baka.ikslibs.ptr.DomPointer to) Deprecated.
void	remove(Node node) Removes given node from the document.
void	remove(String id) Deprecated.
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	setText(String id, String value) Deprecated.
Text	splitText(sk.baka.ikslibs.ptr.DomPointer ptr) Deprecated.
Text	splitText(String id, int pos) Deprecated.
Text	splitText(Text text, int pos) Deprecated.
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 sk.baka.xml.gene.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:

sk.baka.xml.gene.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

@Deprecated
public void setText(String id,
                               String value)

Deprecated.

Sets text, denoted by given id, to given value. It may be pi, comment or attribute node.

Parameters:

id - id of text node, that receives new value.

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

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.

splitText

@Deprecated
public Text splitText(String id,
                                 int pos)

Deprecated.

Splits the text/cdata node at the specified position. If pos is equal to zero or length of textual value of given text then nothing happens. The node denoted by given id is not moved, only its textual value is changed.

Parameters:

id - the id of the text/cdata node

pos - zero-based position where the text shall be splitted.

Returns:

a second half of the splitted node. It may be null when no splitting occured.

splitText

@Deprecated
public Text splitText(Text text,
                                 int pos)

Deprecated.

Splits the text/cdata node at the specified position. If pos is equal to zero or length of textual value of given text then nothing happens. The node denoted by given id is not moved, only its textual value is changed.

Parameters:

text - the text/cdata node

pos - zero-based position where the text shall be splitted.

Returns:

a second half of the splitted node. It may be null when no splitting occured.

splitText

@Deprecated
public Text splitText(sk.baka.ikslibs.ptr.DomPointer ptr)

Deprecated.

Splits the text/cdata node at the specified position. If pos is equal to zero or length of textual value of given text then nothing happens. The node denoted by given id is not moved, only its textual value is changed.

Parameters:

ptr - the pointer pointing into the text/cdata node.

Returns:

a second half of the splitted node. It may be null when no splitting occured.

insertText

@Deprecated
public String insertText(sk.baka.ikslibs.ptr.DOMPoint ip,
                                    String contextId,
                                    String value,
                                    short type)
                  throws DocumentException

Deprecated.

Inserts text into element, depending on given parameters. If ip points into text, then that text is modified instead. If ip points to a location next to node with equal type, then that text is modified instead.

Parameters:

ip - insert point, where to insert new text.

contextId - the context element, where new text must be inserted.

value - new text value. if null or empty string ("") is given, then nothing is created.

type - type of created node, one of Node.TEXT_NODE or Node.CDATA_SECTION_NODE constants. When modifying text, this parameter is ignored.

Returns:

id of newly created text element, or id of modified element. If value is empty or null, then null is returned.

Throws:

DocumentException - when element with given id doesn't exist or it doesn't denote regular element.

insertText

@Deprecated
public String insertText(sk.baka.ikslibs.ptr.DomPointer point,
                                    String value,
                                    short type)

Deprecated.

Inserts text into element, depending on given parameters. If ip points into text, then that text is modified instead. If ip points to a location next to node with equal type, then that text is modified instead.

Parameters:

point - insert point, where to insert new text. It must not point into an entity.

value - new text value. if null or empty string ("") is given, then nothing is created.

type - type of created node, one of Node.TEXT_NODE or Node.CDATA_SECTION_NODE constants. When modifying text, this parameter is ignored.

Returns:

id of newly created text element, or id of modified element. If value is empty or null, then null is returned.

insertText

@Deprecated
public String insertText(sk.baka.ikslibs.ptr.DOMPoint ip,
                                    Element contextElement,
                                    String value,
                                    short type)

Deprecated.

Inserts text into element, depending on given parameters. If ip points into text, then that text is modified instead. If ip points to a location next to node with equal type, then that text is modified instead.

Parameters:

ip - insert point, where to insert new text.

contextElement - the context element, where new text must be inserted.

value - new text value. if null or empty string ("") is given, then nothing is created.

type - type of created node, one of Node.TEXT_NODE or Node.CDATA_SECTION_NODE constants. When modifying text, this parameter is ignored.

Returns:

id of newly created text element, or id of modified element. If value is empty or null, then null is returned.

remove

@Deprecated
public void remove(String id)

Deprecated.

Removes node(s) with given id from document.

Parameters:

id - id of the node, that will be removed.

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.

insertNode

@Deprecated
public void insertNode(Node node,
                                  sk.baka.ikslibs.ptr.DomPointer ptr,
                                  boolean merge)

Deprecated.

Inserts the node at the specified pointer. The function does not use the ip part of the pointer hence it inserts node into correct place even if there was a node already inserted before this place. IP part is used only if merge is true and the node is a text or cdata node. If the node is an element then it receives an id, however no descendant elements receives an id.

Parameters:

node - the node to insert, it must be element, comment, pi, text or cdata only.

ptr - where to insert the node.

merge - if true then if new node is a text node then it will be merged with adjacent nodes if possible. If false then no merging is performed.

insertFragment

@Deprecated
public void insertFragment(DocumentFragment frag,
                                      sk.baka.ikslibs.ptr.DomPointer ptr)

Deprecated.

Inserts all nodes from specified document fragment into specified position. All nodes are automatically merged. All emp:id attributes are ignored. All nodes are removed from the fragment in the process and become part of the document.

Parameters:

frag - the fragment

ptr - where to insert nodes from the fragment.

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.

isRemovable

public boolean isRemovable(sk.baka.ikslibs.ptr.DomPointer from,
                           sk.baka.ikslibs.ptr.DomPointer to)

Checks whether all nodes from specified range can be deleted - i.e. if delete with these parameters shall succeed.

Parameters:

from - start of the removal interval. The node where this pointer points shall be removed (an exception is if some contents of the node are left after the operation).

to - end of the removal interval.

Returns:

true if the specified interval is removable, false otherwise.

remove

@Deprecated
public void remove(sk.baka.ikslibs.ptr.DomPointer from,
                              sk.baka.ikslibs.ptr.DomPointer to)

Deprecated.

Tries to remove all nodes in the specified range (the node pointed to by to parameter is not removed). The function shall not remove elements that shall not have all its children removed.

Parameters:

from - start of the removal interval. The node where this pointer points shall be removed (exception is a node which have some children left after the operation).

to - end of the removal interval. It may be null- in such case the function shall remove all nodes to the end of the document.

cut

@Deprecated
public DocumentFragment cut(sk.baka.ikslibs.ptr.DomPointer from,
                                       sk.baka.ikslibs.ptr.DomPointer to)

Deprecated.

Tries to remove all nodes in the specified range (the node pointed to by to parameter is not removed). Removed nodes are returned in a DocumentFragment instance. Both pointers must have the same parent element.

Parameters:

from - start of the removal interval. The node where this pointer points shall be removed.

to - end of the removal interval.

Returns:

DocumentFragment instance containing nodes that have been cut from the document. Never null. No element in the target fragment will have emp:id attribute.

insertText

@Deprecated
public sk.baka.ikslibs.levelmapper.NodeListID insertText(sk.baka.ikslibs.levelmapper.NodeListID list,
                                                                    int pos,
                                                                    String text,
                                                                    short type)

Deprecated.

Tries to insert some text into specified position.

Parameters:

list - current list of nodes, where to insert the text.

pos - the position in the textValue string.

type - type of created node, one of Node.TEXT_NODE or Node.CDATA_SECTION_NODE constants. When modifying text, this parameter is ignored.

text - the text to be inserted

Returns:

new instance of list that reflects the changes made to the document.

Throws:

IllegalArgumentException - if no text can be inserted at specified position.

insertEntity

@Deprecated
public sk.baka.ikslibs.levelmapper.NodeListID insertEntity(sk.baka.ikslibs.levelmapper.NodeListID list,
                                                                      int pos,
                                                                      String entityName)

Deprecated.

Inserts an entity into specified position.

Parameters:

list - current list of nodes, where to insert the entity.

pos - the position in the textValue string.

entityName - the name of the entity.

Returns:

new instance of list that reflects the changes made to the document.

delete

@Deprecated
public sk.baka.ikslibs.levelmapper.NodeListID delete(sk.baka.ikslibs.levelmapper.NodeListID list,
                                                                int fromPos,
                                                                int toPos)

Deprecated.

Tries to delete specified range of text.

Parameters:

list - list of text/cdata nodes. If function finishes succesfully and the document gets modified, this list is invalid and must not be used.

fromPos - the starting position

toPos - the ending position - character at this position shall not be deleted.

Returns:

new instance of list that reflects the changes made to the document.