Package com.documentum.fc.client

# Interface IDfVirtualDocumentNode

public interface IDfVirtualDocumentNode
This interface provides access to the nodes in a virtual document tree displayed in the Virtual Document Manager.

The term virtual document tree refers to the graphic display of a virtual document's component hierarchy in the Virtual Document Manager. Each component in the tree is called a node.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `areChildrenCompound()`
  Indicates whether users can add, remove, or reorder the children of this node through VDM.
  `void`
  `assemble(IDfSysObject object)`
  Creates an assembly for the node.
  `boolean`
  `canBeRemoved()`
  Indicates whether the node can be removed from its parent.
  `boolean`
  `canBeRestructured()`
  Indicates whether the node can be restructured.
  `boolean`
  `causesCycle()`
  Indicates whether the node's object ID matches that of any of its parents in the virtual document hierarchy.
  `void`
  `disassemble()`
  Disassembles an assembly.
  `boolean`
  `doesSelectedVersionMatchBinding()`
  Indicates whether the currently displayed node object matches the defined binding for the node.
  `IDfSysObject`
  `getAssemblyDocument()`
  Returns the document with which an assembly is associated.
  `String`
  `getAssemblyDocumentBinding()`
  Returns the binding value between the assembly's associated document and that document's parent document.
  `IDfVirtualDocumentNode`
  `getAssemblyParent()`
  Returns an IDfVirtualDocumentNode object for the root of the assembly that contains this node.
  `IDfVersionTreeLabels`
  `getAvailableVersions()`
  Returns a list of the version labels for the object represented by this node.
  `com.documentum.fc.common.IDfBasicAttributes`
  `getBasicAttributes()`
  `String`
  `getBinding()`
  Returns the version label used to resolve the binding for this node.
  `IDfVirtualDocumentNode`
  `getChild(int index)`
  Returns a given child node of this node.
  `int`
  `getChildCount()`
  Returns the number of immediate children for this node.
  `IDfId`
  `getChronId()`
  Returns the chronicle ID for the object represented by this node.
  `int`
  `getCopyBehavior()`
  Returns the copy behavior for the node.
  `boolean`
  `getFollowAssembly()`
  Returns the follow_assembly attribute setting for this node.
  `IDfId`
  `getId()`
  Returns a string that uniquely identifies this node in the virtual document tree.
  `String`
  `getLateBindingValue()`
  Returns the late binding value for the node.
  `String`
  `getNodeToken()`
  Returns a string representation of the virtual document node in a particular format.The format corresponds to the virtual document node's position with respect to the root.
  `boolean`
  `getOverrideLateBindingValue()`
  Returns the use_node_ver_label attribute value from the containment object associated with this node.
  `IDfVirtualDocumentNode`
  `getParent()`
  Returns the IDfVirtualDocumentNode object for the immediate parent of this node.
  `IDfProperties`
  `getProperties()`
  Returns an interface to the DfProperties object owned by this virtual document node.
  `IDfId`
  `getRelationshipId()`
  Returns the object ID of the containment or assembly object for this node.
  `IDfSysObject`
  `getSelectedObject()`
  Returns an IDfSysObject interface for the document represented by the node.
  `String`
  `getVDMNumber()`
  Returns the node's number in the virtual document tree.
  `IDfVirtualDocument`
  `getVirtualDocumentFromNode()`
  Returns the IDfVirtualDocument interface for the VDM window in which the virtual document containing this node appears.
  `boolean`
  `isBindingBroken()`
  Indicates whether there is a version in the node's version tree that matches the binding criteria.
  `boolean`
  `isCompound()`
  Indicates whether users can add to, remove, or reorder this node in the VDM display.
  `boolean`
  `isFromAssembly()`
  Indicates whether this node was selected from an assembly.
  `boolean`
  `isRoot()`
  Indicates whether the node is the root of the virtual document tree.
  `boolean`
  `isStructurallyModified()`
  Indicates whether the node is structurally modified or not.
  `boolean`
  `isVirtualDocument()`
  Indicates whether the node is a virtual document.
  `void`
  `resetSelectedVersionFromBinding()`
  Clears any temporary object selection and resets the node's selection based on its defined binding.
  `void`
  `setAssemblyDocumentBinding(String bindingValue)`
  Sets the binding between an assembly's associated document and that document's parent in the virtual document tree.
  `void`
  `setBinding(String newBinding)`
  Defines a new version label to use to resolve the binding for this node.
  `void`
  `setCopyBehavior(int behavior)`
  Sets the copy behavior for the node.
  `void`
  `setFollowAssembly(boolean followAssembly)`
  Directs the system to use the node's assembly in the display.
  `void`
  `setOverrideLateBindingValue(boolean override)`
  Sets the use_node_ver_label attribute for the node's associated containment object.
  `void`
  `setSelectedVersion(String theVersion)`
  Overrides the node's binding criteria and displays the specified version.

