API: RevUtils and factory methods for IFileRevisions

Rename RevUtils to RevCommitUtils and publish as API in package
org.eclipse.egit.core.util. These operations are generally useful;
there is no need to keep them internal.

Also provide a new org.eclipse.egit.core.revisions.FileRevisionFactory
to give access to factory methods for creating IFileRevisions for files
in git commits or in the git index.

Bug: 573222
Change-Id: If25d3bc9952916405fe3a93f915a3166750155de
Signed-off-by: Thomas Wolf <thomas.wolf@paranor.ch>

12 files changed, 153 insertions, 34 deletions

diff --git a/org.eclipse.egit.core.test/src/org/eclipse/egit/core/test/RevUtilsTest.java b/org.eclipse.egit.core.test/src/org/eclipse/egit/core/test/RevUtilsTest.java
index e7ac6318be..35ad3a3278 100644
--- a/org.eclipse.egit.core.test/src/org/eclipse/egit/core/test/RevUtilsTest.java
+++ b/org.eclipse.egit.core.test/src/org/eclipse/egit/core/test/RevUtilsTest.java
@@ -16,7 +16,7 @@ import static org.junit.Assert.assertTrue;
 import java.io.IOException;
 import java.util.Collection;
 
-import org.eclipse.egit.core.RevUtils;
+import org.eclipse.egit.core.util.RevCommitUtils;
 import org.eclipse.jgit.lib.Constants;
 import org.eclipse.jgit.lib.Ref;
 import org.eclipse.jgit.lib.Repository;
@@ -70,7 +70,7 @@ public class RevUtilsTest extends GitTestCase {
 	private boolean isContainedInAnyRemoteRef(RevCommit commit) throws IOException {
 		Collection<Ref> remoteRefs = repository.getRefDatabase()
 				.getRefsByPrefix(Constants.R_REMOTES);
-		return RevUtils.isContainedInAnyRef(repository, commit, remoteRefs);
+		return RevCommitUtils.isContainedInAnyRef(repository, commit, remoteRefs);
 	}
 
 }
diff --git a/org.eclipse.egit.core/META-INF/MANIFEST.MF b/org.eclipse.egit.core/META-INF/MANIFEST.MF
index a915686c3e..5c0a3960d0 100644
--- a/org.eclipse.egit.core/META-INF/MANIFEST.MF
+++ b/org.eclipse.egit.core/META-INF/MANIFEST.MF
@@ -52,6 +52,7 @@ Export-Package: org.eclipse.egit.core;version="5.12.0";
    org.eclipse.mylyn.github.ui,
    org.eclipse.egit.core.junit",
  org.eclipse.egit.core.project;version="5.12.0";x-friends:="org.eclipse.egit.ui,org.eclipse.egit.ui.test,org.eclipse.egit.gitflow.ui",
+ org.eclipse.egit.core.revisions;version="5.12.0",
  org.eclipse.egit.core.securestorage;version="5.12.0";x-friends:="org.eclipse.egit.ui",
  org.eclipse.egit.core.settings;version="5.12.0",
  org.eclipse.egit.core.storage;version="5.12.0";
@@ -60,7 +61,8 @@ Export-Package: org.eclipse.egit.core;version="5.12.0";
    org.eclipse.jgit.lib,
    org.eclipse.core.resources",
  org.eclipse.egit.core.synchronize;version="5.12.0";x-friends:="org.eclipse.egit.ui,org.eclipse.egit.ui.test",
- org.eclipse.egit.core.synchronize.dto;version="5.12.0";x-friends:="org.eclipse.egit.ui"
+ org.eclipse.egit.core.synchronize.dto;version="5.12.0";x-friends:="org.eclipse.egit.ui",
+ org.eclipse.egit.core.util;version="5.12.0"
 Bundle-ActivationPolicy: lazy
 Bundle-RequiredExecutionEnvironment: JavaSE-1.8
 Import-Package: org.eclipse.core.net.proxy;bundle-version="[1.3.0,2.0.0)",
