org.apache.sis.util.collection

## Class DefaultTreeTable.Node

- Object
- - DefaultTreeTable.Node

- All Implemented Interfaces:
    Serializable, Cloneable, TreeTable.Node
  Enclosing class:
    DefaultTreeTable

      public static class DefaultTreeTable.Node
      extends Object
      implements TreeTable.Node, Cloneable, Serializable

  A `TreeTable​.Node` implementation which can store values for a pre-defined list of columns. The list of columns is specified by a `TreeTable`, or inherited from a parent node.
  Note on the parent node
  The value returned by the `getParent()` method is updated automatically when this node is added to or removed from the list of children of another `Node` instance - there is no `setParent(Node)` method. Since the parent is inferred rather than user-specified, it is ignored by the `clone()`, `equals(Object)` and `hashCode()` methods.
  Since:
    0.3
  See Also:
    `DefaultTreeTable`, `TableColumn`, Serialized Form

  Defined in the `sis-utility` module

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Node(CharSequence name)` Creates a node with a single column for object names (convenience constructor).
    `Node(DefaultTreeTable.Node parent)` Creates a new node with the given parent.
    `Node(DefaultTreeTable.Node parent, int index)` Creates a new node with the given parent.
    `Node(TreeTable table)` Creates a new node for the given table.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DefaultTreeTable.Node` | `clone()` Returns a clone of this node without parent.
    `boolean` | `equals(Object other)` Compares the given object with this node for values and children equality, ignoring the parent.
    `List<TreeTable.Node>` | `getChildren()` Returns the children of this node.
    `TreeTable.Node` | `getParent()` Returns the parent of this node.
    `Object` | `getUserObject()` Returns the user object associated to this node.
    `<V> V` | `getValue(TableColumn<V> column)` Returns the value in the given column, or `null` if none.
    `int` | `hashCode()` Returns a hash-code value computed from the values and children, ignoring the parent.
    `boolean` | `isEditable(TableColumn<?> column)` Determines whether the value in the specified column is editable.
    `boolean` | `isLeaf()` Returns `true` if this node can not have any children.
    `DefaultTreeTable.Node` | `newChild()` Adds a new child in the children list.
    `<V> void` | `setValue(TableColumn<V> column, V value)` Sets the value for the given column.
    `String` | `toString()` Returns a string representation of this node for identification in error message or in debugger.

    - ### Methods inherited from class Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Node

          public Node(TreeTable table)

      Creates a new node for the given table. The new node will be able to store a value for each columns defined in the given table.

      This method does not set the new node as the root of the given table. If desired, it is the caller responsibility to set the table root node.

      Parameters:
        `table` - the table for which this node is created.

    - #### Node

          public Node(DefaultTreeTable.Node parent)

      Creates a new node with the given parent. The new node is added at the end of the parent list of children. The new node will be able to store values for the same columns than the parent node.
      Parameters:
        `parent` - the parent of the new node.

    - #### Node

          public Node(DefaultTreeTable.Node parent,
                      int index)

      Creates a new node with the given parent. The new node is added to the parent list of children at the given index. The new node will be able to store values for the same columns than the parent node.
      Parameters:
        `parent` - the parent of the new node.
        `index` - the index where to add the new node in the parent list of children.

    - #### Node

          public Node(CharSequence name)

      Creates a node with a single column for object names (convenience constructor). The node will have the following columns:

      Node columns
      Header | Type | Initial value
      --- | --- | ---
      "Name" | `CharSequence` | `name`

      Parameters:
        `name` - the initial value for the "Name" column (can be `null`).

  - ### Method Detail

    - #### getParent

          public final TreeTable.Node getParent()

      Returns the parent of this node. On `Node` creation, this value may be initially `null`. It will be automatically set to a non-null value when this node will be added as a child of another `Node` instance.

      Note that the parent is intentionally ignored by the `clone()`, `equals(Object)` and `hashCode()` methods.

      Specified by:
        `getParent` in interface `TreeTable​.Node`
      Returns:
        the parent, or `null` if none.

    - #### isLeaf

          public boolean isLeaf()

      Returns `true` if this node can not have any children. The default implementation unconditionally returns `false` even if the list of children is empty, because the list is allowed to grow at any time.

      Subclasses can override this method if they can determine which nodes are leaves. In the current implementation, the return value shall be stable (i.e. a node can not alternate between leaf and non-leaf state). However this restriction may be relaxed in a future SIS version.

      Specified by:
        `isLeaf` in interface `TreeTable​.Node`
      Returns:
        `true` if this node can not have any children.

    - #### getChildren

          public final List<TreeTable.Node> getChildren()

      Returns the children of this node. For non-leaf nodes, the list is modifiable and will automatically updates the parent reference of any `Node` instance added to or removed from the list.

      For leaf nodes, this method returns an unmodifiable empty list.

      Specified by:
        `getChildren` in interface `TreeTable​.Node`
      Returns:
        the children, or an empty collection if none.

    - #### newChild

          public DefaultTreeTable.Node newChild()

      Adds a new child in the children list. The default implementation first checks that this node is not a leaf, then delegates to the `Node(Node)` constructor. That constructor call has the following implications:
      - The new node inherits the columns of this node, on the assumption that they are the same set of columns than other children nodes.
      - The new node is appended at the end of the children list.
      Subclasses may override this method with different behavior.
      Specified by:
        `newChild` in interface `TreeTable​.Node`
      Returns:
        the new child.
      Throws:
        `UnsupportedOperationException` - if this node is a leaf.

    - #### getValue

          public <V> V getValue(TableColumn<V> column)

      Returns the value in the given column, or `null` if none.
      Specified by:
        `getValue` in interface `TreeTable​.Node`
      Type Parameters:
        `V` - the base type of values in the given column.
      Parameters:
        `column` - identifier of the column from which to get the value.
      Returns:
        the value in the given column, or `null` if none.
      See Also:
        `TreeTable​.getColumns()`

    - #### setValue

          public <V> void setValue(TableColumn<V> column,
                                   V value)
                            throws IllegalArgumentException

      Sets the value for the given column. The `isEditable(TableColumn)` method can be invoked before this setter method for determining if the given column is modifiable.
      Specified by:
        `setValue` in interface `TreeTable​.Node`
      Type Parameters:
        `V` - the base type of values in the given column.
      Parameters:
        `column` - identifier of the column into which to set the value.
        `value` - the value to set.
      Throws:
        `IllegalArgumentException` - if the given column is not a legal column for this node.
      See Also:
        `isEditable(TableColumn)`

    - #### isEditable

          public boolean isEditable(TableColumn<?> column)

      Determines whether the value in the specified column is editable. If the given column is not a legal column for this `Node` instance, then this method returns `false`.
      Specified by:
        `isEditable` in interface `TreeTable​.Node`
      Parameters:
        `column` - the column to query.
      Returns:
        `true` if the given column is a legal column for this `Node` implementation and the corresponding value is editable, or `false` otherwise.

    - #### getUserObject

          public Object getUserObject()

      Returns the user object associated to this node. The default implementation returns `null`.
      Specified by:
        `getUserObject` in interface `TreeTable​.Node`
      Returns:
        any object stored at this node by the user, or `null` if none.

    - #### clone

          public DefaultTreeTable.Node clone()
                                      throws CloneNotSupportedException

      Returns a clone of this node without parent. This method recursively clones all children, but does not clone the column values. The parent of the cloned node is set to `null`.
      Overrides:
        `clone` in class `Object`
      Returns:
        a clone of this node without parent.
      Throws:
        `CloneNotSupportedException` - if this node or one of its children can not be cloned.

    - #### equals

          public boolean equals(Object other)

      Compares the given object with this node for values and children equality, ignoring the parent. This method can be used for determining if two branches of a same tree or of two different trees are identical.
      Implementation note: This method ignores the parent because:
      - When comparing the children recursively, comparing the parents would cause infinite recursivity.
      - For consistency with the `clone()` method, which can not clone the parent.
      - For making possible to compare branches instead than only whole trees.
      Specified by:
        `equals` in interface `TreeTable​.Node`
      Overrides:
        `equals` in class `Object`
      Parameters:
        `other` - the object to compare with this node.
      Returns:
        `true` if the two objects are equal, ignoring the parent node.

    - #### hashCode

          public int hashCode()

      Returns a hash-code value computed from the values and children, ignoring the parent. This method is defined for consistency with `equals(Object)` contract.
      Specified by:
        `hashCode` in interface `TreeTable​.Node`
      Overrides:
        `hashCode` in class `Object`
      Returns:
        a hash code for this node, potentially based on values and children but ignoring parent.

    - #### toString

          public String toString()

      Returns a string representation of this node for identification in error message or in debugger. The default implementation returns the `toString()` value of the first non-empty `CharSequence` found in the values, if any. If no such value is found, then this method returns "Node-i" where Node is the simple classname and i is the index of this node in the parent node.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this node.

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.