sk.uniba.euromath.document
Class DomPointer

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

All Implemented Interfaces:

Comparable

public final class DomPointer
extends Object
implements Comparable

Represents immutable pointer to contents of document. It always points between nodes (if there are any). The following is true:

• beforePoints and pointsTo is null if and only if parent doesn't have any child elements.
• Object doesn't respond to DOM modification, so when document is modified after object creation, properties may not be valid.

DomPointerFlag flags define behaviour of getNext, getPrevious,getNearest, getFirst and getLast functions. By default, when no flags are specified then any insertpoint will do. These flags specify restrictions on returned pointer.

Warning! Tests for equality and comparing pointers may seem inconsistent: If one pointer is pointing after the last character of the text node and second pointer points right after this text node having pos parameter equal to zero, then it seems that these two pointers are pointing at same position in the document however they are not equal. In such case try normalization and/or entity skipping.

The pointer can be compared only to pointers pointing into same tree. Comparing disconnected pointers (for example pointing into two different fragments) is disallowed and results in IllegalArgumentException.

Author:

Martin Vysny

Field Summary

Node	beforePoints Pointer points right after this node.
String	beforePointsId Id of node, after which pointer points.
(package private) DomCore	doc Reference to document.
InsertPoint	ip InsertPoint representation of pointer.
Node	parent Pointer points to contents of this node.
Node	parentContainer Pointer points to contents of this container - an ID-level node holder; it is never an entity reference, for example.
Element	parentElement Pointer points to contents of this element.
String	parentElementId Pointer points to contents of this element.
String	parentId Id of parent element (the element, to which contents the pointer points).
Node	pointsTo Pointer points to (before) this node.
String	pointsToId Holds id of node, where the pointer points.

Constructor Summary

DomPointer(DomCore doc, Node parent, InsertPoint ip, ElementRule parentElementRule, Boolean inEntity)
Constructs instance of pointer.

Method Summary

int	compareTo(Object obj)
boolean	createsText(short type) Queries, whether creating text at this point really creates a new text node, or it merely modifies corresponding adjacent node.
boolean	descendsFrom(Node node) Checks, whether this pointer points into contents of given node.
boolean	equals(Object obj)
Document	getDocument() Returns the document where the pointer points.
DomPointer	getNext(EnumSet<DomPointerFlag> ptrFlags, boolean canReturnSelf, boolean dontGoIntoElements) Returns pointer to next node, in Document order ordering (as if serialized, see W3C definition).
DomPointer	getNextSibling() Creates new instance of pointer, that points to next node.
(package private) ElementRule	getParentElementRule() Caches and returns rule for parent element.
DomPointer	getPrevious(EnumSet<DomPointerFlag> ptrFlags, boolean canReturnSelf, boolean dontGoIntoElements) Returns pointer to previous node in Document order ordering (as if serialized, see W3C definition).
DomPointer	getPreviousSibling() Creates new instance of pointer, that points to the beforePoints node.
int	hashCode()
boolean	inEntity() Queries if this pointer points into contents of, or a descendant of an EntityReference node.
boolean	isPointingIntoText() Checks if this pointer points into a text node.
DomPointer	normalize() Normalizes the pointer.
DomPointer	skipFromEntities() Skips forwards and backwards out from entities as much as possible.
DomPointer	skipFromEntities(boolean forward) Tries to skip out of entities as much as possible.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

parent

public final Node parent

Pointer points to contents of this node. Never null. May be instance of Element,EntityReference, Document and DocumentFragment.

parentId

public final String parentId

Id of parent element (the element, to which contents the pointer points). It may be null only if this parent is not an element.

parentElement

public final Element parentElement

Pointer points to contents of this element. May be null in case when there is no parent element (pointer points onto root element, into child of document fragment etc). If parent is Element node then this value represents same instance as parent.

parentElementId

public final String parentElementId

Pointer points to contents of this element. May be null if and only if parentElement is null. If parent is Element node then this value is equal to parentId.

parentContainer

public final Node parentContainer

Pointer points to contents of this container - an ID-level node holder; it is never an entity reference, for example. Never null. It is equal to parentElement if it is not null. If parentElement is null then this container is a Document or document fragment instance.

ip

public final InsertPoint ip

InsertPoint representation of pointer.

pointsTo

public final Node pointsTo

Pointer points to (before) this node. If pointer points to end of node sequence, then this value is null.

pointsToId

public final String pointsToId

Holds id of node, where the pointer points. It is null if and only if pointsTo is null or pointsTo cannot have ID (EntityReference node, for example).

beforePoints

public final Node beforePoints

Pointer points right after this node. It is previous sibling of pointsTo node. It can be null - then pointer points at the start of node sequence.

beforePointsId

public final String beforePointsId

Id of node, after which pointer points. It is null if and only if beforePoints is null or beforePoints cannot have ID (EntityReference node, for example).

