Deprecate all of the older Tree related code

We want to get rid of these APIs, because they don't perform as well
as DirCache/TreeWalk, or don't offer nearly as many features.

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

org.eclipse.jgit.test/tst/org/eclipse/jgit/lib/ReadTreeTest.java

@@ -609,7 +609,7 @@ public class ReadTreeTest extends RepositoryTestCase {
 	}
 
 	/**
-	 * An implementation of the {@link Checkout} interface which uses {@link WorkDirCheckout}
+	 * An implementation of the {@link Checkout} interface which uses WorkDirCheckout
 	 */
 	class WorkdirCheckoutImpl extends WorkDirCheckout implements Checkout {
 		public WorkdirCheckoutImpl(Tree head, GitIndex index,

org.eclipse.jgit/src/org/eclipse/jgit/lib/AbstractIndexTreeVisitor.java

@@ -55,7 +55,10 @@ import org.eclipse.jgit.lib.GitIndex.Entry;
  * case about certain events
  * @author dwatson
  *
+ * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk} instead, with a
+ * {@link org.eclipse.jgit.dircache.DirCacheIterator} as one of the members.
  */
+@Deprecated
 public class AbstractIndexTreeVisitor implements IndexTreeVisitor {
 	public void finishVisitTree(Tree tree, Tree auxTree, String curDir)
 			throws IOException {

org.eclipse.jgit/src/org/eclipse/jgit/lib/FileMode.java

@@ -82,7 +82,7 @@ public abstract class FileMode {
 	/** Bit pattern for {@link #TYPE_MASK} matching {@link #MISSING}. */
 	public static final int TYPE_MISSING = 0000000;
 
-	/** Mode indicating an entry is a {@link Tree}. */
+	/** Mode indicating an entry is a tree (aka directory). */
 	@SuppressWarnings("synthetic-access")
 	public static final FileMode TREE = new FileMode(TYPE_TREE,
 			Constants.OBJ_TREE) {
@@ -91,7 +91,7 @@ public abstract class FileMode {
 		}
 	};
 
-	/** Mode indicating an entry is a {@link SymlinkTreeEntry}. */
+	/** Mode indicating an entry is a symbolic link. */
 	@SuppressWarnings("synthetic-access")
 	public static final FileMode SYMLINK = new FileMode(TYPE_SYMLINK,
 			Constants.OBJ_BLOB) {
@@ -100,7 +100,7 @@ public abstract class FileMode {
 		}
 	};
 
-	/** Mode indicating an entry is a non-executable {@link FileTreeEntry}. */
+	/** Mode indicating an entry is a non-executable file. */
 	@SuppressWarnings("synthetic-access")
 	public static final FileMode REGULAR_FILE = new FileMode(0100644,
 			Constants.OBJ_BLOB) {
@@ -109,7 +109,7 @@ public abstract class FileMode {
 		}
 	};
 
-	/** Mode indicating an entry is an executable {@link FileTreeEntry}. */
+	/** Mode indicating an entry is an executable file. */
 	@SuppressWarnings("synthetic-access")
 	public static final FileMode EXECUTABLE_FILE = new FileMode(0100755,
 			Constants.OBJ_BLOB) {

org.eclipse.jgit/src/org/eclipse/jgit/lib/FileTreeEntry.java

@@ -48,7 +48,14 @@ import java.io.IOException;
 
 /**
  * A representation of a file (blob) object in a {@link Tree}.
+ *
+ * @deprecated To look up information about a single path, use
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#forPath(Repository, String, org.eclipse.jgit.revwalk.RevTree)}.
+ * To lookup information about multiple paths at once, use a
+ * {@link org.eclipse.jgit.treewalk.TreeWalk} and obtain the current entry's
+ * information from its getter methods.
  */
+@Deprecated
 public class FileTreeEntry extends TreeEntry {
 	private FileMode mode;
 

org.eclipse.jgit/src/org/eclipse/jgit/lib/GitIndex.java

@@ -357,7 +357,12 @@ public class GitIndex {
 		return filemode.booleanValue();
 	}
 
-	/** An index entry */
+	/**
+	 * An index entry
+	 *
+	 * @deprecated Use {@link org.eclipse.jgit.dircache.DirCacheEntry}.
+	 */
+	@Deprecated
 	public class Entry {
 		private long ctime;
 

org.eclipse.jgit/src/org/eclipse/jgit/lib/GitlinkTreeEntry.java

@@ -51,7 +51,14 @@ import java.io.IOException;
  * A tree entry representing a gitlink entry used for submodules.
  *
  * Note. Java cannot really handle these as file system objects.
+ *
+ * @deprecated To look up information about a single path, use
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#forPath(Repository, String, org.eclipse.jgit.revwalk.RevTree)}.
+ * To lookup information about multiple paths at once, use a
+ * {@link org.eclipse.jgit.treewalk.TreeWalk} and obtain the current entry's
+ * information from its getter methods.
  */
+@Deprecated
 public class GitlinkTreeEntry extends TreeEntry {
 	private static final long serialVersionUID = 1L;
 

org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexDiff.java

@@ -52,7 +52,13 @@ import org.eclipse.jgit.lib.GitIndex.Entry;
 
 /**
  * Compares the Index, a Tree, and the working directory
+ *
+ * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk} instead, with at
+ * least the {@link org.eclipse.jgit.dircache.DirCacheIterator} and
+ * {@link org.eclipse.jgit.treewalk.FileTreeIterator} iterators, and setting
+ * the filter {@link org.eclipse.jgit.treewalk.filter.TreeFilter#ANY_DIFF}.
  */
+@Deprecated
 public class IndexDiff {
 	private GitIndex index;
 	private Tree tree;

org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexTreeVisitor.java

@@ -58,7 +58,11 @@ import org.eclipse.jgit.lib.GitIndex.Entry;
  *
  * A File argument is supplied to allow us to check for modifications in
  * a work tree or update the file.
+ *
+ * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk} instead, with
+ * a {@link org.eclipse.jgit.dircache.DirCacheIterator} as a member.
  */
+@Deprecated
 public interface IndexTreeVisitor {
 	/**
 	 * Visit a blob, and corresponding tree and index entries.

org.eclipse.jgit/src/org/eclipse/jgit/lib/IndexTreeWalker.java

@@ -55,7 +55,13 @@ import org.eclipse.jgit.lib.GitIndex.Entry;
  * A class for traversing the index and one or two trees.
  *
  * A visitor is invoked for executing actions, like figuring out how to merge.
+ *
+ * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk} with multiple
+ * iterators, such as {@link org.eclipse.jgit.dircache.DirCacheIterator},
+ * {@link org.eclipse.jgit.treewalk.FileTreeIterator}, and a native tree
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#addTree(AnyObjectId)}.
  */
+@Deprecated
 public class IndexTreeWalker {
 	private final Tree mainTree;
 	private final Tree newTree;

org.eclipse.jgit/src/org/eclipse/jgit/lib/Repository.java

@@ -552,7 +552,10 @@ public class Repository {
 	 * @throws IOException for I/O error or unexpected object type.
 	 *
 	 * @see #resolve(String)
+	 * @deprecated Use {@link #resolve(String)} and pass its return value to
+	 * {@link org.eclipse.jgit.revwalk.RevWalk#parseCommit(AnyObjectId)}.
 	 */
+	@Deprecated
 	public Commit mapCommit(final String revstr) throws IOException {
 		final ObjectId id = resolve(revstr);
 		return id != null ? mapCommit(id) : null;
@@ -566,7 +569,12 @@ public class Repository {
 	 * @param refName optional, only relevant for simple tags
 	 * @return The Git object if found or null
 	 * @throws IOException
+	 * @deprecated Use {@link org.eclipse.jgit.revwalk.RevWalk#parseCommit(AnyObjectId)},
+	 *  or {@link org.eclipse.jgit.revwalk.RevWalk#parseTag(AnyObjectId)}.
+	 *  To read a tree, use {@link org.eclipse.jgit.treewalk.TreeWalk#addTree(AnyObjectId)}.
+	 *  To read a blob, open it with {@link #openObject(AnyObjectId)}.
 	 */
+	@Deprecated
 	public Object mapObject(final ObjectId id, final String refName) throws IOException {
 		final ObjectLoader or = openObject(id);
 		if (or == null)
@@ -596,7 +604,9 @@ public class Repository {
 	 * @param id
 	 * @return Commit or null
 	 * @throws IOException for I/O error or unexpected object type.
+	 * @deprecated Use {@link org.eclipse.jgit.revwalk.RevWalk#parseCommit(AnyObjectId)}.
 	 */
+	@Deprecated
 	public Commit mapCommit(final ObjectId id) throws IOException {
 		final ObjectLoader or = openObject(id);
 		if (or == null)
@@ -622,7 +632,10 @@ public class Repository {
 	 * @throws IOException
 	 *
 	 * @see #resolve(String)
+	 * @deprecated Use {@link #resolve(String)} and pass its return value to
+	 * {@link org.eclipse.jgit.treewalk.TreeWalk#addTree(AnyObjectId)}.
 	 */
+	@Deprecated
 	public Tree mapTree(final String revstr) throws IOException {
 		final ObjectId id = resolve(revstr);
 		return id != null ? mapTree(id) : null;
@@ -633,7 +646,9 @@ public class Repository {
 	 * @param id
 	 * @return Tree or null
 	 * @throws IOException for I/O error or unexpected object type.
+	 * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk#addTree(AnyObjectId)}.
 	 */
+	@Deprecated
 	public Tree mapTree(final ObjectId id) throws IOException {
 		final ObjectLoader or = openObject(id);
 		if (or == null)
@@ -667,7 +682,10 @@ public class Repository {
 	 * @param revstr
 	 * @return a Tag or null
 	 * @throws IOException on I/O error or unexpected type
+	 * @deprecated Use {@link #resolve(String)} and feed its return value to
+	 * {@link org.eclipse.jgit.revwalk.RevWalk#parseTag(AnyObjectId)}.
 	 */
+	@Deprecated
 	public Tag mapTag(String revstr) throws IOException {
 		final ObjectId id = resolve(revstr);
 		return id != null ? mapTag(revstr, id) : null;
@@ -679,7 +697,9 @@ public class Repository {
 	 * @param id
 	 * @return Commit or null
 	 * @throws IOException for I/O error or unexpected object type.
+	 * @deprecated Use {@link org.eclipse.jgit.revwalk.RevWalk#parseTag(AnyObjectId)}.
 	 */
+	@Deprecated
 	public Tag mapTag(final String refName, final ObjectId id) throws IOException {
 		final ObjectLoader or = openObject(id);
 		if (or == null)

org.eclipse.jgit/src/org/eclipse/jgit/lib/SymlinkTreeEntry.java

@@ -50,7 +50,14 @@ import java.io.IOException;
  * A tree entry representing a symbolic link.
  *
  * Note. Java cannot really handle these as file system objects.
+ *
+ * @deprecated To look up information about a single path, use
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#forPath(Repository, String, org.eclipse.jgit.revwalk.RevTree)}.
+ * To lookup information about multiple paths at once, use a
+ * {@link org.eclipse.jgit.treewalk.TreeWalk} and obtain the current entry's
+ * information from its getter methods.
  */
+@Deprecated
 public class SymlinkTreeEntry extends TreeEntry {
 	private static final long serialVersionUID = 1L;
 

org.eclipse.jgit/src/org/eclipse/jgit/lib/Tree.java

@@ -56,7 +56,14 @@ import org.eclipse.jgit.util.RawParseUtils;
 
 /**
  * A representation of a Git tree entry. A Tree is a directory in Git.
+ *
+ * @deprecated To look up information about a single path, use
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#forPath(Repository, String, org.eclipse.jgit.revwalk.RevTree)}.
+ * To lookup information about multiple paths at once, use a
+ * {@link org.eclipse.jgit.treewalk.TreeWalk} and obtain the current entry's
+ * information from its getter methods.
  */
+@Deprecated
 public class Tree extends TreeEntry implements Treeish {
 	private static final TreeEntry[] EMPTY_TREE = {};
 

org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeEntry.java

@@ -51,7 +51,14 @@ import org.eclipse.jgit.util.RawParseUtils;
 
 /**
  * This class represents an entry in a tree, like a blob or another tree.
+ *
+ * @deprecated To look up information about a single path, use
+ * {@link org.eclipse.jgit.treewalk.TreeWalk#forPath(Repository, String, org.eclipse.jgit.revwalk.RevTree)}.
+ * To lookup information about multiple paths at once, use a
+ * {@link org.eclipse.jgit.treewalk.TreeWalk} and obtain the current entry's
+ * information from its getter methods.
  */
+@Deprecated
 public abstract class TreeEntry implements Comparable {
 	/**
 	 * a flag for {@link TreeEntry#accept(TreeVisitor, int)} to visit only modified entries

org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeIterator.java

@@ -56,7 +56,10 @@ import org.eclipse.jgit.JGitText;
  * Default is to only visit leafs. An {@link Order} value can be supplied to
  * make the iteration include Tree nodes as well either before or after the
  * child nodes have been visited.
+ *
+ * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk} instead.
  */
+@Deprecated
 public class TreeIterator implements Iterator<TreeEntry> {
 
 	private Tree tree;

org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeVisitor.java

@@ -50,7 +50,10 @@ import java.io.IOException;
 /**
  * A TreeVisitor is invoked depth first for every node in a tree and is expected
  * to perform different actions.
+ *
+ * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk} instead.
  */
+@Deprecated
 public interface TreeVisitor {
 	/**
 	 * Visit to a tree node before child nodes are visited.

org.eclipse.jgit/src/org/eclipse/jgit/lib/TreeVisitorWithCurrentDirectory.java

@@ -51,7 +51,11 @@ import java.util.ArrayList;
 
 /**
  * Abstract TreeVisitor for visiting all files known by a Tree.
+ *
+ * @deprecated Use {@link org.eclipse.jgit.treewalk.TreeWalk} instead, with a
+ * {@link org.eclipse.jgit.treewalk.FileTreeIterator} as one of its members.
  */
+@Deprecated
 public abstract class TreeVisitorWithCurrentDirectory implements TreeVisitor {
 	private final ArrayList<File> stack = new ArrayList<File>(16);
 

org.eclipse.jgit/src/org/eclipse/jgit/lib/Treeish.java

@@ -48,7 +48,12 @@ import java.io.IOException;
 
 /**
  * Tree-ish is an interface for tree-like Git objects.
+ *
+ * @deprecated Use {@link org.eclipse.jgit.revwalk.RevWalk} to parse objects
+ * and resolve to a {@link org.eclipse.jgit.revwalk.RevTree}.  See the method
+ * {@link org.eclipse.jgit.revwalk.RevWalk#parseTree(AnyObjectId)}.
  */
+@Deprecated
 public interface Treeish {
 	/**
 	 * @return the id of this tree

org.eclipse.jgit/src/org/eclipse/jgit/lib/WorkDirCheckout.java

@@ -62,7 +62,10 @@ import org.eclipse.jgit.lib.GitIndex.Entry;
  * with the index (actually a tree too).
  *
  * Three-way merges are no performed. See {@link #setFailOnConflict(boolean)}.
+ *
+ * @deprecated Use org.eclipse.jgit.dircache.DirCacheCheckout.
  */
+@Deprecated
 public class WorkDirCheckout {
 	File root;
 

org.eclipse.jgit/src/org/eclipse/jgit/lib/WriteTree.java

@@ -56,7 +56,10 @@ import org.eclipse.jgit.errors.SymlinksNotSupportedException;
 /**
  * A tree visitor for writing a directory tree to the git object database. Blob
  * data is fetched from the files, not the cached blobs.
+ *
+ * @deprecated Use {@link org.eclipse.jgit.dircache.DirCache} instead.
  */
+@Deprecated
 public class WriteTree extends TreeVisitorWithCurrentDirectory {
 	private final ObjectWriter ow;
 

org.eclipse.jgit/src/org/eclipse/jgit/revwalk/RevWalk.java

@@ -603,6 +603,25 @@ public class RevWalk implements Iterable<RevCommit> {
 		return c;
 	}
 
+	/**
+	 * Locate a reference to a tag without loading it.
+	 * <p>
+	 * The tag may or may not exist in the repository. It is impossible to tell
+	 * from this method's return value.
+	 *
+	 * @param id
+	 *            name of the tag object.
+	 * @return reference to the tag object. Never null.
+	 */
+	public RevTag lookupTag(final AnyObjectId id) {
+		RevTag c = (RevTag) objects.get(id);
+		if (c == null) {
+			c = new RevTag(id);
+			objects.add(c);
+		}
+		return c;
+	}
+
 	/**
 	 * Locate a reference to any object without loading it.
 	 * <p>
@@ -708,6 +727,32 @@ public class RevWalk implements Iterable<RevCommit> {
 		return t;
 	}
 
+	/**
+	 * Locate a reference to an annotated tag and immediately parse its content.
+	 * <p>
+	 * Unlike {@link #lookupTag(AnyObjectId)} this method only returns
+	 * successfully if the tag object exists, is verified to be a tag, and was
+	 * parsed without error.
+	 *
+	 * @param id
+	 *            name of the tag object.
+	 * @return reference to the tag object. Never null.
+	 * @throws MissingObjectException
+	 *             the supplied tag does not exist.
+	 * @throws IncorrectObjectTypeException
+	 *             the supplied id is not a tag or an annotated tag.
+	 * @throws IOException
+	 *             a pack file or loose object could not be read.
+	 */
+	public RevTag parseTag(final AnyObjectId id) throws MissingObjectException,
+			IncorrectObjectTypeException, IOException {
+		RevObject c = parseAny(id);
+		if (!(c instanceof RevTag))
+			throw new IncorrectObjectTypeException(id.toObjectId(),
+					Constants.TYPE_TAG);
+		return (RevTag) c;
+	}
+
 	/**
 	 * Locate a reference to any object and immediately parse its headers.
 	 * <p>

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

@@ -404,7 +404,7 @@ public class TreeWalk {
 	 * @throws IOException
 	 *             a loose object or pack file could not be read.
 	 */
-	public int addTree(final ObjectId id) throws MissingObjectException,
+	public int addTree(final AnyObjectId id) throws MissingObjectException,
 			IncorrectObjectTypeException, CorruptObjectException, IOException {
 		return addTree(parserFor(id));
 	}