sk.baka.ikslibs.modify
Class DOMMutils

java.lang.Object
  sk.baka.ikslibs.modify.DOMMutils

public final class DOMMutils
extends Object

Utility class for the document mutation. Does not check if the mutation operation breaks validity of the document.

Author:

Martin Vysny

Method Summary

static void	clearAttributes(Node node) Removes all attribute nodes (including xmlns: attributes) from given node.
static boolean	clearChildren(Node node, boolean checkUndeletable) Deletes all child nodes in the node (all nodes from the document, for example).
static Attr	createAttribute(Element e, QName qname, String value) Creates an attribute.
static Attr	createAttribute(Element e, String prefix, String localName, String namespace, String value) Creates an attribute.
static Attr	createXmlnsAttribute(Element e, String namespaceUri, String prefix) Creates an xmlns attribute, that maps given namespace to a prefix.
static void	createXmlnsAttributes(Element e, Map<String,String> namespaces) Adds and/or replaces xmlns mapping for all given namespaces in given element.
static DocumentFragment	cut(DOMInterval interval) Tries to remove all nodes in the specified range.
static NodeListID	delete(NodeListID list, int fromPos, int toPos) Tries to delete specified range of text.
static NodeListID	insertEntity(NodeListID list, int pos, String entityName, EntityManager em) Inserts an entity into specified position.
static void	insertFragment(DocumentFragment frag, DomPointer ptr) Inserts all nodes from specified document fragment into specified position.
static void	insertNode(Node node, DomPointer ptr, boolean merge) Inserts the node at the specified pointer.
static CharacterData	insertText(DOMPoint p, Element contextElement, String value, short type) Inserts text into element, depending on given parameters.
static CharacterData	insertText(DomPointer point, String value, short type) Inserts text into element, depending on given parameters.
static NodeListID	insertText(NodeListID list, int pos, String text, short type) Tries to insert given text into specified position.
boolean	isRemovable(DomPointer from, DomPointer to) Checks whether all nodes from specified range can be deleted - i.e.
static void	mergeTextNodes(Node node, MergeTypeEnum mergeType) Merges the adjacent text nodes into one.
static void	mergeTextNodesOnly(Node node, MergeTypeEnum mergeType) Merges the adjacent text nodes into one.
static DocumentFragment	moveContentToFragment(Document doc) Moves all content nodes from the document into newly created document fragment.
static void	normalizeWhitespaces(Node node) If the node is a text node then all starting and trailing whitespaces are removed, and all consecutive whitespaces are replaced by a single space.
static String	normalizeWhitespaces(String string) All starting and trailing whitespaces are removed, and all consecutive whitespaces are replaced by a single space character.
static void	normalizeWhitespacesTree(Node node) Whitespace-normalizes all nodes that are descendants of given node.
static void	remove(DOMInterval interval) Tries to remove all nodes in the specified range.
static void	remove(Node node) Removes given node from the document.
static void	remove(NodeListID nodeList) Removes node(s) from the document.
static void	removeIf(Node node, boolean onlyIfEmpty, boolean onlyCharacterContainer) Removes node from its parent (or owner element in case of an attribute).
static void	removeXmlns(Element e) Removes all xmlns attributes from given element.
void	replaceNode(Node node, Node newNode) Replaces the node with another node.
static boolean	setData(Node node, String data) Modifies data, associated with given node.
static void	setText(NodeListID nodeList, String value) Sets text, denoted by given id, to given value.
static void	setText(Node node, String value) Sets text of given node to given value.
static Text	splitText(DomPointer ptr) Splits the text/cdata node at the specified position.
static Text	splitText(NodeListID list, int pos) Splits the text/cdata node at the specified position.
static Text	splitText(Text text, int pos) Splits the text/cdata node at the specified position.
static DocumentFragment	toFragment(Node node) Converts the node into a document fragment.

Methods inherited from class java.lang.Object

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

Method Detail

normalizeWhitespaces

public static void normalizeWhitespaces(Node node)

If the node is a text node then all starting and trailing whitespaces are removed, and all consecutive whitespaces are replaced by a single space.

Parameters:

node - the node to modify

normalizeWhitespaces

public static String normalizeWhitespaces(String string)

All starting and trailing whitespaces are removed, and all consecutive whitespaces are replaced by a single space character.

Parameters:

string - the string to normalize

Returns:

whitespace-normalized string.

normalizeWhitespacesTree

public static void normalizeWhitespacesTree(Node node)

Whitespace-normalizes all nodes that are descendants of given node. If a text node is blank then it is completely removed from the document tree.

Parameters:

node - the root of the tree to normalize.

setText

public static void setText(NodeListID nodeList,
                           String value)

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

Parameters:

nodeList - the node list that will receive new value.

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

setText

public static 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

public static Text splitText(NodeListID list,
                             int pos)

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:

list - the nodelist.

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

public static Text splitText(Text text,
                             int pos)

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

public static Text splitText(DomPointer ptr)

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

public static CharacterData insertText(DomPointer point,
                                       String value,
                                       short type)

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:

newly created text node, or a modified text node. If value is empty or null, then null is returned.

insertText

public static CharacterData insertText(DOMPoint p,
                                       Element contextElement,
                                       String value,
                                       short type)

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:

p - 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:

newly created text node, or a modified text node. If value is empty or null, then null is returned.

remove

public static void remove(NodeListID nodeList)