- ## Method Details

  - ### getId

    IDfId getId()
    Returns a string that uniquely identifies this node in the virtual document tree.

    Returns:
      An IDfId object containing the node identifier

  - ### getAssemblyParent

    IDfVirtualDocumentNode getAssemblyParent() throws DfException
    Returns an IDfVirtualDocumentNode object for the root of the assembly that contains this node.

    This method is only valid if the node was selected from an assembly. If the node was not selected from an assembly, use `getParent()` to obtain the parent node.

    Returns:
      An IDfVirtualDocumentNode object for the root node; `null` if this node is not from an assembly
    Throws:
      `DfException` - if the server returns an error
    See Also:
      - `getParent()`

  - ### getParent

    IDfVirtualDocumentNode getParent() throws DfException
    Returns the IDfVirtualDocumentNode object for the immediate parent of this node.

    This method returns `null` if this node is the root of the virtual document tree.

    Returns:
      An IDfVirtualDocumentNode object for the immediate parent of this node; `null` if this node is the root of the virtual document tree
    Throws:
      `DfException` - if the server returns an error
    See Also:
      - `getAssemblyParent()`

  - ### getChildCount

    int getChildCount() throws DfException
    Returns the number of immediate children for this node.

    The immediate children are those components that are directly contained by this node.

    Returns:
      The number of components this node directly contains
    Throws:
      `DfException` - if the server returns an error

  - ### getChild

    IDfVirtualDocumentNode getChild(int index) throws DfException
    Returns a given child node of this node.

    The child is identified by its index value. The index value represents the child node's position among its siblings. Index numbers begin with 0 and increment by 1 for each addition of a child node. To determine the total number of child nodes, use `getChildCount()`.
    Parameters:
      `index` - The index number of the child you want to obtain
    Returns:
      The IDfVirtualDocumentNode object corresponding to the specified index
    Throws:
      `DfException` - if the server returns an error

  - ### causesCycle

    boolean causesCycle() throws DfException
    Indicates whether the node's object ID matches that of any of its parents in the virtual document hierarchy.

    The server does not allow you to add a component to itself in the virtual document hierarchy, either directly or indirectly. If this method returns `true`, it indicates that you are trying to add the node to itself. The server will not allow you to save such a change.

    Returns:
      `true` if the object represented by this node occurs in this node's parent hierarchy; `false` if not
    Throws:
      `DfException` - if the server returns an error

  - ### isRoot

    boolean isRoot() throws DfException
    Indicates whether the node is the root of the virtual document tree.

    The root of the virtual document tree is the node at the top of the tree in the VDM window.

    Returns:
      `true` if the node is the root of the virtual document tree; `false` if not
    Throws:
      `DfException` - if the server returns an error

  - ### isCompound

    boolean isCompound() throws DfException
    Indicates whether users can add to, remove, or reorder this node in the VDM display.

    Virtual documents are sometimes created by other editing applications, such as OLE or SGML, and imported into the repository. When this occurs, the a_compound_architecture attribute of the parent document is set to indicate the source application of the document. The VDM can display these virtual documents, but users cannot use the VDM to add, remove, or reorder the nodes of the document. Any structural changes must be made within the context of the original application that created the document.

    This method returns `true` if there is any value other than `null` or empty for the a_compound_architecture attribute of the node's immediate parent.

    Returns:
      `true` if the a_compound_architecture attribute of the node's immediate parent is not null/empty; `false` if the attribute is null/empty. This method always returns `false` if the node is selected from an assembly.
    Throws:
      `DfException` - if the server returns an error

  - ### areChildrenCompound

    boolean areChildrenCompound() throws DfException
    Indicates whether users can add, remove, or reorder the children of this node through VDM.

    Virtual documents are sometimes created by other editing applications, such as OLE or SGML, and imported into the repository. When this occurs, the a_compound_architecture attribute of the parent document is set to indicate the source application of the document. The VDM can display these virtual documents, but users cannot use the VDM to add, remove, or reorder the nodes of the document. Any structural changes must be made within the context of the original application that created the document.

    This method returns `true` if there is any value other than `null` or empty in the a_compound_architecture attribute for the object represented by this node.

    Returns:
      `true` if the a_compound_architecture attribute for this node is not null/empty; `false` if it is null/empty. This method always returns `false` if the node is selected from an assembly.
    Throws:
      `DfException` - if the server returns an error

  - ### isVirtualDocument

    boolean isVirtualDocument() throws DfException
    Indicates whether the node is a virtual document.

    Virtual document nodes can be other virtual documents, simple documents, or selected from an assembly. A document is a virtual document if its r_is_virtual_document attribute is true or if its r_link_cnt attribute is greater than 0.

    Returns:
      `true` if node is a virtual document; `false` if not
    Throws:
      `DfException` - if the server returns an error

  - ### canBeRestructured

    boolean canBeRestructured() throws DfException
    Indicates whether the node can be restructured.

    A virtual document node can be restructured if the node is either a non-compound document or if the document is a compound document and it was marked as editable in the application configuration file.

    Returns:
      `true` if the node can be restructured; `false` if not
    Throws:
      `DfException` - if the server returns an error

  - ### canBeRemoved

    boolean canBeRemoved() throws DfException
    Indicates whether the node can be removed from its parent.

    Virtual document node can be removed.

    Returns:
      `true` if node can be removed, otherwise `false`
    Throws:
      `DfException` - if the server returns an error

  - ### isStructurallyModified

    boolean isStructurallyModified() throws DfException
    Indicates whether the node is structurally modified or not.

    Virtual document node can be removed.

    Returns:
      `true` if node can be remuved, otherwise `false`
    Throws:
      `DfException` - if the server returns an error

  - ### getCopyBehavior

    int getCopyBehavior() throws DfException
    Returns the copy behavior for the node.

    If the node is a virtual document, the copy behavior defines how its descendant children are handled when the document is copied.

    Returns:
      An integer corresponding to the copy behavior. Valid values and their meanings are:

           Value    Meaning
           0        User chooses copy behavior at runtime
           1        Server creates pointers to the children
           2        Server makes a new copy of the children

    Throws:
      `DfException` - if the server returns an error

  - ### setCopyBehavior

    void setCopyBehavior(int behavior) throws DfException
    Sets the copy behavior for the node.

    This method is only valid for nodes that are virtual documents. To use this method, the node's parent must be checked out. The copy behavior for a virtual document defines how the server handles the document's descendants when the document is copied.

    When the virtual document is copied, the server can either make new copies of the descendants or create internal pointers to the descendants.

    Parameters:
      `behavior` - Set this to the integer that defines the copy behavior. Valid values and their meanings are:

           Value    Meaning
           0        User makes the choice between copy or pointer at runtime
           1        Server creates pointers to the children
           2        Server makes a new copy of the children

    Throws:
      `DfException` - if the server returns an error

  - ### getChronId

    IDfId getChronId() throws DfException
    Returns the chronicle ID for the object represented by this node.

    The chronicle ID is the object ID of the first version of an object.

    Returns:
      An IDfId object that contains the object's chronicle ID
    Throws:
      `DfException` - if the server returns an error

  - ### getBinding

    String getBinding() throws DfException
    Returns the version label used to resolve the binding for this node.

    If the node is early-bound to the virtual document, the version label can be a symbolic or implicit value. If the node is late-bound or is the root node, this returns a null reference. If the node is selected from an assembly, this returns an implicit version label.

    Returns:
      The binding version label string
    Throws:
      `DfException` - if the server returns an error

  - ### setBinding

    void setBinding(String newBinding) throws DfException
    Defines a new version label to use to resolve the binding for this node.

    To use this method, the node's parent must be checked out. To early bind the component to its parent, specify an implicit or symbolic version label. To late bind the node to the parent, specify `null` in `newBinding`.

    You cannot use late binding for assembly nodes.

    Parameters:
      `newBinding` - Set this to an implicit or symbolic version label for early binding or to `null` for late binding.
    Throws:
      `DfException` - if the server returns an error

  - ### isBindingBroken

    boolean isBindingBroken() throws DfException
    Indicates whether there is a version in the node's version tree that matches the binding criteria.

    Users can change the binding criteria through the user interface. If they do so, it might create a node with broken bindings. The term broken bindings means that there is no version of the object represented by the node that matches the binding criteria.

    This method always returns `false` for the root node of the virtual document tree.

    Returns:
      `true` if no version matches the binding criteria; `false` if there is a matching version or if this is the root node
    Throws:
      `DfException` - if the server returns an error

  - ### doesSelectedVersionMatchBinding

    boolean doesSelectedVersionMatchBinding() throws DfException
    Indicates whether the currently displayed node object matches the defined binding for the node.

    Users can change the object displayed for any given node. This method determines whether the object currently displayed for a node matches the binding defined for the node.

    Returns:
      `true` if the currently displayed object matches the defined binding for the node; `false` if not. Always returns true for the root node.
    Throws:
      `DfException` - if the server returns an error

  - ### getSelectedObject

    IDfSysObject getSelectedObject() throws DfException
    Returns an IDfSysObject interface for the document represented by the node.

    The returned interface represents the displayed version of the document. (This can differ from the version defined by the binding criteria.)

    Returns:
      An IDfSysObject interface for the displayed version of the document represented by this node
    Throws:
      `DfException` - if the server returns an error

  - ### setSelectedVersion

    void setSelectedVersion(String theVersion) throws DfException
    Overrides the node's binding criteria and displays the specified version.

    Changes made to the node's display using this method are not saved to the repository. They exist only while the containing VDM window is open.

    Specifying a version label that is not found in the object's version tree results in a broken binding. The system will attempt to resolve a broken binding if the `IDfVirtualDocument.setIncludeBrokenBindings(boolean)` flag is set to `true`. If that flag is `false`, the system will not display the node.

    Parameters:
      `theVersion` - Defines the version label of the version you want to display
    Throws:
      `DfException` - if the server returns an error

  - ### resetSelectedVersionFromBinding

    void resetSelectedVersionFromBinding() throws DfException
    Clears any temporary object selection and resets the node's selection based on its defined binding.

    Use this method to remove from the display any temporary version selected using `setSelectedVersion(java.lang.String)` and redisplay the version defined by the node's binding criteria.

    Throws:
      `DfException` - if the server returns an error

  - ### isFromAssembly

    boolean isFromAssembly() throws DfException
    Indicates whether this node was selected from an assembly.

    Returns:
      `true` if the node is from an assembly; `false` if not
    Throws:
      `DfException` - if the server returns an error

  - ### setFollowAssembly

    void setFollowAssembly(boolean followAssembly) throws DfException
    Directs the system to use the node's assembly in the display.

    To use this method, the node's parent must be checked out.

    If this flag is set to `true`, the system uses the node's assembly to display the node and its descendants. The virtual document represented by the assembly replaces the node and the assembly components are used to select the node's children. This change is not stored persistently for the root node.

    If the node has no associated assembly or if the node is an assembly node, the follow assembly setting is ignored.

    An assembly is a snap shot of a virtual document at a given point in time. For more information about assemblies and their structure, refer to Server Fundamentals.

    Parameters:
      `followAssembly` - Set this to `true` if you want to display the assembly associated with a node. Set it to `false` to select the descendants from the node's actual children.
    Throws:
      `DfException` - if the server returns an error

  - ### getFollowAssembly

    boolean getFollowAssembly() throws DfException
    Returns the follow_assembly attribute setting for this node.

    The follow_assembly attribute determines whether the system chooses the node and its descendants for display from the node's containment objects or from an associated assembly.

    For more information about the follow_assembly attribute, refer to Server Fundamentals.

    Returns:
      `true`, meaning that the node display is chosen from an assembly; `false` if not.
    Throws:
      `DfException` - if the server returns an error

  - ### getOverrideLateBindingValue

    boolean getOverrideLateBindingValue() throws DfException
    Returns the use_node_ver_label attribute value from the containment object associated with this node.

    This attribute value is only important if the node is early bound to the virtual document and is itself a virtual document. In such cases, the use_node_ver_label attribute value determines whether the system uses the node's early-bound version label to select the node's late-bound children.

    For more information about this attribute, refer to the Server Fundamentals.

    Returns:
      `true` if the system can use the node's early bound version label to select its late-bound children; `false` if not. The return value is always `false` for assembly nodes and the root node.
    Throws:
      `DfException` - if the server returns an error

  - ### setOverrideLateBindingValue

    void setOverrideLateBindingValue(boolean override) throws DfException
    Sets the use_node_ver_label attribute for the node's associated containment object.

    This attribute's value is only important if the node is early bound to the virtual document and is itself a virtual document. In such cases, the use_node_ver_label attribute value determines whether the system uses the node's early-bound version label to select the node's late-bound children.

    This method has no effect if the node is an assembly node or a root node, or is late bound to the virtual document.

    Parameters:
      `override` - Set this to `true` if you want to use the node's early-bound label to resolve its late-bound children. Set it to `false` if not.
    Throws:
      `DfException` - if the server returns an error

  - ### getLateBindingValue

    String getLateBindingValue() throws DfException
    Returns the late binding value for the node.

    This method is only valid for late-bound nodes. The method searches up the node's hierarchy to find the first early-bound parent node for which use_node_ver_label is true. When it finds that node, the method returns the node's early-bound version label as this node's late-binding version label. The search on the node hierarchy begins with this node's direct parent. If that node doesn't meet the conditions, then the search progresses to the parent node's parent, and so on up the node hierachy until a late-binding value is found.

    If this is the root node, the late-binding value from the IDfVirtualDocument is returned.

    Returns:
      The late-binding version label to use to for this node.
    Throws:
      `DfException` - if the server returns an error

  - ### getAvailableVersions

    IDfVersionTreeLabels getAvailableVersions() throws DfException
    Returns a list of the version labels for the object represented by this node.

    Every SysObject has one implicit version label and can also have one or more symbolic labels. For more information about version labels, refer to Server Fundamentals.

    Returns:
      An IDfVersionLabelList object that contains the version labels for the object represented by this node
    Throws:
      `DfException` - if the server returns an error

  - ### getRelationshipId

    IDfId getRelationshipId() throws DfException
    Returns the object ID of the containment or assembly object for this node.

    If the node was selected from containment objects, this method returns the object ID of the containment object associated with this node. If the node was selected from an assembly, this method returns the object ID of the assembly object associated with this node.

    For more information about containment and assembly objects, refer to Server Fundamentals.

    Returns:
      An IDfId object that contains the object ID
    Throws:
      `DfException` - if the server returns an error

  - ### assemble

    void assemble(IDfSysObject object) throws DfException
    Creates an assembly for the node.

    The node must be a virtual document. The assembly contains all the children of the node, direct and indirect. The assembly is associated with the document identified in the `object` paramter.

    An implicit transaction is opened during this method call. You cannot call this method in a transaction. For more information about assemblies, refer to Server Fundamentals.

    Parameters:
      `object` - An IDfSysObject object representing the document with which you want to associate the assembly. This object can be the object represented by this node or a different object.
    Throws:
      `DfException` - if the server returns an error

  - ### disassemble

    void disassemble() throws DfException
    Disassembles an assembly.

    This method is only valid for nodes that have an associated assembly. Disassembling an assembly removes from the repository all the assembly objects that make up the assembly.

    For more information about assemblies, refer to Server Fundamentals.

    Throws:
      `DfException` - if the server returns an error

  - ### getVDMNumber

    String getVDMNumber() throws DfException
    Returns the node's number in the virtual document tree.

    Each node in a virtual document tree is assigned a number that indicates its position in the tree.

    Returns:
      The node's number in the virtual document tree
    Throws:
      `DfException` - if the server returns an error

  - ### getAssemblyDocument

    IDfSysObject getAssemblyDocument() throws DfException
    Returns the document with which an assembly is associated.

    This method is valid only for nodes that were selected from an assembly. It returns an IDfSysObject object representing the document with which the assembly that contains this node is associated.

    Returns:
      An IDfSysObject object for the document
    Throws:
      `DfException` - if the server returns an error

  - ### getAssemblyDocumentBinding

    String getAssemblyDocumentBinding() throws DfException
    Returns the binding value between the assembly's associated document and that document's parent document.

    This method is only valid if the node is selected from an assembly.

    An assembly is group of assembly objects that represent a snapshot of a virtual document. When an assembly is created, it is associated with a SysObject. If a SysObject with an associated assembly is part of a virtual document tree, you can choose to display the node and any descendants by selecting them from the assembly.

    If the node is selected from an assembly, this method returns the value that binds the SysObject with which the assembly is associated to the SysObject's parent in the tree.

    Returns:
      The binding value
    Throws:
      `DfException` - if the server returns an error
    See Also:
      - `getAssemblyDocument()`
      - `setFollowAssembly(boolean)`

  - ### setAssemblyDocumentBinding

    void setAssemblyDocumentBinding(String bindingValue) throws DfException
    Sets the binding between an assembly's associated document and that document's parent in the virtual document tree.

    This method is only valid if the node is selected from an assembly.

    An assembly is group of assembly object objects that represent a snapshot of a virtual document. When an assembly is created, it is associated with a SysObject. If a SysObject with an associated assembly is part of a virtual document tree, you can choose to display the node and any descendants by selecting them from the assembly.

    If the node is selected from an assembly, this method sets the value that binds the SysObject with which the assembly is associated to the SysObject's parent in the tree.

    Parameters:
      `bindingValue` - The binding value
    Throws:
      `DfException` - if the server returns an error

  - ### getVirtualDocumentFromNode

    IDfVirtualDocument getVirtualDocumentFromNode()
    Returns the IDfVirtualDocument interface for the VDM window in which the virtual document containing this node appears.

    Each open VDM window corresponds to an IDfVirtualDocument interface. Nodes are uniquely identified across all open VDM windows. Consequently, you can use this method to return the IDfVirtualDocument interface for the VDM window that contains this node.

    Returns:
      An IDfVirtualDocument interface for the containing VDM window

  - ### getNodeToken

    String getNodeToken() throws DfException
    Returns a string representation of the virtual document node in a particular format.The format corresponds to the virtual document node's position with respect to the root.
    Returns:
      A string representation of the virtual document node
    Throws:
      `DfException` - if the server returns an error

  - ### getProperties

    IDfProperties getProperties() throws DfException
    Returns an interface to the DfProperties object owned by this virtual document node. This can be used to set and get application-specific properties for this object.
    Returns:
      An IDfProperties object associated with this virtual document node.
    Throws:
      `DfException`

  - ### getBasicAttributes

    com.documentum.fc.common.IDfBasicAttributes getBasicAttributes() throws DfException
    Throws:
      `DfException`