HBASE-17532 Replaced explicit type with diamond operator

[hbase.git] / hbase-common / src / main / java / org / apache / hadoop / hbase / util / AvlUtil.java

/**
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.hadoop.hbase.util;

import java.util.Iterator;
import java.util.concurrent.atomic.AtomicBoolean;

import org.apache.hadoop.hbase.classification.InterfaceAudience;
import org.apache.hadoop.hbase.classification.InterfaceStability;

/**
 * Helper class that allows to create and manipulate an AvlTree.
 * The main utility is in cases where over time we have a lot of add/remove of the same object,
 * and we want to avoid all the allocations/deallocations of the "node" objects that the
 * java containers will create.
 */
@InterfaceAudience.Private
@InterfaceStability.Evolving
public final class AvlUtil {
  private AvlUtil() {}

  /**
   * This class represent a node that will be used in an AvlTree.
   * Instead of creating another object for the tree node,
   * like the TreeMap and the other java contains, here the node can be extended
   * and the content can be embedded directly in the node itself.
   * This is useful in cases where over time we have a lot of add/remove of the same object.
   */
  @InterfaceAudience.Private
  public static abstract class AvlNode<TNode extends AvlNode> {
    protected TNode avlLeft;
    protected TNode avlRight;
    protected int avlHeight;

    public abstract int compareTo(TNode other);
  }

  /**
   * This class extends the AvlNode and adds two links that will be used in conjunction
   * with the AvlIterableList class.
   * This is useful in situations where your node must be in a map to have a quick lookup by key,
   * but it also require to be in something like a list/queue.
   * This is useful in cases where over time we have a lot of add/remove of the same object.
   */
  @InterfaceAudience.Private
  public static abstract class AvlLinkedNode<TNode extends AvlLinkedNode> extends AvlNode<TNode> {
    protected TNode iterNext = null;
    protected TNode iterPrev = null;
  }

  @InterfaceAudience.Private
  public interface AvlInsertOrReplace<TNode extends AvlNode> {
    TNode insert(Object searchKey);
    TNode replace(Object searchKey, TNode prevNode);
  }

  /**
   * The AvlTree allows to lookup an object using a custom key.
   * e.g. the java Map allows only to lookup by key using the Comparator
   * specified in the constructor.
   * In this case you can pass a specific comparator for every needs.
   */
  @InterfaceAudience.Private
  public static interface AvlKeyComparator<TNode extends AvlNode> {
    int compareKey(TNode node, Object key);
  }

  /**
   * Visitor that allows to traverse a set of AvlNodes.
   * If you don't like the callback style of the visitor you can always use the AvlTreeIterator.
   */
  @InterfaceAudience.Private
  public static interface AvlNodeVisitor<TNode extends AvlNode> {
    /**
     * @param node the node that we are currently visiting
     * @return false to stop the iteration. true to continue.
     */
    boolean visitNode(TNode node);
  }

  /**
   * Helper class that allows to create and manipulate an AVL Tree
   */
  @InterfaceAudience.Private
  public static class AvlTree {
    /**
     * @param root the current root of the tree
     * @param key the key for the node we are trying to find
     * @param keyComparator the comparator to use to match node and key
     * @return the node that matches the specified key or null in case of node not found.
     */
    public static <TNode extends AvlNode> TNode get(TNode root, final Object key,
        final AvlKeyComparator<TNode> keyComparator) {
      while (root != null) {
        int cmp = keyComparator.compareKey(root, key);
        if (cmp > 0) {
          root = (TNode)root.avlLeft;
        } else if (cmp < 0) {
          root = (TNode)root.avlRight;
        } else {
          return (TNode)root;
        }
      }
      return null;
    }

    /**
     * @param root the current root of the tree
     * @return the first (min) node of the tree
     */
    public static <TNode extends AvlNode> TNode getFirst(TNode root) {
      if (root != null) {
        while (root.avlLeft != null) {
          root = (TNode)root.avlLeft;
        }
      }
      return root;
    }