Removes node(s) from the document.

Parameters:

nodeList - nodes that shall be removed.

remove

public static 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.

removeIf

public static void removeIf(Node node,
                            boolean onlyIfEmpty,
                            boolean onlyCharacterContainer)

Removes node from its parent (or owner element in case of an attribute). Does nothing when the node has no parent.

Parameters:

node - the node to remove

onlyIfEmpty - if true then the node is removed only if it has zero children (or empty data in case of character container).

onlyCharacterContainer - if true then only character containers are removed (empty elements are not removed)

createAttribute

public static Attr 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:

the newly created attribute instance.

createAttribute

public static Attr 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:

the newly created attribute instance.

insertNode

public static void insertNode(Node node,
                              DomPointer ptr,
                              boolean merge)

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

public static void insertFragment(DocumentFragment frag,
                                  DomPointer ptr)

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(DomPointer from,
                           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

public static void remove(DOMInterval interval)

Tries to remove all nodes in the specified range. The function shall not remove elements that shall not have all its children removed. A quick normalization is performed after the node removal.

For description of removed contents please see Range.deleteContents() and DOM ranges.

Parameters:

interval - the interval to be removed. It must not be attribute interval.

cut

public static DocumentFragment cut(DOMInterval interval)

Tries to remove all nodes in the specified range. Removed nodes are returned in a DocumentFragment instance. A quick normalization is performed after the node removal.

For description of removed contents please see Range.extractContents() and DOM ranges.

Parameters:

interval - the interval to be removed. It must not be attribute interval.

Returns:

DocumentFragment instance containing nodes that have been cut from the document. Never null.

insertText

public static NodeListID insertText(NodeListID list,
                                    int pos,
                                    String text,
                                    short type)

Tries to insert given 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

public static NodeListID insertEntity(NodeListID list,
                                      int pos,
                                      String entityName,
                                      EntityManager em)

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.

em - the entity manager for the document.

Returns:

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

delete

public static NodeListID delete(NodeListID list,
                                int fromPos,
                                int toPos)

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.

mergeTextNodes

public static void mergeTextNodes(Node node,
                                  MergeTypeEnum mergeType)

Merges the adjacent text nodes into one. If node denotes text node then this node is merged with its siblings. If node denotes a container then all its children are merged.

Parameters:

node - denotes the placement of the nodes to merge. If node is a container node then all its children are merged

mergeType - one of the merge constants.

mergeTextNodesOnly

public static void mergeTextNodesOnly(Node node,
                                      MergeTypeEnum mergeType)

Merges the adjacent text nodes into one. If node denotes text node then this node is merged with its siblings, otherwise the function does nothing.

Parameters:

node - denotes the placement of the nodes to merge.

mergeType - one of the merge constants.

removeXmlns

public static void removeXmlns(Element e)

Removes all xmlns attributes from given element.

Parameters:

e - element to modify.

Throws:

UnremovableNodeException - if an unremovable xmlns attribute occured.

clearAttributes

public static void clearAttributes(Node node)

Removes all attribute nodes (including xmlns: attributes) from given node.

Parameters:

node - remove attributes from this node. Only element can have attributes hence function does nothing for other types of nodes.

Throws:

UnremovableNodeException - if some attributes are not removable.

toFragment

public static DocumentFragment toFragment(Node node)

Converts the node into a document fragment. If node is a document fragment then it is simply returned. If node is a document then all nodes are moved using the moveContentToFragment method. If node is content node then it shall be the sole child of the returned fragment.

Parameters:

node - node to convert.

Returns:

document fragment representing given node.

Throws:

IllegalArgumentException - if node is not fragment, document nor content node.

moveContentToFragment

public static DocumentFragment moveContentToFragment(Document doc)

Moves all content nodes from the document into newly created document fragment.

Parameters:

doc - the document node.

Returns:

fragment containing all content children of given document.

clearChildren

public static boolean clearChildren(Node node,
                                    boolean checkUndeletable)

Deletes all child nodes in the node (all nodes from the document, for example). Does nothing for non-container nodes like text, cdata, pi, comment, attribute.

Parameters:

node - the node.

checkUndeletable - if true then function will fail if undeletable element occurs.

Returns:

true if all children were succesfully deleted, false otherwise.

Throws:

UnremovableNodeException - if one of its children cannot be removed.

setData

public static boolean setData(Node node,
                              String data)

Modifies data, associated with given node.

Parameters:

node - the node.

data - character data, that the node will contain. null is threated as an empty string.

Returns:

true, if data was changed, or false when the original data were the same as the new data.

createXmlnsAttributes

public static void createXmlnsAttributes(Element e,
                                         Map<String,String> namespaces)

Adds and/or replaces xmlns mapping for all given namespaces in given element.

Parameters:

e - the element.

namespaces - collection of namespaces. All these namespaces' mappings are added to element. Maps namespace to a prefix.

createXmlnsAttribute

public static Attr createXmlnsAttribute(Element e,
                                        String namespaceUri,
                                        String prefix)

Creates an xmlns attribute, that maps given namespace to a prefix. When an XML namespace is given then null is returned. Attribute is attached to the element.

Parameters:

e - element, where to create element.

namespaceUri - creates xmlns mapping for this namespace.

prefix - the prefix.

Returns:

xmlns attribute node, or null if trying to map a xmlns prefix and/or namespace.