iluwatar#778 Implemented BSTIterator. Included comprehensive unit and integration tests. Refactored file structure to be friendly to future contributors with iterators of more data structures. Added JUnitPlatform to enable running test suite across all iterator implementations. Added README to /binarysearchtree to document what it does and how it works.

Author: mitchellirvin

iterator/etc/bst.png

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <class-diagram version="1.1.8" icons="true" automaticImage="PNG" always-add-relationships="false" generalizations="true" 
   realizations="true" associations="true" dependencies="false" nesting-relationships="true">  
-  <class id="1" language="java" name="com.iluwatar.iterator.TreasureChest" project="iterator" 
+  <class id="1" language="java" name="com.iluwatar.iterator.list.TreasureChest" project="iterator"
     file="/iterator/src/main/java/com/iluwatar/iterator/TreasureChest.java" binary="false" corner="BOTTOM_RIGHT">    
     <position height="124" width="195" x="1" y="237"/>    
     <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
@@ -10,7 +10,7 @@
       <operations public="true" package="true" protected="true" private="true" static="true"/>    
     </display>  
   </class>  
-  <class id="2" language="java" name="com.iluwatar.iterator.Item" project="iterator" 
+  <class id="2" language="java" name="com.iluwatar.iterator.list.Item" project="iterator"
     file="/iterator/src/main/java/com/iluwatar/iterator/Item.java" binary="false" corner="BOTTOM_RIGHT">    
     <position height="160" width="157" x="195" y="401"/>    
     <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
@@ -19,7 +19,7 @@
       <operations public="true" package="true" protected="true" private="true" static="true"/>    
     </display>  
   </class>  
-  <enumeration id="3" language="java" name="com.iluwatar.iterator.ItemType" project="iterator" 
+  <enumeration id="3" language="java" name="com.iluwatar.iterator.list.ItemType" project="iterator"
     file="/iterator/src/main/java/com/iluwatar/iterator/ItemType.java" binary="false" corner="BOTTOM_RIGHT">    
     <position height="160" width="145" x="388" y="601"/>    
     <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
@@ -28,7 +28,7 @@
       <operations public="true" package="true" protected="true" private="true" static="true"/>    
     </display>  
   </enumeration>  
-  <interface id="4" language="java" name="com.iluwatar.iterator.ItemIterator" project="iterator" 
+  <interface id="4" language="java" name="com.iluwatar.iterator.list.ItemIterator" project="iterator"
     file="/iterator/src/main/java/com/iluwatar/iterator/ItemIterator.java" binary="false" corner="BOTTOM_RIGHT">    
     <position height="106" width="131" x="236" y="237"/>    
     <display autosize="true" stereotype="true" package="true" initial-value="false" signature="true" 
@@ -37,7 +37,7 @@
       <operations public="true" package="true" protected="true" private="true" static="true"/>    
     </display>  
   </interface>  
-  <class id="5" language="java" name="com.iluwatar.iterator.TreasureChestItemIterator" project="iterator" 
+  <class id="5" language="java" name="com.iluwatar.iterator.list.TreasureChestItemIterator" project="iterator"
     file="/iterator/src/main/java/com/iluwatar/iterator/TreasureChestItemIterator.java" binary="false" 
     corner="BOTTOM_RIGHT">    
     <position height="160" width="323" x="236" y="37"/>    

iterator/etc/iterator.ucls

@@ -48,5 +48,11 @@
       <artifactId>junit-jupiter-params</artifactId>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>org.junit.platform</groupId>
+      <artifactId>junit-platform-runner</artifactId>
+      <version>1.2.0</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
 </project>

iterator/pom.xml