    /**
     * @param root the current root of the tree
     * @return the last (max) node of the tree
     */
    public static <TNode extends AvlNode> TNode getLast(TNode root) {
      if (root != null) {
        while (root.avlRight != null) {
          root = (TNode)root.avlRight;
        }
      }
      return root;
    }

    /**
     * Insert a node into the tree. It uses the AvlNode.compareTo() for ordering.
     * NOTE: The node must not be already in the tree.
     * @param root the current root of the tree
     * @param node the node to insert
     * @return the new root of the tree
     */
    public static <TNode extends AvlNode> TNode insert(TNode root, TNode node) {
      if (root == null) return node;

      int cmp = node.compareTo(root);
      assert cmp != 0 : "node already inserted: " + root;
      if (cmp < 0) {
        root.avlLeft = insert(root.avlLeft, node);
      } else {
        root.avlRight = insert(root.avlRight, node);
      }
      return balance(root);
    }

    /**
     * Insert a node into the tree.
     * This is useful when you want to create a new node or replace the content
     * depending if the node already exists or not.
     * Using AvlInsertOrReplace class you can return the node to add/replace.
     *
     * @param root the current root of the tree
     * @param key the key for the node we are trying to insert
     * @param keyComparator the comparator to use to match node and key
     * @param insertOrReplace the class to use to insert or replace the node
     * @return the new root of the tree
     */
    public static <TNode extends AvlNode> TNode insert(TNode root, Object key,
        final AvlKeyComparator<TNode> keyComparator,
        final AvlInsertOrReplace<TNode> insertOrReplace) {
      if (root == null) {
        return insertOrReplace.insert(key);
      }

      int cmp = keyComparator.compareKey(root, key);
      if (cmp < 0) {
        root.avlLeft = insert((TNode)root.avlLeft, key, keyComparator, insertOrReplace);
      } else if (cmp > 0) {
        root.avlRight = insert((TNode)root.avlRight, key, keyComparator, insertOrReplace);
      } else {
        TNode left = (TNode)root.avlLeft;
        TNode right = (TNode)root.avlRight;
        root = insertOrReplace.replace(key, root);
        root.avlLeft = left;
        root.avlRight = right;
        return root;
      }
      return balance(root);
    }

    private static <TNode extends AvlNode> TNode removeMin(TNode p) {
      if (p.avlLeft == null)
        return (TNode)p.avlRight;
      p.avlLeft = removeMin(p.avlLeft);
      return balance(p);
    }

    /**
     * Removes the node matching the specified key from the tree
     * @param root the current root of the tree
     * @param key the key for the node we are trying to find
     * @param keyComparator the comparator to use to match node and key
     * @return the new root of the tree
     */
    public static <TNode extends AvlNode> TNode remove(TNode root, Object key,
        final AvlKeyComparator<TNode> keyComparator) {
      return remove(root, key, keyComparator, null);
    }

    /**
     * Removes the node matching the specified key from the tree
     * @param root the current root of the tree
     * @param key the key for the node we are trying to find
     * @param keyComparator the comparator to use to match node and key
     * @param removed will be set to true if the node was found and removed, otherwise false
     * @return the new root of the tree
     */
    public static <TNode extends AvlNode> TNode remove(TNode root, Object key,
        final AvlKeyComparator<TNode> keyComparator, final AtomicBoolean removed) {
      if (root == null) return null;

      int cmp = keyComparator.compareKey(root, key);
      if (cmp == 0) {
        if (removed != null) removed.set(true);

        TNode q = (TNode)root.avlLeft;
        TNode r = (TNode)root.avlRight;
        if (r == null) return q;
        TNode min = getFirst(r);
        min.avlRight = removeMin(r);
        min.avlLeft = q;
        return balance(min);
      } else if (cmp > 0) {
        root.avlLeft = remove((TNode)root.avlLeft, key, keyComparator);
      } else /* if (cmp < 0) */ {
        root.avlRight = remove((TNode)root.avlRight, key, keyComparator);
      }
      return balance(root);
    }