diff --git a/org.eclipse.egit.core/src/org/eclipse/egit/core/internal/storage/CommitFileRevision.java b/org.eclipse.egit.core/src/org/eclipse/egit/core/internal/storage/CommitFileRevision.java
index 80266183d9..411ad1d8db 100644
--- a/org.eclipse.egit.core/src/org/eclipse/egit/core/internal/storage/CommitFileRevision.java
+++ b/org.eclipse.egit.core/src/org/eclipse/egit/core/internal/storage/CommitFileRevision.java
@@ -75,8 +75,7 @@ public class CommitFileRevision extends GitFileRevision implements
 			locateBlobObjectId();
 		}
 		return new CommitBlobStorage(getRepository(), getGitPath(), blobId,
-				commit,
-				metadata);
+				commit, metadata);
 	}
 
 	@Override
diff --git a/org.eclipse.egit.core/src/org/eclipse/egit/core/revisions/FileRevisionFactory.java b/org.eclipse.egit.core/src/org/eclipse/egit/core/revisions/FileRevisionFactory.java
new file mode 100644
index 0000000000..3207bdac35
--- /dev/null
+++ b/org.eclipse.egit.core/src/org/eclipse/egit/core/revisions/FileRevisionFactory.java
@@ -0,0 +1,112 @@
+/*******************************************************************************
+ * Copyright (C) 2021 Thomas Wolf <thomas.wolf@paranor.ch> and others
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License 2.0
+ * which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+package org.eclipse.egit.core.revisions;
+
+import java.util.Objects;
+
+import org.eclipse.egit.core.internal.storage.GitFileRevision;
+import org.eclipse.jgit.dircache.DirCacheCheckout.CheckoutMetadata;
+import org.eclipse.jgit.dircache.DirCacheEntry;
+import org.eclipse.jgit.lib.ObjectId;
+import org.eclipse.jgit.lib.Repository;
+import org.eclipse.jgit.revwalk.RevCommit;
+import org.eclipse.team.core.history.IFileRevision;
+
+/**
+ * Factory methods to create {@link IFileRevision}s.
+ *
+ * @since 5.12
+ */
+public final class FileRevisionFactory {
+
+	private FileRevisionFactory() {
+		// No instantiation
+	}
+
+	/**
+	 * Obtains a file revision for a specific blob of an existing commit.
+	 *
+	 * @param repository
+	 *            the repository this commit was loaded out of, and that this
+	 *            file's blob should also be reachable through.
+	 * @param commit
+	 *            the commit the blob was identified to be within.
+	 * @param gitPath
+	 *            path within the commit's tree of the file.
+	 * @return revision implementation for this file in the given commit.
+	 */
+	public static IFileRevision inCommit(Repository repository,
+			RevCommit commit, String gitPath) {
+		return GitFileRevision.inCommit(repository, commit, gitPath, null,
+				null);
+	}
+
+	/**
+	 * Obtains a file revision for a specific blob of an existing commit. Use
+	 * this variant if you already know the blob ID and the
+	 * {@link CheckoutMetadata} for a JGit tree walk.
+	 *
+	 * @param repository
+	 *            the repository this commit was loaded out of, and that this
+	 *            file's blob should also be reachable through.
+	 * @param commit
+	 *            the commit the blob was identified to be within.
+	 * @param gitPath
+	 *            path within the commit's tree of the file.
+	 * @param blobId
+	 *            ID of the blob within the git repository
+	 * @param metadata
+	 *            Smudge filters and EOL stream type to apply when the content
+	 *            is to be gotten.
+	 * @return revision implementation for this file in the given commit.
+	 */
+	public static IFileRevision inCommit(Repository repository,
+			RevCommit commit, String gitPath, ObjectId blobId,
+			CheckoutMetadata metadata) {
+		return GitFileRevision.inCommit(repository, commit, gitPath,
+				Objects.requireNonNull(blobId),
+				Objects.requireNonNull(metadata));
+	}
+
+	/**
+	 * Obtains a file revision for an item in the git index.
+	 *
+	 * @param repository
+	 *            the repository which contains the index to use.
+	 * @param gitPath
+	 *            path of the resource in the index
+	 * @return revision implementation for the given path in the index
+	 */
+	public static IFileRevision inIndex(Repository repository,
+			String gitPath) {
+		return GitFileRevision.inIndex(repository, gitPath);
+	}
+
+	/**
+	 * Obtains a file revision for a particular stage of an item in the git
+	 * index.
+	 *
+	 * @param repository
+	 *            the repository which contains the index to use.
+	 * @param gitPath
+	 *            path of the resource in the index
+	 * @param stage
+	 *            stage of the index entry to get; use one of the
+	 *            {@link DirCacheEntry} constants (e.g.
+	 *            {@link DirCacheEntry#STAGE_2})
+	 * @return revision implementation for the given path in the index
+	 */
+	public static IFileRevision inIndex(Repository repository,
+			String gitPath, int stage) {
+		return GitFileRevision.inIndex(repository, gitPath, stage);
+	}
+
+}
diff --git a/org.eclipse.egit.core/src/org/eclipse/egit/core/synchronize/dto/GitSynchronizeData.java b/org.eclipse.egit.core/src/org/eclipse/egit/core/synchronize/dto/GitSynchronizeData.java
index 0f4c53efc2..ce2129f884 100644
--- a/org.eclipse.egit.core/src/org/eclipse/egit/core/synchronize/dto/GitSynchronizeData.java
+++ b/org.eclipse.egit.core/src/org/eclipse/egit/core/synchronize/dto/GitSynchronizeData.java
@@ -11,7 +11,7 @@
 package org.eclipse.egit.core.synchronize.dto;
 
 import static org.eclipse.core.runtime.Assert.isNotNull;