@@ -0,0 +1,78 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package com.iluwatar.iterator.binarysearchtree;
+
+import com.iluwatar.iterator.interfaces.Iterator;
+import java.util.ArrayDeque;
+
+/**
+ * This BstIterator iterates IN order. For example, given a BST with Integer values,
+ * expect to retrieve TreeNodes according to the Integer's natural ordering (1, 2, 3...)
+ * @param <T> This Iterator has been implemented with generic typing to allow traversal of TreeNodes of various types
+ */
+public class BstIterator<T> implements Iterator {
+
+  private ArrayDeque<TreeNode<T>> pathStack;
+
+  public BstIterator(TreeNode<T> root) {
+    pathStack = new ArrayDeque<>();
+    pushPathToNextSmallest(root);
+  }
+
+  /**
+   * This BstIterator manages to use O(h) extra space, where h is the height of the tree
+   * It achieves this by maintaining a stack of the nodes to handle (pushing all left nodes first),
+   * before handling self or right node
+   * @param node TreeNode that acts as root of the subtree we're interested in.
+   */
+  private void pushPathToNextSmallest(TreeNode<T> node) {
+    while (node != null) {
+      pathStack.push(node);
+      node = node.getLeft();
+    }
+  }
+
+  /**
+   * @return true if this iterator has a "next" element
+   */
+  @Override
+  public boolean hasNext() {
+    return !pathStack.isEmpty();
+  }
+
+  /**
+   *
+   * @return TreeNode next. The next element according to our in-order traversal of the given BST
+   * @throws IllegalStateException if this iterator does not have a next element
+   */
+  @Override
+  public TreeNode<T> next() throws IllegalStateException {
+    if (pathStack.isEmpty()) {
+      throw new IllegalStateException();
+    }
+    TreeNode<T> next = pathStack.pop();
+    pushPathToNextSmallest(next.getRight());
+    return next;
+  }
+
+}

iterator/src/main/java/com/iluwatar/iterator/binarysearchtree/BstIterator.java

