Module org.apache.sis.util
Package org.apache.sis.util.collection

# Class DefaultTreeTable.Node

Object
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 predefined 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

- ## Constructor Summary

  Constructors
  Constructor
  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

  Modifier and Type
  Method
  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.
  `final List<TreeTable​.Node>`
  `getChildren()`
  Returns the children of this node.
  `final 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 cannot 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 Details

  - ### 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 Details

  - ### 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 cannot 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 cannot 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 cannot 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 cannot 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 cannot clone the parent.
    - For making possible to compare branches instead of 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.