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>

5 files changed, 45 insertions, 0 deletions

diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java
index b4e2d2c2dd..aa8d9fb85d 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/dircache/DirCacheIterator.java
@@ -160,6 +160,15 @@ public class DirCacheIterator extends AbstractTreeIterator {
 	}
 
 	@Override
+	public void reset() {
+		if (!first()) {
+			ptr = treeStart;
+			if (!eof())
+				parseEntry();
+		}
+	}
+
+	@Override
 	public boolean first() {
 		return ptr == treeStart;
 	}
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java
index a54b3e9cfa..eee62c63a5 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/AbstractTreeIterator.java
@@ -497,6 +497,22 @@ public abstract class AbstractTreeIterator {
 	}
 
 	/**
+	 * 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>
 	 * An iterator is positioned on the first entry if <code>back(1)</code>
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java
index 8e4094a055..01b8274253 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/CanonicalTreeParser.java
@@ -244,6 +244,12 @@ public class CanonicalTreeParser extends AbstractTreeIterator {
 	}
 
 	@Override
+	public void reset() {
+		if (!first())
+			reset(raw);
+	}
+
+	@Override
 	public boolean first() {
 		return currPtr == 0;
 	}
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java
index 7d4ee6d2bd..49d75871e8 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/EmptyTreeIterator.java
@@ -108,6 +108,11 @@ public class EmptyTreeIterator extends AbstractTreeIterator {
 	}
 
 	@Override
+	public void reset() {
+		// Do nothing.
+	}
+
+	@Override
 	public boolean first() {
 		return true;
 	}
diff --git a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java
index 5256e8aae9..51c3483699 100644
--- a/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java
+++ b/org.eclipse.jgit/src/org/eclipse/jgit/treewalk/WorkingTreeIterator.java
@@ -333,6 +333,15 @@ public abstract class WorkingTreeIterator extends AbstractTreeIterator {
 	}
 
 	@Override
+	public void reset() {
+		if (!first()) {
+			ptr = 0;
+			if (!eof())
+				parseEntry();
+		}
+	}
+
+	@Override
 	public boolean first() {
 		return ptr == 0;
 	}