-import static org.eclipse.egit.core.RevUtils.getCommonAncestor;
+import static org.eclipse.egit.core.util.RevCommitUtils.getCommonAncestor;
 import static org.eclipse.jgit.lib.Constants.R_HEADS;
 
 import java.io.File;
diff --git a/org.eclipse.egit.core/src/org/eclipse/egit/core/RevUtils.java b/org.eclipse.egit.core/src/org/eclipse/egit/core/util/RevCommitUtils.java
index 3a6b4f3922..f0c30fa6e9 100644
--- a/org.eclipse.egit.core/src/org/eclipse/egit/core/RevUtils.java
+++ b/org.eclipse.egit.core/src/org/eclipse/egit/core/util/RevCommitUtils.java
@@ -9,7 +9,7 @@
  *
  * SPDX-License-Identifier: EPL-2.0
  *******************************************************************************/
-package org.eclipse.egit.core;
+package org.eclipse.egit.core.util;
 
 import java.io.File;
 import java.io.IOException;
@@ -32,20 +32,26 @@ import org.eclipse.jgit.util.RawParseUtils;
 
 /**
  * Utility class for obtaining Rev object instances.
+ *
+ * @since 5.12
  */
-public class RevUtils {
+public final class RevCommitUtils {
 
-	private RevUtils() {
-		// non instantiable utility class
+	private RevCommitUtils() {
+		// non-instantiable utility class
 	}
 
 	/**
 	 * Finds and returns instance of common ancestor commit for given two
-	 * commit's
+	 * commits.
 	 *
-	 * @param repo repository in which common ancestor should be searched, cannot be null
-	 * @param commit1 left commit id, cannot be null
-	 * @param commit2 right commit id, cannot be null
+	 * @param repo
+	 *            repository in which common ancestor should be searched, cannot
+	 *            be null
+	 * @param commit1
+	 *            left commit id, cannot be null
+	 * @param commit2
+	 *            right commit id, cannot be null
 	 * @return common ancestor for commit1 and commit2 parameters
 	 * @throws IOException
 	 */
@@ -68,10 +74,8 @@ public class RevUtils {
 			RevCommit result = rw.next();
 			if (result != null) {
 				rw.parseBody(result);
-				return result;
-			} else {
-				return null;
 			}
+			return result;
 		}
 	}
 
@@ -159,10 +163,11 @@ public class RevUtils {
 			ObjectId commitId, Collection<Ref> refs) throws IOException {
 		// It's likely that we don't have to walk commits at all, so
 		// check refs directly first.
-		for (Ref ref : refs)
-			if (commitId.equals(ref.getObjectId()))
+		for (Ref ref : refs) {
+			if (commitId.equals(ref.getObjectId())) {
 				return true;
-
+			}
+		}
 		final int skew = 24 * 60 * 60; // one day clock skew
 
 		try (RevWalk walk = new RevWalk(repo)) {
@@ -173,12 +178,12 @@ public class RevUtils {
 				// if commit is in the ref branch, then the tip of ref should be
 				// newer than the commit we are looking for. Allow for a large
 				// clock skew.
-				if (refCommit.getCommitTime() + skew < commit.getCommitTime())
+				if (refCommit.getCommitTime() + skew < commit.getCommitTime()) {
 					continue;
-
-				boolean contained = walk.isMergedInto(commit, refCommit);
-				if (contained)
+				}
+				if (walk.isMergedInto(commit, refCommit)) {
 					return true;
+				}
 			}
 			walk.dispose();
 		}
diff --git a/org.eclipse.egit.ui/META-INF/MANIFEST.MF b/org.eclipse.egit.ui/META-INF/MANIFEST.MF
index 0e432780f0..79b930cb7e 100644
--- a/org.eclipse.egit.ui/META-INF/MANIFEST.MF
+++ b/org.eclipse.egit.ui/META-INF/MANIFEST.MF
@@ -54,6 +54,7 @@ Import-Package: org.eclipse.egit.core;version="[5.12.0,5.13.0)",
  org.eclipse.egit.core.settings;version="[5.12.0,5.13.0)",
  org.eclipse.egit.core.synchronize;version="[5.12.0,5.13.0)",
  org.eclipse.egit.core.synchronize.dto;version="[5.12.0,5.13.0)",
+ org.eclipse.egit.core.util;version="[5.12.0,5.13.0)",
  org.eclipse.jgit.annotations;version="[5.12.0,5.13.0)",
  org.eclipse.jgit.api;version="[5.12.0,5.13.0)",
  org.eclipse.jgit.api.errors;version="[5.12.0,5.13.0)",
diff --git a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/CompareUtils.java b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/CompareUtils.java
index 98ff78d05b..299630923b 100644
--- a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/CompareUtils.java
+++ b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/CompareUtils.java
@@ -47,13 +47,13 @@ import org.eclipse.core.runtime.preferences.IEclipsePreferences;
 import org.eclipse.core.runtime.preferences.IEclipsePreferences.IPreferenceChangeListener;
 import org.eclipse.core.runtime.preferences.IEclipsePreferences.PreferenceChangeEvent;
 import org.eclipse.core.runtime.preferences.InstanceScope;
-import org.eclipse.egit.core.RevUtils;
 import org.eclipse.egit.core.attributes.Filtering;
 import org.eclipse.egit.core.internal.CompareCoreUtils;
 import org.eclipse.egit.core.internal.storage.GitFileRevision;
 import org.eclipse.egit.core.internal.storage.WorkingTreeFileRevision;
 import org.eclipse.egit.core.internal.storage.WorkspaceFileRevision;
 import org.eclipse.egit.core.project.RepositoryMapping;
+import org.eclipse.egit.core.util.RevCommitUtils;
 import org.eclipse.egit.ui.Activator;
 import org.eclipse.egit.ui.UIPreferences;
 import org.eclipse.egit.ui.internal.merge.GitCompareEditorInput;
@@ -229,7 +229,7 @@ public class CompareUtils {
 		ITypedElement ancestor = null;
 		RevCommit commonAncestor = null;
 		try {
-			commonAncestor = RevUtils.getCommonAncestor(db, commit1, commit2);
+			commonAncestor = RevCommitUtils.getCommonAncestor(db, commit1, commit2);
 		} catch (IOException e) {
 			Activator.logError(NLS.bind(UIText.CompareUtils_errorCommonAncestor,
 					commit1.getName(), commit2.getName()), e);
diff --git a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/actions/ReplaceConflictActionHandler.java b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/actions/ReplaceConflictActionHandler.java
index 5b14d0adfe..5d1bf414c4 100644
--- a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/actions/ReplaceConflictActionHandler.java
+++ b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/actions/ReplaceConflictActionHandler.java
@@ -29,7 +29,6 @@ import org.eclipse.core.runtime.IPath;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.core.runtime.jobs.ISchedulingRule;
 import org.eclipse.egit.core.EclipseGitProgressTransformer;
-import org.eclipse.egit.core.RevUtils;
 import org.eclipse.egit.core.internal.Utils;
 import org.eclipse.egit.core.internal.indexdiff.IndexDiffCache;
 import org.eclipse.egit.core.internal.indexdiff.IndexDiffCacheEntry;
@@ -39,6 +38,7 @@ import org.eclipse.egit.core.internal.job.RuleUtil;
 import org.eclipse.egit.core.internal.util.ResourceUtil;
 import org.eclipse.egit.core.op.DiscardChangesOperation;
 import org.eclipse.egit.core.op.DiscardChangesOperation.Stage;
+import org.eclipse.egit.core.util.RevCommitUtils;
 import org.eclipse.egit.core.op.IEGitOperation;
 import org.eclipse.egit.ui.Activator;
 import org.eclipse.egit.ui.JobFamilies;
@@ -211,7 +211,7 @@ public abstract class ReplaceConflictActionHandler
 			}
 		} else {
 			try {
-				RevCommit commit = RevUtils.getTheirs(repository);
+				RevCommit commit = RevCommitUtils.getTheirs(repository);
 				if (commit != null) {
 					element.setText(formatCommitLabel(
 							UIText.ReplaceWithOursTheirsMenu_TheirsWithCommitLabel,
diff --git a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/dialogs/CommitMessageComponent.java b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/dialogs/CommitMessageComponent.java
index 3fbc30002f..f6eee65811 100644
--- a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/dialogs/CommitMessageComponent.java
+++ b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/dialogs/CommitMessageComponent.java
@@ -27,9 +27,9 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.regex.Pattern;
 
-import org.eclipse.egit.core.RevUtils;
 import org.eclipse.egit.core.internal.gerrit.GerritUtil;
 import org.eclipse.egit.core.settings.GitSettings;
+import org.eclipse.egit.core.util.RevCommitUtils;
 import org.eclipse.egit.ui.Activator;
 import org.eclipse.egit.ui.CommitMessageWithCaretPosition;
 import org.eclipse.egit.ui.UIPreferences;
@@ -775,7 +775,7 @@ public class CommitMessageComponent {
 		try {
 			Collection<Ref> refs = repository.getRefDatabase()
 					.getRefsByPrefix(Constants.R_REMOTES);
-			return RevUtils.isContainedInAnyRef(repository, commit, refs);
+			return RevCommitUtils.isContainedInAnyRef(repository, commit, refs);
 		} catch (IOException e) {
 			// The result only affects a warning, so pretend there was no
 			// problem.
diff --git a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/merge/GitMergeEditorInput.java b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/merge/GitMergeEditorInput.java
index 053c0ca319..0f6b000b01 100644
--- a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/merge/GitMergeEditorInput.java
+++ b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/merge/GitMergeEditorInput.java
@@ -35,11 +35,11 @@ import org.eclipse.core.runtime.IPath;
 import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.core.runtime.Path;
 import org.eclipse.egit.core.RepositoryUtil;
-import org.eclipse.egit.core.RevUtils;
 import org.eclipse.egit.core.internal.CompareCoreUtils;
 import org.eclipse.egit.core.internal.CoreText;
 import org.eclipse.egit.core.internal.storage.GitFileRevision;
 import org.eclipse.egit.core.internal.util.ResourceUtil;
+import org.eclipse.egit.core.util.RevCommitUtils;
 import org.eclipse.egit.ui.Activator;
 import org.eclipse.egit.ui.internal.CompareUtils;
 import org.eclipse.egit.ui.internal.UIText;
@@ -162,7 +162,7 @@ public class GitMergeEditorInput extends CompareEditorInput {
 			// get the "right" side
 			final RevCommit rightCommit;
 			try {
-				rightCommit = RevUtils.getTheirs(repo, rw);
+				rightCommit = RevCommitUtils.getTheirs(repo, rw);
 			} catch (IOException e) {
 				throw new InvocationTargetException(e);
 			}
diff --git a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/staging/ReplaceConflictMenu.java b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/staging/ReplaceConflictMenu.java
index 695e7a96c7..cd91085dfe 100644
--- a/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/staging/ReplaceConflictMenu.java
+++ b/org.eclipse.egit.ui/src/org/eclipse/egit/ui/internal/staging/ReplaceConflictMenu.java
@@ -15,8 +15,8 @@ import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
 
-import org.eclipse.egit.core.RevUtils;
 import org.eclipse.egit.core.op.DiscardChangesOperation.Stage;
+import org.eclipse.egit.core.util.RevCommitUtils;
 import org.eclipse.egit.ui.Activator;
 import org.eclipse.egit.ui.internal.UIText;
 import org.eclipse.egit.ui.internal.actions.ReplaceConflictActionHandler;
@@ -74,7 +74,7 @@ public class ReplaceConflictMenu extends CompoundContributionItem {
 		}
 		RevCommit theirs = null;
 		try {
-			theirs = RevUtils.getTheirs(repo);
+			theirs = RevCommitUtils.getTheirs(repo);
 		} catch (IOException e) {
 			Activator.logError(e.getLocalizedMessage(), e);
 		}