    /**
     * Visit each node of the tree
     * @param root the current root of the tree
     * @param visitor the AvlNodeVisitor instance
     */
    public static <TNode extends AvlNode> void visit(final TNode root,
        final AvlNodeVisitor<TNode> visitor) {
      if (root == null) return;

      final AvlTreeIterator<TNode> iterator = new AvlTreeIterator<>(root);
      boolean visitNext = true;
      while (visitNext && iterator.hasNext()) {
        visitNext = visitor.visitNode(iterator.next());
      }
    }

    private static <TNode extends AvlNode> TNode balance(TNode p) {
      fixHeight(p);
      int balance = balanceFactor(p);
      if (balance == 2) {
        if (balanceFactor(p.avlRight) < 0) {
          p.avlRight = rotateRight(p.avlRight);
        }
        return rotateLeft(p);
      } else if (balance == -2) {
        if (balanceFactor(p.avlLeft) > 0) {
          p.avlLeft = rotateLeft(p.avlLeft);
        }
        return rotateRight(p);
      }
      return p;
    }

    private static <TNode extends AvlNode> TNode rotateRight(TNode p) {
      TNode q = (TNode)p.avlLeft;
      p.avlLeft = q.avlRight;
      q.avlRight = p;
      fixHeight(p);
      fixHeight(q);
      return q;
    }

    private static <TNode extends AvlNode> TNode rotateLeft(TNode q) {
      TNode p = (TNode)q.avlRight;
      q.avlRight = p.avlLeft;
      p.avlLeft = q;
      fixHeight(q);
      fixHeight(p);
      return p;
    }

    private static <TNode extends AvlNode> void fixHeight(TNode node) {
      final int heightLeft = height(node.avlLeft);
      final int heightRight = height(node.avlRight);
      node.avlHeight = 1 + Math.max(heightLeft, heightRight);
    }

    private static <TNode extends AvlNode> int height(TNode node) {
      return node != null ? node.avlHeight : 0;
    }

    private static <TNode extends AvlNode> int balanceFactor(TNode node) {
      return height(node.avlRight) - height(node.avlLeft);
    }
  }

  /**
   * Iterator for the AvlTree
   */
  @InterfaceAudience.Private
  public static class AvlTreeIterator<TNode extends AvlNode> implements Iterator<TNode> {
    private final Object[] stack = new Object[64];

    private TNode current = null;
    private int height = 0;

    public AvlTreeIterator() {
    }

    /**
     * Create the iterator starting from the first (min) node of the tree
     */
    public AvlTreeIterator(final TNode root) {
      seekFirst(root);
    }

    /**
     * Create the iterator starting from the specified key
     * @param root the current root of the tree
     * @param key the key for the node we are trying to find
     * @param keyComparator the comparator to use to match node and key
     */
    public AvlTreeIterator(final TNode root, final Object key,
        final AvlKeyComparator<TNode> keyComparator) {
      seekTo(root, key, keyComparator);
    }

    @Override
    public boolean hasNext() {
      return current != null;
    }

    @Override
    public TNode next() {
      final TNode node = this.current;
      seekNext();
      return node;
    }

    @Override
    public void remove() {
      throw new UnsupportedOperationException();
    }

    /**
     * Reset the iterator, and seeks to the first (min) node of the tree
     * @param root the current root of the tree
     */
    public void seekFirst(final TNode root) {
      current = root;
      height = 0;
      if (root != null) {
        while (current.avlLeft != null) {
          stack[height++] = current;
          current = (TNode)current.avlLeft;
        }
      }
    }

    /**
     * Reset the iterator, and seeks to the specified key
     * @param root the current root of the tree
     * @param key the key for the node we are trying to find
     * @param keyComparator the comparator to use to match node and key
     */
    public void seekTo(final TNode root, final Object key,
        final AvlKeyComparator<TNode> keyComparator) {
      current = null;
      height = 0;

      TNode node = root;
      while (node != null) {
        if (keyComparator.compareKey(node, key) >= 0) {
          if (node.avlLeft != null) {
            stack[height++] = node;
            node = (TNode)node.avlLeft;
          } else {
            current = node;
            return;
          }
        } else {
          if (node.avlRight != null) {
            stack[height++] = node;
            node = (TNode)node.avlRight;
          } else {
            if (height > 0) {
              TNode parent = (TNode)stack[--height];
              while (node == parent.avlRight) {
                if (height == 0) {
                  current = null;
                  return;
                }
                node = parent;
                parent = (TNode)stack[--height];
              }
              current = parent;
              return;
            }
            current = null;
            return;
          }
        }
      }
    }

