sk.baka.ikslibs.ptr
Class DOMPoint

java.lang.Object
  sk.baka.ikslibs.ptr.DOMPoint

All Implemented Interfaces:

Comparable

public final class DOMPoint
extends Object
implements Comparable

A lightweight pointer. It does not even contain the parent node. Defines a point in some arbitrary node. The point is specified by nodeIndex and pos parameters. If nodeIndex denotes Element, the pointer points before this Element. In this case, the pos argument is ignored and should be set to zero. If nodeIndex denotes CharacterData, then pos specifies the index of a character, where the pointer points. Immutable, thread-safe.

The comparator employs these additional document order rules on the namespace and attribute nodes of each element:

• An element's namespace and attribute nodes have a document order position greater than the element but less than any child node of the element.
• Namespace (xmlns:) nodes have a lesser document order position than attribute nodes.
• An element's namespace nodes are sorted lexicographically by local name (the default namespace node, if one exists, has no local name and is therefore lexicographically least).
• An element's attribute nodes are sorted lexicographically with namespace URI as the primary key and local name as the secondary key (an empty namespace URI is lexicographically least).

Lexicographic comparison, which orders strings from least to greatest alphabetically, is based on the UCS codepoint values, which is equivalent to lexicographic ordering based on UTF-8.

Author:

Martin Vysny

Field Summary

QName	attrName If not null then this point points into attribute with this qname.
static DOMPoint	FIRST A first point in any context node.
int	nodeIndex Index of the node, where the pointer points.
int	pos If nodeIndex denotes CharacterData or attrName specifies an attribute, then this parameter defines index of character in this CharacterData or Attr, after which to insert new element.

Constructor Summary

DOMPoint(int nodeIndex, int pos)
Creates instance of the point, pointing onto a child node.

DOMPoint(QName attrName, int pos)
Creates instance of the point, pointing onto an attribute.

Method Summary

int	compareTo(Object obj)
boolean	equals(Object obj)
static DOMPoint	getLast(Element e) Returns a point pointing after the last child node of e.
Node	getNode(Node parent) Returns node that this points point on.
int	hashCode()
boolean	isAttrPoint() Checks if this point points into contents of an attribute
boolean	isValid(Node parent, boolean mustPointToNode, boolean mayPointAfterLastChar) Checks if this point is valid in the context of given parent node.
boolean	isValid(NodeList list, boolean mustPointToNode, boolean mayPointAfterLastChar) Checks if this point is valid in the context of given node list.
boolean	isXmlnsAttrPoint() Checks if this point points into contents of an xmlns attribute
String	toString() Converts insertpoint object to a string using syntax: [insertPlace,pos].
static DOMPoint	valueOf(Node node, int pos) Retrieves the DOM point pointing onto given node.
static DOMPoint	valueOf(String string) Parses given string and returns an insert point instance.

Methods inherited from class java.lang.Object

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

Field Detail

nodeIndex

public final int nodeIndex

Index of the node, where the pointer points. If 0, it points before the first node. Never less than zero. Ignored (set to 0) when attrName is not null.

pos

public final int pos

If nodeIndex denotes CharacterData or attrName specifies an attribute, then this parameter defines index of character in this CharacterData or Attr, after which to insert new element. This value must not be negative.

attrName

public final QName attrName

If not null then this point points into attribute with this qname.

FIRST

public static final DOMPoint FIRST

A first point in any context node. Node inserted at this point will be first in the sequence of nodes.

Constructor Detail

DOMPoint

public DOMPoint(int nodeIndex,
                int pos)

Creates instance of the point, pointing onto a child node.

Parameters:

nodeIndex - index of node in parent parameter. Defines place, where we want to insert new element. When 0, try to insert before first node. Must not be negative.

pos - if nodeIndex points onto a CharacterData, then this parameter defines index of character in this CharacterData, where the point points. This value must not be less than zero.

DOMPoint

public DOMPoint(QName attrName,
                int pos)

Creates instance of the point, pointing onto an attribute.

Parameters:

attrName - this point points into attribute with this qname.

pos - this parameter defines index of character in this Attr, where the point points. This value must not be less than zero.

Method Detail

getLast

public static DOMPoint getLast(Element e)

Returns a point pointing after the last child node of e.

Parameters:

e - the element.

Returns:

last insertpoint.

valueOf

public static DOMPoint valueOf(Node node,
                               int pos)

Retrieves the DOM point pointing onto given node.

Parameters:

node - the node to point to.

pos - if the node is a CharacterData or Attr, then this parameter defines index of character in this CharacterData/Attr, where the point points. This value must not be less than zero.

Returns:

point.

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(Object obj)

Specified by:

compareTo in interface Comparable

isAttrPoint

public boolean isAttrPoint()

Checks if this point points into contents of an attribute

Returns:

true when attrName is not null.

isXmlnsAttrPoint

public boolean isXmlnsAttrPoint()

Checks if this point points into contents of an xmlns attribute

Returns:

true when attrName's QName.getNamespaceURI() is equal to .

toString

public String toString()

Converts insertpoint object to a string using syntax: [insertPlace,pos].

Overrides:

toString in class Object

valueOf

public static DOMPoint valueOf(String string)

Parses given string and returns an insert point instance.

Parameters:

string - string in form of [nodeIndex,pos]

Returns:

point instance represented by the string.

isValid

public boolean isValid(NodeList list,
                       boolean mustPointToNode,
                       boolean mayPointAfterLastChar)

Checks if this point is valid in the context of given node list. Valid point must point inside a range character boundary-point, to a node, or at the end of the nodelist.

Warning: this function is not able to validate attribute points marking them invalid.

Parameters:

list - children of the context element. May be null - in such case the method acts as if a zero-sized list has been passed.

mustPointToNode - if insertpoint is valid when it points to the end of the nodelist - if true then it must not point after last node.

mayPointAfterLastChar - if true then the point is valid even if it points after the last char in the character node.

Returns:

true if insert point is valid, false otherwise.

isValid

public boolean isValid(Node parent,
                       boolean mustPointToNode,
                       boolean mayPointAfterLastChar)

Checks if this point is valid in the context of given parent node. Valid point must point inside a range character boundary-point, to a node, or at the end of the nodelist.

Parameters:

parent - the parent node.

mustPointToNode - if insertpoint is valid when it points to the end of the nodelist - if true then it must not point after last node. Ignored when this point points onto an attribute.

mayPointAfterLastChar - if true then the point is valid even if it points after the last char in the character node.

Returns:

true if insert point is valid, false otherwise.

getNode

public Node getNode(Node parent)

Returns node that this points point on.

Parameters:

parent - the context node.

Returns:

the node. May return null if the point does not point onto a node.