Deprecate checkoutEntry without ObjectReader

Callers should manage the ObjectReader, as this allows the JGit library to cache
context relevant information across files checked out at the same time. If the
caller only has one file to checkout, it should still explicitly manage the life
span of the ObjectReader.

Change-Id: Ib57fba6cb4b774ccff8c416ef4d32e2b390f16a9

org.eclipse.jgit.test/tst/org/eclipse/jgit/treewalk/FileTreeIteratorTest.java

@@ -291,13 +291,13 @@ public class FileTreeIteratorTest extends RepositoryTestCase {
 		// Modify previously committed DirCacheEntry and write it back to disk
 		DirCacheEntry dce = db.readDirCache().getEntry("symlink");
 		dce.setFileMode(FileMode.SYMLINK);
-		DirCacheCheckout.checkoutEntry(db, f, dce);
+		ObjectReader objectReader = db.newObjectReader();
+		DirCacheCheckout.checkoutEntry(db, f, dce, objectReader);
 
 		FileTreeIterator fti = new FileTreeIterator(trash, db.getFS(), db
 				.getConfig().get(WorkingTreeOptions.KEY));
 		while (!fti.getEntryPathString().equals("symlink"))
 			fti.next(1);
-		ObjectReader objectReader = db.newObjectReader();
 		assertFalse(fti.isModified(dce, false, objectReader));
 		objectReader.release();
 	}

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

@@ -1163,7 +1163,9 @@ public class DirCacheCheckout {
 	 * @param entry
 	 *            the entry containing new mode and content
 	 * @throws IOException
+	 * @deprecated Use the overloaded form that accepts {@link ObjectReader}.
 	 */
+	@Deprecated
 	public static void checkoutEntry(final Repository repository, File f,
 			DirCacheEntry entry) throws IOException {
 		ObjectReader or = repository.newObjectReader();