Interface TreeInfo

  • All Known Implementing Classes:
    AxiomDocument, DocumentImpl, DocumentWrapper, DOM4JDocumentWrapper, DominoTree, FleetingDocumentNode, GenericTreeInfo, JDOM2DocumentWrapper, RebasedDocument, SpaceStrippedDocument, TinyTree, TypeStrippedDocument, VirtualTreeInfo, XOMDocumentWrapper

    public interface TreeInfo
    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.
    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      Configuration getConfiguration()
      Get the Configuration to which the nodes in this tree belong
      long getDocumentNumber()
      Get the document number, which identifies this tree uniquely within a Configuration.
      default Durability getDurability()
      Get the durability of nodes in the tree.
      NodeInfo getRootNode()
      Get the NodeInfo object representing the node at the root of the tree, which will often but not invariably be a document node
      SpaceStrippingRule getSpaceStrippingRule()
      Get details of space stripping action that was applied to this document during construction.
      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 that applies to this tree.
      default boolean isMutable()
      Ask whether the tree is mutable.
      default boolean isTyped()
      Ask whether the tree 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 setSpaceStrippingRule​(SpaceStrippingRule rule)
      Set details of space stripping action that was applied to this document during construction.
      void setUserData​(java.lang.String key, java.lang.Object value)
      Set user data that applies to this tree.
    • Method Detail

      • getRootNode

        NodeInfo getRootNode()
        Get the NodeInfo object representing the node at the root of the tree, which will often but not invariably be a document node
        Returns:
        the node at the root of the tree
      • getConfiguration

        Configuration getConfiguration()
        Get the Configuration to which the nodes in this tree belong
        Returns:
        the configuration
      • getDocumentNumber

        long getDocumentNumber()
        Get the document number, which identifies this tree uniquely within a Configuration. Document numbers are used when sorting nodes from different trees into document order.
        Returns:
        the document number
      • isTyped

        default boolean isTyped()
        Ask whether the tree contains any nodes whose type annotation is anything other than UNTYPED or UNTYPED_ATOMIC
        Returns:
        true if the tree contains elements or attributes whose type is other than UNTYPED or UNTYPED_ATOMIC. This is typically the case only if the document has been schema-validated (one can imagine an external tree model in which the type annotations arise some other way, but they must always be consistent with the typed value of the node).
      • isMutable

        default boolean isMutable()
        Ask whether the tree is mutable. A mutable tree can be modified (without changes to node identity) using XQuery Update primitives, or equivalents in other languages (such as Saxon XSLT extensions). "Mutable" here means mutable using XSLT/XQuery mechanisms, not using subversive lower-level mechanisms such as external DOM updates. To be mutable, it is necessary that its nodes implement the MutableNodeInfo interface; but this is not sufficient, because some tree implementations that support mutability interfaces may have optimizations for the case of non-mutability.
        Returns:
        true if the tree is mutable
      • 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
      • setSpaceStrippingRule

        void setSpaceStrippingRule​(SpaceStrippingRule rule)
        Set details of space stripping action that was applied to this document during construction. This ensures that space stripping is not applied twice to the same document.
        Parameters:
        rule - details of the space stripping rules that have been applied to this document during its construction.
        Since:
        9.9
      • getSpaceStrippingRule

        SpaceStrippingRule getSpaceStrippingRule()
        Get details of space stripping action that was applied to this document during construction. This ensures that space stripping is not applied twice to the same document.
        Returns:
        details of the space stripping rules that have been applied to this document during its construction. By default, returns NoElementsSpaceStrippingRule, indicating that no space stripping has been applied
        Since:
        9.9
      • setUserData

        void setUserData​(java.lang.String key,
                         java.lang.Object value)
        Set user data that applies to this tree. 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:".
        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 that applies to this tree. 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.
      • getDurability

        default Durability getDurability()
        Get the durability of nodes in the tree. This affects how they are handled in a memo function cache, to optimize memory and garbage collection. By default, all nodes are considered durable unless otherwise specified
        Returns:
        the durability property of this node tree