src/net/pterodactylus/util/data/Node.java

   1
   2 package net.pterodactylus.util.data;
   3
   4 import java.util.Comparator;
   5 import java.util.Iterator;
   6
   7 /**
   8  * A node that can be stored in a {@link Tree}. A node has exactly one parent
   9  * (which is <code>null</code> if the node is the {@link Tree#getRootNode()}
  10  * of the tree) and an arbitrary amount of child nodes.
  11  *
  12  * @author David ‘Bombe’ Roden &lt;bombe@freenetproject.org&gt;
  13  * @param <E>
  14  *            The type of the element to store
  15  */
  16 public interface Node<E extends Comparable<E>> extends Iterable<Node<E>>, Comparable<Node<E>> {
  17
  18         /**
  19          * Returns the parent node of the node.
  20          *
  21          * @return The parent node
  22          */
  23         public Node<E> getParent();
  24
  25         /**
  26          * Returns the element that is stored in the node.
  27          *
  28          * @return The node’s element
  29          */
  30         public E getElement();
  31
  32         /**
  33          * Adds an element as a child to this node and returns the created node.
  34          *
  35          * @param child
  36          *            The child node’s element
  37          * @return The created child node
  38          */
  39         public Node<E> addChild(E child);
  40
  41         /**
  42          * Returns the number of children this node has.
  43          *
  44          * @return The number of children
  45          */
  46         public int size();
  47
  48         /**
  49          * Returns the child at the given index.
  50          *
  51          * @param index
  52          *            The index of the child
  53          * @return The child at the given index
  54          */
  55         public Node<E> getChild(int index);
  56
  57         /**
  58          * Returns the direct child node that contains the given element.
  59          *
  60          * @param element
  61          *            The element
  62          * @return The direct child node containing the given element, or
  63          *         <code>null</code> if this node does not have a child node
  64          *         containing the given element
  65          */
  66         public Node<E> getChild(E element);
  67
  68         /**
  69          * Returns whether the given node is a direct child of this node.
  70          *
  71          * @param childNode
  72          *            The child node
  73          * @return <code>true</code> if the given node is a direct child of this
  74          *         node, <code>false</code> otherwise
  75          */
  76         public boolean hasChild(Node<E> childNode);
  77
  78         /**
  79          * Returns whether this node contains a child node containing the given
  80          * element.
  81          *
  82          * @param element
  83          *            The element
  84          * @return <code>true</code> if this node contains a direct child node
  85          *         containing the given element, <code>false</code> otherwise
  86          */
  87         public boolean hasChild(E element);
  88
  89         /**
  90          * Returns the index of the given child node.
  91          *
  92          * @param childNode
  93          *            The child node
  94          * @return The index of the child node, or <code>-1</code> if the child
  95          *         node is not a child node of this node
  96          */
  97         public int getIndexOfChild(Node<E> childNode);
  98
  99         /**
 100          * Returns the index of the child node containing the given element.
 101          *
 102          * @param element
 103          *            The element
 104          * @return The index of the child node, or <code>-1</code> if the child
 105          *         node is not a child node of this node
 106          */
 107         public int getIndexOfChild(E element);
 108
 109         /**
 110          * Remove the given child node from this node. If the given node is not a
 111          * child of this node, nothing happens.
 112          *
 113          * @param childNode
 114          *            The child node to remove
 115          */
 116         public void removeChild(Node<E> childNode);
 117
 118         /**
 119          * Removes the child node that contains the given element. The element in
 120          * the node is checked using {@link Object#equals(Object)}.
 121          *
 122          * @param child
 123          *            The child element to remove
 124          */
 125         public void removeChild(E child);
 126
 127         /**
 128          * Removes the child at the given index.
 129          *
 130          * @param childIndex
 131          *            The index of the child to remove
 132          */
 133         public void removeChild(int childIndex);
 134
 135         /**
 136          * Removes all children from this node.
 137          */
 138         public void removeAllChildren();
 139
 140         /**
 141          * {@inheritDoc}
 142          */
 143         public Iterator<Node<E>> iterator();
 144
 145         /**
 146          * Searches this node’s children recursively for a node that contains the
 147          * given element.
 148          *
 149          * @param element
 150          *            The element to search
 151          * @return The node that contains the given element, or <code>null</code>
 152          *         if no node could be found
 153          */
 154         public Node<E> findChild(E element);
 155
 156         /**
 157          * Sorts all children according to their natural order.
 158          */
 159         public void sortChildren();
 160
 161         /**
 162          * Sorts all children with the given comparator.
 163          *
 164          * @param comparator
 165          *            The comparator used to sort the children
 166          */
 167         public void sortChildren(Comparator<Node<E>> comparator);
 168
 169 }