sk.uniba.euromath.document
Class IDManager

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

public final class IDManager
extends Object

Provides support for mapping between ID and nodes. The class relies mainly on value of the attribute Const.EM_ATTRIBUTE_ID, its internal list is used only for fast execution of getNode. Non-element nodes, such as text, cdata etc, are addressed by their parent element's id, thus they don't have ID themselves.

Every element has an ID: an integer number. Every non-element non-atribute node has two-part ID, split by a ;: first part is ID of their parent element, and second part is their position in this element (the numbering starts from 0). Warning: this numbering is consistent with the 'normalized document' (the document that is source for the transformation process) rather than the original document. Use the getID() function rather than computing the ID yourself. Every attribute has an ID split by @: first part is the ID of their owner element and second part is the prefixed name of the attribute.

If the node is a root node (the parent is the document) and it is not an element then the ID is in format ";[number]" - it does not have an ID of parent element.

Prior to each transformation the document is normalized: entity references are resolved and all adjacent text and cdata nodes are merged into one text node. Hence one text node can be backwards-identified as a set of 'adjacent' nodes (adjacent when the entity references are resolved). No ID may reference an entity reference node.

Nodes belonging to contents of EntityReference node are not modifiable however they do have an ID - if they contain namespace cross boundary then we need this ID for emp:mark element.

FOP requires that each ID is unique. However we may want to identify same element from different places. We must ensure that two different ID strings denote the same element. Hence, we define the ID structure as follows:

[parent-id]{; or @} position or attribute-name [:any_string]

where [] denotes the optional part and {} represents choice between two or more strings. No whitespaces are allowed. Two IDs are equal if and only if their parent-id are equal or both are missing and position or attribute-name are equal.

Author:

Martin Vysny

Constructor Summary

IDManager(DomCore document)
Constructs an IDManager instance bound to specified document.

Method Summary

String	addElement(Element element) Links given element with unique ID.
String	addElement(Element element, boolean fail) Links given element with unique ID.
String	addTree(Node node) Adds all element nodes in the descendant-or-self axis of given node to the id list.
String	addTree(Node node, boolean fail) Adds all element nodes in the descendant-or-self axis of given node to the id list.
boolean	areIdEqual(String id1, String id2) Tests if the two IDs denote the same nodeset.
static boolean	canHaveId(Node node) Checks if the node can have an id.
static boolean	canHaveId(short nodeType) Checks if the node can have an id.
void	checkNode(Node node) Checks if given node is from this document.
int	compareIds(String id1, String id2) Compares two IDs by their document order and returns result similar to Comparable.compareTo(Object) method.
String	getID(Node node) Gets ID value from the node.
static String	getIDNull(Node node) Gets ID value from the node.
NodeListID	getNode(String id) Gets node identified by ID.
NodeListID	getNodeNull(String id) Gets node identified by ID.
short	getNodeType(String id) Returns the type of node, denoted by given ID.
boolean	hasID(Element element) Examines if the node has ID (contains the emp:id attribute).
boolean	inEntity(String id) Checks if node with given ID is in an entity, therefore unmodifiable.
static boolean	isEmpId(Node node) Checks if given node is the emp:id attribute.
boolean	isValid(String id) Checks whether given ID is valid.
static boolean	isWellFormed(String id) Checks whether given ID is well-formed (but the presence of the node with this id in the document is not checked).
void	remove(Element element) Removes element from list.
(package private) void	remove(String id) Removes element with given id from our list.
(package private) static void	removeIdAttr(Element element) Removes the id attribute from the element.
void	removeTree(Node node) Removes all element nodes in the descendant-or-self axis of given node from the id list.
(package private) void	removeTreeIdOnly(Node node) Strips all element nodes in the descendant-or-self axis from the emp:id attribute but does not unregister them from the ID manager.
void	sortByDocumentOrder(List<String> list) Sorts list of IDs: node denoted by first ID precedes node denoted by second ID etc.

Methods inherited from class java.lang.Object

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

Constructor Detail

IDManager

IDManager(DomCore document)
    throws DocumentException

Constructs an IDManager instance bound to specified document. Instance created with reference to document will not accept nodes from another document. Upon creating, IDs for all elements are generated, except for elements, that are descendants of EntityReference nodes, because they are not modifiable.

Parameters:

document - the document.

Throws:

DocumentException - when some elements already contains emp:id.

Method Detail

addElement

public String addElement(Element element)

Links given element with unique ID. The node will be modified by inserting an emp:id attribute. If the node already has an id then its present id is returned instead.

Parameters:

element - Element, that has been added to the document.

Returns:

ID-value that has been assigned to node.

addElement

public String addElement(Element element,
                         boolean fail)
                  throws DocumentException

Links given element with unique ID. The node will be modified by inserting an emp:id attribute. If the node already has an id then its present id is returned instead.

Parameters:

element - Element, that has been added to the document.

fail - if true then the function will fail when element already has id.

Returns:

ID-value that has been assigned to node.

Throws:

DocumentException - if element already contains id.

checkNode

public void checkNode(Node node)

Checks if given node is from this document.

Parameters:

node - node to check

Throws:

IllegalArgumentException - if node is not from our document.

addTree

public String addTree(Node node)

Adds all element nodes in the descendant-or-self axis of given node to the id list. Function returns id of given node. Function shall fail only if the argument is null.

Parameters:

node - the root of the tree to register.

Returns:

an id of given node. It returns null only if the node is not an element and parent element has no id.

addTree

public String addTree(Node node,
                      boolean fail)
               throws DocumentException

Adds all element nodes in the descendant-or-self axis of given node to the id list. Function returns id of given node. Function shall fail only if the argument is null.

Parameters:

node - the root of the tree to register.

fail - if true then the function will fail when at least one element contains the emp:id attribute. In this case some elements may already have received an id.

Returns:

an id of given node. It returns null only if the node is not an element and parent element has no id.

Throws:

DocumentException - if an element already contains emp:id and fail is true.

remove

public void remove(Element element)

Removes element from list. If element does not have an id then nothing happens.

Parameters:

element - element, which is being removed from the manager.

removeIdAttr

static void removeIdAttr(Element element)

Removes the id attribute from the element. If element does not have the attribute then nothing happens.

Parameters:

element - element, which shall have emp:id attribute stripped.

removeTree

public void removeTree(Node node)

Removes all element nodes in the descendant-or-self axis of given node from the id list. Function shall fail only if the argument is null.

Parameters:

node - the root of the tree to remove from registry.

removeTreeIdOnly

void removeTreeIdOnly(Node node)

Strips all element nodes in the descendant-or-self axis from the emp:id attribute but does not unregister them from the ID manager. Useful when making clone of element etc.

Parameters:

node - the root of the tree.

remove

void remove(String id)

Removes element with given id from our list.

Parameters:

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

Throws:

AssertionError - if the id is not an element id.

canHaveId

public static boolean canHaveId(Node node)

Checks if the node can have an id. Only elements, attributes, text, cdata, processing instruction and comments can have an id.

Parameters:

node - the node to check

Returns:

true if the node can have id, false otherwise.

canHaveId

public static boolean canHaveId(short nodeType)

Checks if the node can have an id. Only elements, attributes, text, cdata, processing instruction and comments can have an id.

Parameters:

nodeType - the node type to check

Returns:

true if the node can have id, false otherwise.

isWellFormed

public static boolean isWellFormed(String id)

Checks whether given ID is well-formed (but the presence of the node with this id in the document is not checked).

Parameters:

id - the ID to check.

Returns:

true if the ID is well-formed, false otherwise.

isValid

public boolean isValid(String id)

Checks whether given ID is valid. It must be well-formed and it must be present in the document.

Parameters:

id - the ID to check.

Returns:

true if id is valid, false otherwise.

inEntity

public boolean inEntity(String id)
                 throws DocumentException

Checks if node with given ID is in an entity, therefore unmodifiable.

Parameters:

id - ID of the node

Returns:

true if the node is not modifiable, false if node is not in an entity (in case of element, PI, comment, attribute) or some text parts may be modifiable (in case of textual node).

Throws:

DocumentException - if id doesn't exist.

getNodeType

public short getNodeType(String id)
                  throws DocumentException

Returns the type of node, denoted by given ID. If the ID spans over multiple text/cdata nodes then the type of the first node is returned.

Parameters:

id - id of the node.

Returns:

one of the Node type constants.

Throws:

DocumentException - if given ID does not exist.

getIDNull

public static String getIDNull(Node node)

Gets ID value from the node. If specified node has no ID, function returns null. This method works also with nodes, which doesn't belong to our document. If the ID spans over multiple nodes then given node is amongst these nodes.

Parameters:

node - Element, whose ID has to be returned.

Returns:

Id of the node, or null if the node doesn't have an ID. It will not have the trailing third (:) part.

getID

public String getID(Node node)

Gets ID value from the node. If the specified node has no ID, function fails with IllegalStateException. It works with all types of nodes, even not from our document.

Parameters:

node - node, whose ID has to be returned.

Returns:

Id of the node.

areIdEqual

public boolean areIdEqual(String id1,
                          String id2)

Tests if the two IDs denote the same nodeset.

Parameters:

id1 - first ID

id2 - second ID

Returns:

true if the IDs are same.

getNode

public NodeListID getNode(String id)
                   throws DocumentException

Gets node identified by ID.

Parameters:

id - id of the desired node.

Returns:

nodelist, never null nor empty.

Throws:

DocumentException - if id doesn't exist.

getNodeNull

public NodeListID getNodeNull(String id)

Gets node identified by ID.

Parameters:

id - id of the desired node.

Returns:

non-null non-empty list of node, or null if the id is not valid.

hasID

public boolean hasID(Element element)

Examines if the node has ID (contains the emp:id attribute).

Parameters:

element - the element to be examined.

Returns:

true if node has ID.

isEmpId

public static boolean isEmpId(Node node)

Checks if given node is the emp:id attribute.

Parameters:

node - node to check.

Returns:

true if node is emp:id attribute, false otherwise.

compareIds

public int compareIds(String id1,
                      String id2)
               throws DocumentException

Compares two IDs by their document order and returns result similar to Comparable.compareTo(Object) method.

Parameters:

id1 - first ID

id2 - second ID

Returns:

-1 if node denoted by first id precedes node denoted by second id (as stated by the document ordering), 0 if two ids are equal as determined by the areIdEqual(String, String) method, or 1 if node denoted by first id follows node denoted by second id.

Throws:

DocumentException - if id doesn't exist.

sortByDocumentOrder

public void sortByDocumentOrder(List<String> list)

Sorts list of IDs: node denoted by first ID precedes node denoted by second ID etc.

Parameters:

list - list to sort.