    private void seekNext() {
      if (current == null) return;
      if (current.avlRight != null) {
        stack[height++] = current;
        current = (TNode)current.avlRight;
        while (current.avlLeft != null) {
          stack[height++] = current;
          current = (TNode)current.avlLeft;
        }
      } else {
        TNode node;
        do {
          if (height == 0) {
            current = null;
            return;
          }
          node = current;
          current = (TNode)stack[--height];
        } while (current.avlRight == node);
      }
    }
  }

  /**
   * Helper class that allows to create and manipulate a linked list of AvlLinkedNodes
   */
  @InterfaceAudience.Private
  public static class AvlIterableList {
    /**
     * @param node the current node
     * @return the successor of the current node
     */
    public static <TNode extends AvlLinkedNode> TNode readNext(TNode node) {
      return (TNode)node.iterNext;
    }

    /**
     * @param node the current node
     * @return the predecessor of the current node
     */
    public static <TNode extends AvlLinkedNode> TNode readPrev(TNode node) {
      return (TNode)node.iterPrev;
    }

    /**
     * @param head the head of the linked list
     * @param node the node to add to the front of the list
     * @return the new head of the list
     */
    public static <TNode extends AvlLinkedNode> TNode prepend(TNode head, TNode node) {
      assert !isLinked(node) : node + " is already linked";
      if (head != null) {
        TNode tail = (TNode)head.iterPrev;
        tail.iterNext = node;
        head.iterPrev = node;
        node.iterNext = head;
        node.iterPrev = tail;
      } else {
        node.iterNext = node;
        node.iterPrev = node;
      }
      return node;
    }

    /**
     * @param head the head of the linked list
     * @param node the node to add to the tail of the list
     * @return the new head of the list
     */
    public static <TNode extends AvlLinkedNode> TNode append(TNode head, TNode node) {
      assert !isLinked(node) : node + " is already linked";
      if (head != null) {
        TNode tail = (TNode)head.iterPrev;
        tail.iterNext = node;
        node.iterNext = head;
        node.iterPrev = tail;
        head.iterPrev = node;
        return head;
      }
      node.iterNext = node;
      node.iterPrev = node;
      return node;
    }

    /**
     * @param head the head of the current linked list
     * @param otherHead the head of the list to append to the current list
     * @return the new head of the current list
     */
    public static <TNode extends AvlLinkedNode> TNode appendList(TNode head, TNode otherHead) {
      if (head == null) return otherHead;
      if (otherHead == null) return head;

      TNode tail = (TNode)head.iterPrev;
      TNode otherTail = (TNode)otherHead.iterPrev;
      tail.iterNext = otherHead;
      otherHead.iterPrev = tail;
      otherTail.iterNext = head;
      head.iterPrev = otherTail;
      return head;
    }

    /**
     * @param head the head of the linked list
     * @param node the node to remove from the list
     * @return the new head of the list
     */
    public static <TNode extends AvlLinkedNode> TNode remove(TNode head, TNode node) {
      assert isLinked(node) : node + " is not linked";
      if (node != node.iterNext) {
        node.iterPrev.iterNext = node.iterNext;
        node.iterNext.iterPrev = node.iterPrev;
        head = (head == node) ? (TNode)node.iterNext : head;
      } else {
        head = null;
      }
      node.iterNext = null;
      node.iterPrev = null;
      return head;
    }

    /**
     * @param node the node to check
     * @return true if the node is linked to a list, false otherwise
     */
    public static <TNode extends AvlLinkedNode> boolean isLinked(TNode node) {
      return node.iterPrev != null && node.iterNext != null;
    }
  }
}