Class GTreeNode

  • All Implemented Interfaces:
    java.lang.Cloneable, java.lang.Comparable<GTreeNode>
    Direct Known Subclasses:
    DomainFileNode, GTreeLazyNode, InProgressGTreeNode, InProgressGTreeRootNode, NoProjectNode

    public abstract class GTreeNode
    extends java.lang.Object
    implements java.lang.Comparable<GTreeNode>
    Base implementation for GTree nodes. Direct subclasses of this class are expected to have all their children in hand when initially constructed (either in their constructor or externally using addNode(GTreeNode) or setChildren(List). For large trees, subclasses should instead extend GTreeLazyNode or GTreeSlowLoadingNode

    All methods in this class that mutate the children node must perform that operation in the swing thread.

    To create a simple GTreeNode where nodes will be added immediately using the addNode() methods, simply extend this class and implement the following methods:

    • getName()
    • getToolTip()
    • isLeaf()
    • getIcon()
    Usage Notes:
    • The equals() method: The GTree has the ability to remember expanded and selected states. This will only work if the nodes in the saved state can be matched with the nodes in the GTree. Java will do this by using the equals() method. There is a potential problem with this usage. If nodes within the GTree get rebuilt ( i.e., new nodes are created), then, by default, the expanded and selected state feature will be unable to find the correct nodes, since the default equals() method on GTreeNode performs a comparison based upon instances. To fix this problem, the equals(Object) method has been implemented such that nodes are considered equal if they have the same name (see getName()). The hashCode() method will return the hash of the name. The name attribute was chosen because it should be the most unique and descriptive piece of information available in a generic GTreeNode.


      There are two situations where the equals(Object) and hashCode() using the name are insufficient. One is if your tree implementation allows nodes with the same name with the same parent. The other possible situation is if your nodes can change their name, which may confuse the tree. If either of these situations apply, just override the equals(Object) and hashCode() methods to make them more robust.


    • Constructor Summary

      Constructors 
      Constructor Description
      GTreeNode()  
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void addNode​(int index, GTreeNode node)
      Adds the given node at the given index as a child to this node
      void addNode​(GTreeNode node)
      Adds the given node as a child to this node.
      void addNodes​(java.util.List<GTreeNode> nodes)
      Adds the given nodes as children to this node
      protected java.util.List<GTreeNode> children()  
      GTreeNode clone()
      Creates a clone of this node.
      void collapse()
      Convenience method for collapsing (closing) this node in the tree.
      int compareTo​(GTreeNode node)  
      void dispose()  
      protected void doAddNode​(int index, GTreeNode node)
      Adds a node to this node's children at the given index and notifies the tree.
      protected void doAddNode​(GTreeNode node)
      Adds a node to this node's children.
      protected void doAddNodes​(java.util.List<GTreeNode> nodes)
      Adds the given nodes to this node's children.
      protected void doFireNodeAdded​(GTreeNode newNode)  
      protected void doFireNodeChanged()  
      protected void doFireNodeRemoved​(GTreeNode removedNode, int index)  
      protected void doFireNodeStructureChanged()  
      protected void doRemoveNode​(GTreeNode node)
      Removes the node from this node's children and notifies the tree.
      protected void doSetChildren​(java.util.List<GTreeNode> childList)
      Sets the children of this node to the given list of child nodes, but does not notify the tree.
      protected void doSetChildrenAndFireEvent​(java.util.List<GTreeNode> childList)
      Sets the children of this node to the given list of child nodes and fires the appropriate tree event to kick the tree to update the display.
      boolean equals​(java.lang.Object obj)  
      void expand()
      Convenience method for expanding (opening) this node in the tree.
      GTreeNode filter​(GTreeFilter filter, TaskMonitor monitor)
      Generates a filtered copy of this node and its children.
      void fireNodeChanged​(GTreeNode parentNode, GTreeNode node)
      Notifies the tree that a node has changed
      void fireNodeStructureChanged​(GTreeNode node)
      Notifies the tree that the node has different children.
      protected java.util.List<GTreeNode> generateChildren()
      Subclasses implement this method to initially load the children.
      GTreeNode getChild​(int index)
      Returns the child node at the given index.
      GTreeNode getChild​(java.lang.String name)
      Returns the child node of this node with the given name.
      int getChildCount()
      Returns the number of visible children of this node.
      java.util.List<GTreeNode> getChildren()
      Returns all of the visible children of this node.
      java.lang.String getDisplayText()
      Returns the display text for the node.
      abstract javax.swing.Icon getIcon​(boolean expanded)
      Returns the Icon to be displayed for this node in the tree
      int getIndexInParent()
      Returns the index of this node within its parent node
      int getIndexOfChild​(GTreeNode node)
      Returns the index of the given node within this node.
      int getLeafCount()
      Returns the total number of leaf nodes in the subtree from this node.
      abstract java.lang.String getName()
      Returns the name of the node.
      int getNodeCount()
      Returns the total number of nodes in the subtree rooted at this node.
      GTreeNode getParent()
      Returns the parent of this node.
      GTreeNode getRoot()
      Returns the rootNode for this tree or null if there is no parent path to a root node.
      abstract java.lang.String getToolTip()
      Returns the string to be displayed as a tooltip when the user hovers the mouse on this node in the tree
      GTree getTree()
      Returns the GTree that this node is attached to
      javax.swing.tree.TreePath getTreePath()
      Returns the TreePath for this node
      int hashCode()  
      boolean isAncestor​(GTreeNode node)
      Returns true if the given node is a child of this node or one of its children.
      boolean isEditable()
      Returns true if this node is allowed to be edited in the tree.
      boolean isExpanded()
      Convenience method determining if this node is expanded in a tree.
      boolean isInProgress()
      Returns true if the node is in the process of loading its children.
      abstract boolean isLeaf()
      Returns true if this node never has children
      boolean isLoaded()
      True if the children for this node have been loaded yet.
      boolean isRoot()
      Returns true if this is a root node of a GTree
      java.util.Iterator<GTreeNode> iterator​(boolean depthFirst)
      Returns an iterator of the GTree nodes in the subtree of this node
      int loadAll​(TaskMonitor monitor)
      Causes any lazy or slow loading nodes in the tree to load their children so that the tree is fully loaded.
      void removeAll()
      Removes all children from this node.
      void removeNode​(GTreeNode node)
      Remove the given node from this node
      void setChildren​(java.util.List<GTreeNode> childList)
      Sets the children on this node.
      java.util.stream.Stream<GTreeNode> stream​(boolean depthFirst)
      Returns a stream of the GTree nodes in the subtree of this node
      java.lang.String toString()  
      void valueChanged​(java.lang.Object newValue)
      Notification method called when a cell editor completes editing to notify this node that its value has changed.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • GTreeNode

        public GTreeNode()
    • Method Detail

      • generateChildren

        protected java.util.List<GTreeNode> generateChildren()
        Subclasses implement this method to initially load the children.
        Returns:
        a list of the initial children for this node.
      • getDisplayText

        public java.lang.String getDisplayText()
        Returns the display text for the node. By default, this is the same as the name of the node. The name of the node usually serves two purposes: 1) to uniquely identify the node (the identity) and 2) the display text (what you see in the tree). Sometimes, it is useful to display more information in the tree without affecting the nodes identity. In this case, you can override this method to return the "display" name, while getName() will still return the name used to identify the node.
        Returns:
        the display text for the node.
      • getName

        public abstract java.lang.String getName()
        Returns the name of the node. If getDisplayText() is not overridden, then this is also the text that will be displayed in the tree for that node. In general, the name of a node should not change. If the text displayed in the tree changes over time, override getDisplayText().
        Returns:
        the name of the node
      • getIcon

        public abstract javax.swing.Icon getIcon​(boolean expanded)
        Returns the Icon to be displayed for this node in the tree
        Parameters:
        expanded - true if the node is expanded
        Returns:
        the icon to be displayed for this node in the tree
      • getToolTip

        public abstract java.lang.String getToolTip()
        Returns the string to be displayed as a tooltip when the user hovers the mouse on this node in the tree
        Returns:
        the tooltip to be displayed
      • isLeaf

        public abstract boolean isLeaf()
        Returns true if this node never has children
        Returns:
        true if this node is a leaf
      • compareTo

        public int compareTo​(GTreeNode node)
        Specified by:
        compareTo in interface java.lang.Comparable<GTreeNode>
      • addNode

        public void addNode​(GTreeNode node)
        Adds the given node as a child to this node. Note: this method may be inefficient so if you have many nodes to add, you should use either addNodes(List) or setChildren(List)
        Parameters:
        node - the node to add as a child
      • addNodes

        public void addNodes​(java.util.List<GTreeNode> nodes)
        Adds the given nodes as children to this node
        Parameters:
        nodes - the nodes to add
      • addNode

        public void addNode​(int index,
                            GTreeNode node)
        Adds the given node at the given index as a child to this node
        Parameters:
        index - the index to place the node
        node - the node to add as a child of this node
      • getChildren

        public java.util.List<GTreeNode> getChildren()
        Returns all of the visible children of this node. If there are filtered nodes, then they will not be returned.
        Returns:
        all of the visible children of this node. If there are filtered nodes, then they will not be returned.
      • getChildCount

        public int getChildCount()
        Returns the number of visible children of this node. Does not include nodes that are current filtered out
        Returns:
        the number of visible children of this node
      • getChild

        public GTreeNode getChild​(java.lang.String name)
        Returns the child node of this node with the given name.
        Parameters:
        name - the name of the child to be returned
        Returns:
        the child with the given name
      • getChild

        public GTreeNode getChild​(int index)
        Returns the child node at the given index. Returns null if the index is out of bounds.
        Parameters:
        index - the index of the child to be returned
        Returns:
        the child at the given index
      • getNodeCount

        public int getNodeCount()
        Returns the total number of nodes in the subtree rooted at this node. Leaf nodes return 1.
        Returns:
        the number of nodes from this node downward
      • getLeafCount

        public int getLeafCount()
        Returns the total number of leaf nodes in the subtree from this node. Note that if any nodes are "lazy" (see GTreeLazyNode) and not currently loaded, then it will be considered as a leaf and return 1.
        Returns:
        the total number of leaf nodes in the subtree from this node
      • getIndexInParent

        public int getIndexInParent()
        Returns the index of this node within its parent node
        Returns:
        the index of this node within its parent node
      • getIndexOfChild

        public int getIndexOfChild​(GTreeNode node)
        Returns the index of the given node within this node. -1 is returned if the node is not a child of this node.
        Parameters:
        node - whose index we want
        Returns:
        the index of the given node within this node
      • getTreePath

        public javax.swing.tree.TreePath getTreePath()
        Returns the TreePath for this node
        Returns:
        the TreePath for this node
      • removeAll

        public void removeAll()
        Removes all children from this node. The children nodes will be disposed.
      • removeNode

        public void removeNode​(GTreeNode node)
        Remove the given node from this node
        Parameters:
        node - the to be removed
      • setChildren

        public void setChildren​(java.util.List<GTreeNode> childList)
        Sets the children on this node. Any existing current children will be dispose.
        Parameters:
        childList - this list of nodes to be set as children of this node
      • isAncestor

        public boolean isAncestor​(GTreeNode node)
        Returns true if the given node is a child of this node or one of its children.
        Parameters:
        node - the potential descendant node to check
        Returns:
        true if the given node is a child of this node or one of its children
      • valueChanged

        public void valueChanged​(java.lang.Object newValue)
        Notification method called when a cell editor completes editing to notify this node that its value has changed. If you override this method you must also override isEditable().
        Parameters:
        newValue - the new value provided by the cell editor
        See Also:
        isEditable()
      • isEditable

        public boolean isEditable()
        Returns true if this node is allowed to be edited in the tree. You must override this method to allow a node to be edited. You must also override valueChanged(Object) to handle the result of the edit.
        Returns:
        true if this node is allowed to be edited in the tree
        See Also:
        valueChanged(Object)
      • getRoot

        public GTreeNode getRoot()
        Returns the rootNode for this tree or null if there is no parent path to a root node.
        Returns:
        the rootNode for a tree of nodes in a GTree
      • filter

        public GTreeNode filter​(GTreeFilter filter,
                                TaskMonitor monitor)
                         throws CancelledException,
                                java.lang.CloneNotSupportedException
        Generates a filtered copy of this node and its children.

        A node will be included if it or any of its descendants are accepted by the filter. NOTE: the filter will only be applied to a nodes children if they are loaded. So to perform a filter on all the nodes in the tree, the loadAll(TaskMonitor) should be called before the filter call.

        Parameters:
        filter - the filter being applied
        monitor - a TaskMonitor for tracking the progress and cancelling
        Returns:
        A copy of this node and its children that matches the filter or null if this node and none of its children match the filter.
        Throws:
        CancelledException - if the operation is cancelled via the TaskMonitor
        java.lang.CloneNotSupportedException - if any nodes in the tree explicitly prevents cloning
      • loadAll

        public int loadAll​(TaskMonitor monitor)
                    throws CancelledException
        Causes any lazy or slow loading nodes in the tree to load their children so that the tree is fully loaded. Nodes that are already loaded (including normal nodes which are always loaded) do nothing except recursively call loadAll(TaskMonitor) on their children.
        Parameters:
        monitor - the TaskMonitor to monitor progress and provide cancel checking
        Returns:
        the total number of nodes in the subtree of this node
        Throws:
        CancelledException - if the operation is cancelled using the monitor
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object
      • stream

        public java.util.stream.Stream<GTreeNode> stream​(boolean depthFirst)
        Returns a stream of the GTree nodes in the subtree of this node
        Parameters:
        depthFirst - if true, the nodes will be streamed in depth-first order, otherwise breadth-first order
        Returns:
        a stream of the GTree nodes in the subtree of this node
      • iterator

        public java.util.Iterator<GTreeNode> iterator​(boolean depthFirst)
        Returns an iterator of the GTree nodes in the subtree of this node
        Parameters:
        depthFirst - if true, the nodes will be returned in depth-first order, otherwise breadth-first order
        Returns:
        an iterator of the GTree nodes in the subtree of this node
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • fireNodeStructureChanged

        public void fireNodeStructureChanged​(GTreeNode node)
        Notifies the tree that the node has different children. This method
        Parameters:
        node - the node that has changed.
      • fireNodeChanged

        public void fireNodeChanged​(GTreeNode parentNode,
                                    GTreeNode node)
        Notifies the tree that a node has changed
        Parameters:
        parentNode - the node that contains the node that was changed
        node - the that changed
      • expand

        public void expand()
        Convenience method for expanding (opening) this node in the tree. If this node is not currently attached to a visible tree, then this call does nothing
      • collapse

        public void collapse()
        Convenience method for collapsing (closing) this node in the tree. If this node is not currently attached to a visible tree, then this call does nothing
      • isExpanded

        public boolean isExpanded()
        Convenience method determining if this node is expanded in a tree. If the node is not currently attached to a visible tree, then this call returns false
        Returns:
        true if the node is expanded in a currently visible tree.
      • getParent

        public final GTreeNode getParent()
        Returns the parent of this node. Note: this method is deliberately not synchronized (See comments above)
        Returns:
        the parent of this node.
      • isRoot

        public final boolean isRoot()
        Returns true if this is a root node of a GTree
        Returns:
        true if this is a root node of a GTree
      • children

        protected final java.util.List<GTreeNode> children()
      • doSetChildrenAndFireEvent

        protected void doSetChildrenAndFireEvent​(java.util.List<GTreeNode> childList)
        Sets the children of this node to the given list of child nodes and fires the appropriate tree event to kick the tree to update the display. Note: This method must be called from the swing thread because it will notify the underlying JTree.
        Parameters:
        childList - the list of child nodes to assign as children to this node
        See Also:
        if calling from a background thread.
      • doSetChildren

        protected void doSetChildren​(java.util.List<GTreeNode> childList)
        Sets the children of this node to the given list of child nodes, but does not notify the tree. This method does not have to be called from the swing thread. It is intended to be used by background threads that want to populate all or part of the tree, but wait until the bulk operations are completed before notifying the tree.
        Parameters:
        childList - the list of child nodes to assign as children to this node
      • doAddNode

        protected void doAddNode​(GTreeNode node)
        Adds a node to this node's children. Must be called from the swing thread.
        Parameters:
        node - the node to add as a child to this node
      • doAddNode

        protected void doAddNode​(int index,
                                 GTreeNode node)
        Adds a node to this node's children at the given index and notifies the tree. Must be called from the swing thread.
        Parameters:
        index - the index at which to add the new node
        node - the node to add as a child to this node
      • doRemoveNode

        protected void doRemoveNode​(GTreeNode node)
        Removes the node from this node's children and notifies the tree. Must be called from the swing thread.
        Parameters:
        node - the node to remove
      • doAddNodes

        protected void doAddNodes​(java.util.List<GTreeNode> nodes)
        Adds the given nodes to this node's children. Must be called from the swing thread.
        Parameters:
        nodes - the nodes to add to the children this node
      • clone

        public GTreeNode clone()
                        throws java.lang.CloneNotSupportedException
        Creates a clone of this node. The clone should contain a shallow copy of all the node's attributes except that the parent and children are null.
        Overrides:
        clone in class java.lang.Object
        Returns:
        the clone of this object.
        Throws:
        java.lang.CloneNotSupportedException - if some implementation prevents itself from being cloned.
      • dispose

        public void dispose()
      • isInProgress

        public final boolean isInProgress()
        Returns true if the node is in the process of loading its children. See GTreeSlowLoadingNode
        Returns:
        true if the node is in the process of loading its children.
      • isLoaded

        public boolean isLoaded()
        True if the children for this node have been loaded yet. Some GTree nodes are lazy in that they don't load their children until needed. Nodes that have the IN_PROGRESS node as it child is considered loaded if in the swing thread, otherwise they are considered not loaded.
        Returns:
        true if the children for this node have been loaded.
      • getTree

        public GTree getTree()
        Returns the GTree that this node is attached to
        Returns:
        the GTree that this node is attached to
      • doFireNodeAdded

        protected void doFireNodeAdded​(GTreeNode newNode)
      • doFireNodeRemoved

        protected void doFireNodeRemoved​(GTreeNode removedNode,
                                         int index)
      • doFireNodeStructureChanged

        protected void doFireNodeStructureChanged()
      • doFireNodeChanged

        protected void doFireNodeChanged()