Add reset() to AbstractTreeIterator API

This allows callers to force the iterator back to its starting point,
so it can be traversed again.  The default way to do this is to use
back(1) until first() is true, but this isn't very efficient for any
iterator.  All current implementations have better ways to implement
reset without needing to seek backwards.

Change-Id: Ia26e6c852fdac8a0e9c80ac72c8cca9d897463f4
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java

@@ -159,6 +159,15 @@ public class DirCacheIterator extends AbstractTreeIterator {
 		return 0;
 	}
 
+	@Override
+	public void reset() {
+		if (!first()) {
+			ptr = treeStart;
+			if (!eof())
+				parseEntry();
+		}
+	}
+
 	@Override
 	public boolean first() {
 		return ptr == treeStart;

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java

@@ -496,6 +496,22 @@ public abstract class AbstractTreeIterator {
 		return createSubtreeIterator(reader);
 	}
 
+	/**
+	 * Position this iterator on the first entry.
+	 *
+	 * The default implementation of this method uses {@code back(1)} until
+	 * {@code first()} is true. This is most likely not the most efficient
+	 * method of repositioning the iterator to its first entry, so subclasses
+	 * are strongly encouraged to override the method.
+	 *
+	 * @throws CorruptObjectException
+	 *             the tree is invalid.
+	 */
+	public void reset() throws CorruptObjectException {
+		while (!first())
+			back(1);
+	}
+
 	/**
 	 * Is this tree iterator positioned on its first entry?
 	 * <p>

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java

@@ -243,6 +243,12 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 		return nextPtr - Constants.OBJECT_ID_LENGTH;
 	}
 
+	@Override
+	public void reset() {
+		if (!first())
+			reset(raw);
+	}
+
 	@Override
 	public boolean first() {
 		return currPtr == 0;

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java

@@ -107,6 +107,11 @@ public class EmptyTreeIterator extends AbstractTreeIterator {
 		return 0;
 	}
 
+	@Override
+	public void reset() {
+		// Do nothing.
+	}
+
 	@Override
 	public boolean first() {
 		return true;

org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java

@@ -332,6 +332,15 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 		return 0;
 	}
 
+	@Override
+	public void reset() {
+		if (!first()) {
+			ptr = 0;
+			if (!eof())
+				parseEntry();
+		}
+	}
+
 	@Override
 	public boolean first() {
 		return ptr == 0;