net.sf.saxon.om

Interface TreeInfo

All Superinterfaces:

javax.xml.transform.Source

All Known Implementing Classes:

AxiomDocument, DocumentImpl, DocumentWrapper, DOM4JDocumentWrapper, DominoTree, FleetingDocumentNode, GenericTreeInfo, JDOM2DocumentWrapper, JDOMDocumentWrapper, Orphan, SpaceStrippedDocument, TextFragmentValue, TinyTree, TypeStrippedDocument, VirtualTreeInfo, XOMDocumentWrapper

public interface TreeInfo
extends javax.xml.transform.Source

This interface represents information about a tree as a whole. The tree may or may not be rooted at a document node. In some tree models, the interface is implemented by the object representing the root node of the tree (typically but not necessarily the document node). In other tree models, it is a free-standing object. The TreeInfo holds information that is common to all the nodes in a tree, such as the document number and a reference to the Configuration.

Java object identity for TreeInfo objects equates to XPath node identity for the root nodes of the relevant trees: that is, two root nodes are "the same node" if and only if their TreeInfo objects are the same Java object. However, when sorting into document order, the order of trees is based on their "document number", a unique number allocated by the document number allocator for the Configuration.

Since:

9.7. Replaces the DocumentInfo interface which represented both a document as a whole, and the document node at the root of a document, but which did not apply to trees rooted at a node other than a document node.

Author:

Michael H. Kay

Method Summary

Modifier and Type	Method and Description
Configuration	getConfiguration() Get the Configuration to which this document belongs
long	getDocumentNumber() Get the document number, which identifies this tree uniquely within a Configuration
NodeInfo	getRootNode() Get the NodeInfo object representing the document node at the root of the tree
java.lang.String[]	getUnparsedEntity(java.lang.String name) Get the unparsed entity with a given name
java.util.Iterator<java.lang.String>	getUnparsedEntityNames() Get the list of unparsed entities defined in this document
java.lang.Object	getUserData(java.lang.String key) Get user data held in the document node.
boolean	isTyped() Ask whether the document contains any nodes whose type annotation is anything other than UNTYPED or UNTYPED_ATOMIC
NodeInfo	selectID(java.lang.String id, boolean getParent) Get the element with a given ID, if any
void	setUserData(java.lang.String key, java.lang.Object value) Set user data on the document node.

Methods inherited from interface javax.xml.transform.Source

getSystemId, setSystemId

Method Detail

getRootNode

NodeInfo getRootNode()

Get the NodeInfo object representing the document node at the root of the tree

Returns:

the document node

getConfiguration

Configuration getConfiguration()

Get the Configuration to which this document belongs

Returns:

the configuration

getDocumentNumber

long getDocumentNumber()

Get the document number, which identifies this tree uniquely within a Configuration

Returns:

the document number

isTyped

boolean isTyped()

Ask whether the document contains any nodes whose type annotation is anything other than UNTYPED or UNTYPED_ATOMIC

Returns:

true if the document contains elements whose type is other than UNTYPED or UNTYPED_ATOMIC

selectID

NodeInfo selectID(java.lang.String id,
                  boolean getParent)

Get the element with a given ID, if any

Parameters:

id - the required ID value

getParent - true if running the element-with-id() function rather than the id() function; the difference is that in the case of an element of type xs:ID, the parent of the element should be returned, not the element itself.

Returns:

the element with the given ID, or null if there is no such ID present (or if the parser has not notified attributes as being of type ID)

Since:

8.4. Second argument added in 9.2.

getUnparsedEntityNames

java.util.Iterator<java.lang.String> getUnparsedEntityNames()

Get the list of unparsed entities defined in this document

Returns:

an Iterator, whose items are of type String, containing the names of all unparsed entities defined in this document. If there are no unparsed entities or if the information is not available then an empty iterator is returned

Since:

9.1

getUnparsedEntity

java.lang.String[] getUnparsedEntity(java.lang.String name)

Get the unparsed entity with a given name

Parameters:

name - the name of the entity

Returns:

if the entity exists, return an array of two Strings, the first holding the system ID of the entity (as an absolute URI if possible), the second holding the public ID if there is one, or null if not. If the entity does not exist, the method returns null. Applications should be written on the assumption that this array may be extended in the future to provide additional information.

Since:

8.4

setUserData

void setUserData(java.lang.String key,
                 java.lang.Object value)

Set user data on the document node. The user data can be retrieved subsequently using getUserData(java.lang.String)

Parameters:

key - A string giving the name of the property to be set. Clients are responsible for choosing a key that is likely to be unique. Must not be null. Keys used internally by Saxon are prefixed "saxon:".

The key saxon:document-uri may be used to set the document-uri property of the document node. If this is set to a non-empty string, the result of the document-uri() function on the document node will be that string, as an instance of xs:anyURI. If it is set to a zero-length string, the result of document-uri() will be the empty sequence, ().

value - The value to be set for the property. May be null, which effectively removes the existing value for the property.

getUserData

java.lang.Object getUserData(java.lang.String key)

Get user data held in the document node. This retrieves properties previously set using setUserData(java.lang.String, java.lang.Object)

Parameters:

key - A string giving the name of the property to be retrieved.

Returns:

the value of the property, or null if the property has not been defined.