doc

final DomCore doc

Reference to document. It may be null: in that case the PTR_INSERT_TEXT and PTR_INSERT_ELEMENT cannot be used.

Constructor Detail

DomPointer

DomPointer(DomCore doc,
           Node parent,
           InsertPoint ip,
           ElementRule parentElementRule,
           Boolean inEntity)

Constructs instance of pointer.

Parameters:

doc - the document instance. It may be null: then parentId,pointsToId, beforePointsId and getParentElementRule() will always be null, and PTR_INSERT_TEXT and PTR_INSERT_ELEMENT will be ignored.

parent - Pointer points to contents of this element. It must not be null. It may be element, entity reference, document or document fragment node.

ip - insertpoint, where the pointer points.

parentElementRule - rule for parent. If null, it will be computed when needed.

inEntity - if this pointer points into an entity. If null, it will be computed when needed.

Method Detail

getParentElementRule

ElementRule getParentElementRule()

Caches and returns rule for parent element.

Returns:

rule for parent element.

getNext

public DomPointer getNext(EnumSet<DomPointerFlag> ptrFlags,
                          boolean canReturnSelf,
                          boolean dontGoIntoElements)

Returns pointer to next node, in Document order ordering (as if serialized, see W3C definition).

Parameters:

ptrFlags - flags, that must result pointer comply.

canReturnSelf - if false then the pointer returned must not be equal to this pointer.

dontGoIntoElements - if true then the algorithm may leave an element but it may never enter an element and enumerate its content.

Returns:

pointer, that points in next nearest possible pointer. May return this if PTR_CAN_RETURN_SELF is specified. If null, then there is no such next node.

getNextSibling

public DomPointer getNextSibling()

Creates new instance of pointer, that points to next node. If this pointer points to end of nodelist, then returns null.

Returns:

pointer, pointing on node after ours.

getPreviousSibling

public DomPointer getPreviousSibling()

Creates new instance of pointer, that points to the beforePoints node. If this pointer points to start of nodelist, then returns null.

Returns:

pointer, pointing on node before ours.

getPrevious

public DomPointer getPrevious(EnumSet<DomPointerFlag> ptrFlags,
                              boolean canReturnSelf,
                              boolean dontGoIntoElements)

Returns pointer to previous node in Document order ordering (as if serialized, see W3C definition).

Parameters:

ptrFlags - flags, that must result pointer comply.

canReturnSelf - if false then the pointer returned must not be equal to this pointer.

dontGoIntoElements - if true then the algorithm may leave an element but it may never enter an element and enumerate its content.

Returns:

pointer, that points in previous nearest possible pointer. May return this if PTR_CAN_RETURN_SELF is specified. If null, then there is no such previous node.

createsText

public boolean createsText(short type)

Queries, whether creating text at this point really creates a new text node, or it merely modifies corresponding adjacent node.

Parameters:

type - desired type of new node, one of Node.TEXT_NODE or Node.CDATA_SECTION_NODE values.

Returns:

false if newly created node will be immediately merged with adjacent node.

inEntity

public boolean inEntity()

Queries if this pointer points into contents of, or a descendant of an EntityReference node. It also means that these contents are unmodifiable.

Returns:

true if parent is descendant of, or if itself is an EntityReference node.

descendsFrom

public boolean descendsFrom(Node node)

Checks, whether this pointer points into contents of given node.

Parameters:

node - node to check.

Returns:

true if it points into children of given node or into children of descendant of the node.

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

compareTo

public int compareTo(Object obj)

Specified by:

compareTo in interface Comparable

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

skipFromEntities

public DomPointer skipFromEntities(boolean forward)

Tries to skip out of entities as much as possible. Returns equivalent pointer nearest to the root of the DOM tree, skips out of entities in selected direction. [Two pointers are equivalent when their destination points (the point where the pointer points) may not necessarily be equal in DOM level but they are equal (they overlap) in ID level (see IdDomMapper for details)].

Parameters:

forward - if try to move from entity backwards or forwards.

Returns:

pointer p, such that p.next (or p.previous) non-entity reference node is equivalent to this. If forward then the pointer shall point right after the entity node (if available). If backwards then the pointer points onto the entity node (if available).

skipFromEntities

public DomPointer skipFromEntities()

Skips forwards and backwards out from entities as much as possible.

Returns:

pointer p equivalent to this, nearest to the root.

normalize

public DomPointer normalize()

Normalizes the pointer. Presently, only the ip.pos is checked and if it points after the last character of the text node then returned pointer shall point to next node.

Returns:

normalized pointer. If the pointer does not need to be normalized then this is returned.

getDocument

public Document getDocument()

Returns the document where the pointer points. Never null.

Returns:

the document instance.

isPointingIntoText

public boolean isPointingIntoText()

Checks if this pointer points into a text node.

Returns:

true if this pointer points onto a text node, false otherwise.