@@ -0,0 +1,86 @@
+# BSTIterator
+An implementation of the Iterator design pattern, for the Binary Search Tree
+data structure. A great explanation of BSTs can be found in this [video tutorial](https://www.youtube.com/watch?v=i_Q0v_Ct5lY).
+
+### What it Does
+This iterator assumes that the given binary search tree inserts nodes of smaller 
+value to the left, and nodes of larger value to the right of current node. Accordingly, 
+this iterator will return nodes according to "In Order" binary tree traversal. 
+This means that given a binary search tree like the following, the iterator would 
+return values in order: 1, 3, 4, 6, 7, 8, 10, 13, 14. 
+
+![BST](../../../../../../../etc/bst.png "Binary Search Tree")  
+
+### How It's Done
+**The trivial solution** to a binary search tree iterator would be to construct a List (or similar 
+linear data structure) when you construct the BSTIterator. This would require traversing the entire
+BST, adding each node value to your list as you go. The downside to the trivial solution is twofold.
+You're front loading the work by requiring the BSTIterator's constructor to traverse the entire tree, 
+and you're taking up more memory by maintaining (worst case) every node in the tree in a separate 
+data structure. In Big O terms, here are the costs, where n is the number of nodes in the tree:
+* Constructor Run Time: O(n) 
+* `next()` Run Time: O(1)
+* `hasNext()` Run Time: O(1)
+* Extra Space: O(n)
+
+**A better solution** is to maintain _only_ the path to the next smallest node. For instance, given 
+the BST above, when you first create your BSTIterator, instead of traversing the entire tree, you 
+would navigate to the next smallest node (in this case, 1), pushing nodes onto a stack along the way. 
+Your BSTIterator Constructor would look like:
+```
+private ArrayDeque<TreeNode> pathStack;
+
+public BSTIterator(TreeNode root) {
+  pathStack = new ArrayDeque<>();
+  pushPathToNextSmallest(root);
+}
+
+private void pushPathToNextSmallest(TreeNode node) {
+  while (node != null) {
+    pathStack.push(node);
+    node = node.getLeft();
+  }
+}
+```
+
+After the constructor is called our BST, your `pathStack` would look like this:
+
+1\
+3\
+8
+
+This way, you're certain of what the next smallest node is because it lives on top of your path 
+stack. In order to maintain the integrity of this path stack, when you call `next()` and pop a 
+node off the stack, you must check to see if it has a right child. If it does, then you must follow the right 
+child's path to the next smallest node (pushing onto your path stack as you go). Given our above example, 
+calling `next()` on our BSTIterator twice would return node "3". Node "3" has a right child, indicating 
+a path to a node smaller than 3's parent. In this case, you would push node "6" onto the stack, 
+and node "4" onto the stack. `next()` would look like this:
+
+```
+public TreeNode next() throws IllegalStateException {
+  // If the user calls next() and hasNext() is false
+  if (pathStack.isEmpty()) {
+    throw new IllegalStateException();
+  }
+  TreeNode next = pathStack.pop();
+  // follow right child to next smallest node
+  pushPathToNextSmallest(next.getRight());
+  return next;
+}
+```
+
+**Key Concept:** The path to the smallest node of a given subtree is navigating straight to the 
+leftmost node of that subtree.
+
+In Big O terms, here are the costs for our improved solution, where h is the height of the tree:
+* Constructor Run Time: O(h) 
+* `next()` Amortized Run Time: O(1)
+* `hasNext()` Run Time: O(1)
+* Extra Space: O(h)
+
+As you can see, this solution more evenly distributes the work. It yields the same amortized 
+runtime for `next()`, reduces the run time of the constructor, and uses less extra space. 
+
+
+ 

iterator/src/main/java/com/iluwatar/iterator/binarysearchtree/README.md

@@ -0,0 +1,66 @@
+/**
+ * The MIT License Copyright (c) 2014-2016 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+ * associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute,
+ * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+ * NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.iluwatar.iterator.binarysearchtree;
+
+/**
+ * This TreeNode class allows for a generically typed value.
+ * @param <T> generically typed to accept various data types for the val property
+ */
+public class TreeNode<T> {
+
+  private T val;
+  private TreeNode<T> left;
+  private TreeNode<T> right;
+
+  /**
+   * Creates a TreeNode with a given value, and null children
+   * @param val The value of the given node
+   */
+  public TreeNode(T val) {
+    this.val = val;
+    this.left = null;
+    this.right = null;
+  }
+
+  T getVal() {
+    return val;
+  }
+
+  TreeNode<T> getLeft() {
+    return left;
+  }
+
+  void setLeft(TreeNode<T> left) {
+    this.left = left;
+  }
+
+  TreeNode<T> getRight() {
+    return right;
+  }
+
+  void setRight(TreeNode<T> right) {
+    this.right = right;
+  }
+
+  @Override
+  public String toString() {
+    return val.toString();
+  }
+
+}

iterator/src/main/java/com/iluwatar/iterator/binarysearchtree/TreeNode.java

@@ -0,0 +1,30 @@
+/**
+ * The MIT License Copyright (c) 2014-2016 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+ * associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute,
+ * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+ * NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+ * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+package com.iluwatar.iterator.interfaces;
+
+/**
+ * Iterator interface to be implemented by iterators over various data structures
+ * @param <T> generically typed for various objects
+ */
+public interface Iterator<T> {
+
+  boolean hasNext();
+
+  T next();
+}

iterator/src/main/java/com/iluwatar/iterator/interfaces/Iterator.java

@@ -20,8 +20,9 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.iluwatar.iterator;
+package com.iluwatar.iterator.list;
 
+import com.iluwatar.iterator.interfaces.Iterator;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -30,7 +31,7 @@
  * The Iterator pattern is a design pattern in which an iterator is used to traverse a container and
  * access the container's elements. The Iterator pattern decouples algorithms from containers.
  * <p>
- * In this example the Iterator ({@link ItemIterator}) adds abstraction layer on top of a collection
+ * In this example the Iterator ({@link Iterator}) adds abstraction layer on top of a collection
  * ({@link TreasureChest}). This way the collection can change its internal implementation without
  * affecting its clients.
  * 

iterator/src/main/java/com/iluwatar/iterator/App.java renamed to iterator/src/main/java/com/iluwatar/iterator/list/App.java

@@ -20,7 +20,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.iluwatar.iterator;
+package com.iluwatar.iterator.list;
 
 /**
  * 

iterator/src/main/java/com/iluwatar/iterator/Item.java renamed to iterator/src/main/java/com/iluwatar/iterator/list/Item.java

@@ -20,7 +20,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
  * THE SOFTWARE.
  */
-package com.iluwatar.iterator;
+package com.iluwatar.iterator.list;
 
 /**
  *