Deprecate getRevision and getPredecessorRevision

README.md

@@ -62,10 +62,10 @@ VCSEngine vcs = ...
 
 for (RevisionRange range : vcs) {
     // Path to the root of the currently checked out revivion.
-    range.getRevision().getOutput();
+    range.getCurrent().getOutput();
 
     // Returns the files of the currenlty checked out revision as list.
-    range.getRevision().getFiles();
+    range.getCurrent().getFiles();
 }
 ```
 

libvcs4j-api/src/main/java/de/unibremen/informatik/st/libvcs4j/RevisionRange.java

@@ -17,9 +17,9 @@
 
 /**
  * This class represents the state transition between two revisions. The "from"
- * revision (if any) is available with {@link #getPredecessorRevision()}. The
- * "to" revision is available with {@link #getRevision()}.
- *
+ * revision (if any) is available with {@link #getPrevious()}. The "to"
+ * revision is available with {@link #getCurrent()}.
+ * <p>
  * A single range may subsume several commits to merge commits on, for
  * instance, a monthly basis.
  */
@@ -37,11 +37,38 @@ public interface RevisionRange extends VCSModelElement {
 
 	/**
 	 * Returns the "to" revision the file changes of this range belong to.
+	 * @deprecated
+	 * Use {@link #getCurrent()} instead.
 	 *
 	 * @return
 	 * 		The "to" revision the file changes of this range belong to.
 	 */
-	Revision getRevision();
+	@Deprecated
+	default Revision getRevision() {
+		return getCurrent();
+	}
+
+	/**
+	 * Returns the "to" revision the file changes of this range belong to.
+	 *
+	 * @return
+	 * 		The "to" revision the file changes of this range belong to.
+	 */
+	Revision getCurrent();
+
+	/**
+	 * Returns the "from" revision the file changes of this range belong to.
+	 * @deprecated
+	 * Use {@link #getPrevious()} instead.
+	 *
+	 * @return
+	 * 		The "from" revision the file changes of this range belong to or an
+	 * 		empty {@link Optional} if this is the first range.
+	 */
+	@Deprecated
+	default Optional<Revision> getPredecessorRevision() {
+		return getPrevious();
+	}
 
 	/**
 	 * Returns the "from" revision the file changes of this range belong to.
@@ -50,13 +77,12 @@ public interface RevisionRange extends VCSModelElement {
 	 * 		The "from" revision the file changes of this range belong to or an
 	 * 		empty {@link Optional} if this is the first range.
 	 */
-	Optional<Revision> getPredecessorRevision();
+	Optional<Revision> getPrevious();
 
 	/**
-	 * Returns the commits that have been applied to
-	 * {@link #getPredecessorRevision()} so that {@link #getRevision()} results
-	 * from it. The order of the returned list is from oldest to latest.
-	 * Contains at least one commit.
+	 * Returns the commits that have been applied to {@link #getPrevious()} so
+	 * that {@link #getCurrent()} results from it. The order of the returned
+	 * list is from oldest to latest. Contains at least one commit.
 	 *
 	 * @return
 	 * 		The list of commits.
@@ -77,10 +103,9 @@ default Commit getLatestCommit() {
 	}
 
 	/**
-	 * Returns all files that have changed between
-	 * {@link #getPredecessorRevision()} and {@link #getRevision()}. The
-	 * default implementation, if necessary, merges the file changes of all
-	 * commits listed in {@link #getCommits()}.
+	 * Returns all files that have changed between {@link #getPrevious()} and
+	 * {@link #getCurrent()}. The default implementation, if necessary, merges
+	 * the file changes of all commits listed in {@link #getCommits()}.
 	 *
 	 * @return
 	 * 		The list of file changes.
@@ -178,8 +203,8 @@ default List<FileChange> getFileChanges() {
 			// Postprocessing: Replace accumulated file changes such that the
 			// revisions of the referenced files match with the predecessor and
 			// successor revision of this range.
-			final Revision predRev = getPredecessorRevision().orElse(null);
-			final Revision rev = getRevision();
+			final Revision predRev = getPrevious().orElse(null);
+			final Revision rev = getCurrent();
 			final VCSEngine engine = getVCSEngine();
 			final VCSModelFactory factory = engine.getModelFactory();
 			final ListIterator<FileChange> it = accum.listIterator();
@@ -301,7 +326,7 @@ default List<FileChange> getFileChangesBySuffix(final String suffix) {
 	 * {@code prefix}.
 	 *
 	 * You may use this method to analyze file changes affecting a certain
-	 * directory (and its sub-directories) only. For instance, call
+	 * directory (and its subdirectories) only. For instance, call
 	 * {@code getFileChangesByPrefix("src/main/java")} to get only the file
 	 * changes affecting files located in "src/main/java".
 	 *
@@ -378,15 +403,15 @@ default List<Issue> getIssues() {
 	 * Returns whether this range is the first one. That is, there is no
 	 * predecessor revision and, consequently, all changes returned by
 	 * {@link #getFileChanges()} are additions. The default implementation
-	 * simply checks whether {@link #getPredecessorRevision()} returns an empty
+	 * simply checks whether {@link #getPrevious()} returns an empty
 	 * {@link Optional}.
 	 *
 	 * @return
 	 * 		{@code true} if this range is the first one, {@code false}
 	 * 		otherwise.
 	 */
 	default boolean isFirst() {
-		return getPredecessorRevision().isEmpty();
+		return getPrevious().isEmpty();
 	}
 
 	/**
@@ -416,17 +441,16 @@ default void ifNotFirst(final Consumer<RevisionRange> action) {
 	/**
 	 * Merges this range into {@code predecessor} and returns a new instance
 	 * that represents the state transition from
-	 * {@code predecessor.getPredecessorRevision()} to
-	 * {@code this.getRevision()}. The commits of {@code predecessor} and
-	 * {@code this} are combined such that the commits of {@code this} are
-	 * applied onto the commits of {@code predecessor}.
+	 * {@code predecessor.getPrevious()} to {@code this.getCurrent()}. The
+	 * commits of {@code predecessor} and {@code this} are combined such that
+	 * the commits of {@code this} are applied onto the commits of
+	 * {@code predecessor}.
 	 *
 	 * @param predecessor
 	 * 		The predecessor range to merge this range into.
 	 * @return
 	 * 		A new revision range representing the state transition from
-	 * 		{@code predecessor.getPredecessorRevision()} to
-	 * 		{@code this.getRevision()}.
+	 * 		{@code predecessor.getPrevious()} to {@code this.getCurrent()}.
 	 * @throws NullPointerException
 	 * 		If {@code predecessor} is {@code null}.
 	 */
@@ -437,8 +461,7 @@ default RevisionRange merge(final RevisionRange predecessor)
 		final List<Commit> commits = predecessor.getCommits();
 		commits.addAll(getCommits());
 		return engine.getModelFactory().createRevisionRange(getOrdinal(),
-				getRevision(),
-				predecessor.getPredecessorRevision().orElse(null), commits,
-				getVCSEngine());
+				getCurrent(), predecessor.getPrevious().orElse(null),
+				commits, getVCSEngine());
 	}
 }

libvcs4j-api/src/main/java/de/unibremen/informatik/st/libvcs4j/VCSModelFactory.java

@@ -392,28 +392,28 @@ public String toString() {
 	 * fallback. {@code null} values are filtered out.
 	 *
 	 * @param ordinal
-	 * 		The ordinal of the revision range to create.
-	 * @param revision
-	 * 		The revision of the revision range to create.
-	 * @param predecessorRevision
-	 * 		The predecessor revision of the revision range to create.
+	 * 		The ordinal of the range to create.
+	 * @param current
+	 * 		The current revision of the range to create.
+	 * @param previous
+	 * 		The previous revision of the range to create.
 	 * @param commits
-	 * 		The commits of the revision range to create.
+	 * 		The commits of the range to create.
 	 * @param engine
-	 * 		The engine of the revision range to create.
+	 * 		The engine of the range to create.
 	 * @return
 	 * 		The created {@link RevisionRange} instance.
 	 * @throws NullPointerException
-	 * 		If {@code revision} or {@code engine} is {@code null}.
+	 * 		If {@code current} or {@code engine} is {@code null}.
 	 * @throws IllegalArgumentException
 	 * 		If {@code ordinal < 1} or if {@code commits} is empty.
 	 */
 	default RevisionRange createRevisionRange(final int ordinal,
-			final Revision revision, final Revision predecessorRevision,
+			final Revision current, final Revision previous,
 			final List<Commit> commits, final VCSEngine engine)
 			throws NullPointerException, IllegalArgumentException {
 		Validate.isPositive(ordinal, "Ordinal (%d) < 1");
-		Validate.notNull(revision);
+		Validate.notNull(current);
 		Validate.notNull(engine);
 		final List<Commit> _commits = createCopy(commits);
 		Validate.notEmpty(_commits, "There must be at least one commit");
@@ -424,13 +424,13 @@ public int getOrdinal() {
 			}
 
 			@Override
-			public Revision getRevision() {
-				return revision;
+			public Revision getCurrent() {
+				return current;
 			}
 
 			@Override
-			public Optional<Revision> getPredecessorRevision() {
-				return Optional.ofNullable(predecessorRevision);
+			public Optional<Revision> getPrevious() {
+				return Optional.ofNullable(previous);
 			}
 
 			@Override
@@ -446,10 +446,9 @@ public VCSEngine getVCSEngine() {
 			@Override
 			public String toString() {
 				return String.format("RevisionRange(ordinal=%d, " +
-						"revision=%s, predecessorRevision=%s, commits=%d, " +
-						"first=%b)", getOrdinal(), getRevision().getId(),
-						getPredecessorRevision().map(Revision::getId)
-								.orElse(null),
+						"current=%s, previous=%s, commits=%d, " +
+						"first=%b)", getOrdinal(), getCurrent().getId(),
+						getPrevious().map(Revision::getId).orElse(null),
 						getCommits().size(), isFirst());
 			}
 		};

libvcs4j-api/src/test/java/de/unibremen/informatik/st/libvcs4j/RevisionRangeTest.java

@@ -105,7 +105,7 @@ public void testMergeAddRelocateRemove() {
         RevisionRange range1 = spy(RevisionRange.class);
         when(range1.getCommits()).thenReturn(Arrays.asList(c1, c2));
         when(range1.getVCSEngine()).thenReturn(engine);
-        when(range1.getRevision()).thenReturn(rev3);
+        when(range1.getCurrent()).thenReturn(rev3);
         assertThat(range1.getFileChanges())
                 .hasSize(1)
                 .first()
@@ -185,8 +185,8 @@ public void testRelocateRelocateRelocate() {
         RevisionRange range1 = spy(RevisionRange.class);
         when(range1.getCommits()).thenReturn(Arrays.asList(c2, c3));
         when(range1.getVCSEngine()).thenReturn(vcs);
-        when(range1.getPredecessorRevision()).thenReturn(Optional.of(rev1));
-        when(range1.getRevision()).thenReturn(rev3);
+        when(range1.getPrevious()).thenReturn(Optional.of(rev1));
+        when(range1.getCurrent()).thenReturn(rev3);
         assertThat(range1.getFileChanges())
                 .hasSize(1)
                 .first()
@@ -204,8 +204,8 @@ public void testRelocateRelocateRelocate() {
         RevisionRange range2 = spy(RevisionRange.class);
         when(range2.getCommits()).thenReturn(Arrays.asList(c2, c3, c4));
         when(range2.getVCSEngine()).thenReturn(vcs);
-        when(range2.getPredecessorRevision()).thenReturn(Optional.of(rev1));
-        when(range2.getRevision()).thenReturn(rev4);
+        when(range2.getPrevious()).thenReturn(Optional.of(rev1));
+        when(range2.getCurrent()).thenReturn(rev4);
         assertThat(range2.getFileChanges())
                 .hasSize(1)
                 .first()
@@ -260,8 +260,8 @@ public void testAddAdd() {
         RevisionRange range = spy(RevisionRange.class);
         when(range.getCommits()).thenReturn(Arrays.asList(c1, c2));
         when(range.getVCSEngine()).thenReturn(vcs);
-        when(range.getPredecessorRevision()).thenReturn(Optional.empty());
-        when(range.getRevision()).thenReturn(rev2);
+        when(range.getPrevious()).thenReturn(Optional.empty());
+        when(range.getCurrent()).thenReturn(rev2);
         assertThat(range.getFileChanges()).hasSize(2);
 
         assertThat(range.getFileChanges().get(0).getType())
@@ -334,7 +334,7 @@ public void testUnrelated() {
         RevisionRange range = spy(RevisionRange.class);
         when(range.getCommits()).thenReturn(Arrays.asList(c1, c2, c3));
         when(range.getVCSEngine()).thenReturn(engine);
-        when(range.getRevision()).thenReturn(rev3);
+        when(range.getCurrent()).thenReturn(rev3);
         assertThat(range.getFileChanges().get(0).getType())
                 .isEqualTo(r1.getType());
         assertThat(range.getFileChanges().get(1).getType())
@@ -388,15 +388,15 @@ public void isFirstWithPredecessor() {
         Revision rev = mock(Revision.class);
 
         RevisionRange range = mock(RevisionRange.class);
-        when(range.getPredecessorRevision()).thenReturn(Optional.of(rev));
+        when(range.getPrevious()).thenReturn(Optional.of(rev));
         when(range.isFirst()).thenCallRealMethod();
         assertThat(range.isFirst()).isFalse();
     }
 
     @Test
     public void isFirstWithoutPredecessor() {
         RevisionRange range = mock(RevisionRange.class);
-        when(range.getPredecessorRevision()).thenReturn(Optional.empty());
+        when(range.getPrevious()).thenReturn(Optional.empty());
         when(range.isFirst()).thenCallRealMethod();
         assertThat(range.isFirst()).isTrue();
     }

libvcs4j-tools/src/main/java/de/unibremen/informatik/st/libvcs4j/mapping/Mapping.java

@@ -275,7 +275,7 @@ public Result<T> map(
 		log.info("Mapping {}/{} elements", previous.size(), mappables.size());
 		final List<Mappable<T>> current = filterOutNull(mappables);
 		validateSameRevisions(current);
-		validateHaveRevision(current, range.getRevision());
+		validateHaveRevision(current, range.getCurrent());
 
 		final IdentityHashMap<Mappable<T>, Mappable<T>> bySignature =
 				mapBySignature(previous, current);
@@ -320,10 +320,10 @@ public Result<T> map(
 	 * @throws NullPointerException
 	 * 		If any of the given arguments is {@code null}.
 	 * @throws IllegalArgumentException
-	 * 		If {@code range} has no predecessor (see
-	 * 		{@link RevisionRange#getPredecessorRevision()}), if {@code from} or
-	 * 		{@code to} contain a mappable without a range, or if {@code from}
-	 * 		or {@code to} contain a mappable that does not correspond to
+	 * 		If {@code range} has no predecessor revision (see
+	 * 		{@link RevisionRange#getPrevious()}), if {@code from} or
+	 * 		{@code to} contains a mappable without a range, or if {@code from}
+	 * 		or {@code to} contains a mappable that does not correspond to
 	 * 		{@code range}.
 	 * @throws IOException
 	 * 		If an error occurred while applying changes (see
@@ -335,7 +335,7 @@ public Result<T> map(
 			@NonNull final RevisionRange range) throws IOException {
 		final List<Mappable<T>> backup = new ArrayList<>(previous);
 		try {
-			final Revision preRev = range.getPredecessorRevision()
+			final Revision preRev = range.getPrevious()
 					.orElseThrow(() -> new IllegalArgumentException(
 							"Revision range without predecessor"));
 			final List<Mappable<T>> prev = filterOutNull(from);
@@ -451,7 +451,7 @@ private static boolean haveRevision(
 		final IdentityHashMap<Mappable<T>, Mappable<T>> fromToUpdated =
 				new IdentityHashMap<>();
 		from.forEach(f -> fromToUpdated.put(f, f));
-		final Optional<Revision> preRev = range.getPredecessorRevision();
+		final Optional<Revision> preRev = range.getPrevious();
 		final boolean applyChanges = preRev.isPresent()
 				&& haveRevision(from, preRev.get());
 		if (applyChanges) {
@@ -482,7 +482,7 @@ private static boolean haveRevision(
 	private static <T> Optional<Mappable<T>> applyChanges(
 			@NonNull final Mappable<T> mappable,
 			@NonNull final RevisionRange revRange) throws IOException {
-		final Revision revision = revRange.getRevision();
+		final Revision revision = revRange.getCurrent();
 		final List<VCSFile.Range> ranges = new ArrayList<>();
 		for (final VCSFile.Range range : mappable.getRanges()) {
 			// Never returns an addition.

libvcs4j-tools/src/main/java/de/unibremen/informatik/st/libvcs4j/spoon/Environment.java

@@ -39,13 +39,13 @@ public class Environment {
 	private final RevisionRange revisionRange;
 
 	/**
-	 * Shortcut for {@code getRevisionRange().getRevision()}.
+	 * Shortcut for {@code getRevisionRange().getCurrent()}.
 	 *
 	 * @return
-	 * 		The revision returned by {@code getRevisionRange().getRevision()}.
+	 * 		The revision returned by {@code getRevisionRange().getCurrent()}.
 	 */
 	public Revision getRevision() {
-		return revisionRange.getRevision();
+		return revisionRange.getCurrent();
 	}
 
 	/**
@@ -79,7 +79,7 @@ public List<VCSFile> findReferencedFiles(@NonNull final VCSFile file) {
 		// Make VCS file paths canonical.
 		final Map<VCSFile, Path> fileToCPath = new IdentityHashMap<>();
 		try {
-			final Revision revision = revisionRange.getRevision();
+			final Revision revision = revisionRange.getCurrent();
 			for (final VCSFile vFile : revision.getFiles()) {
 				final Path cPath = vFile.toFile().getCanonicalFile().toPath();
 				fileToCPath.put(vFile, cPath);

libvcs4j-tools/src/main/java/de/unibremen/informatik/st/libvcs4j/spoon/EnvironmentBuilder.java

@@ -70,7 +70,7 @@ public Optional<Environment> getEnvironment() {
 	 */
 	public Environment update(@NonNull final RevisionRange range)
 			throws BuildException {
-		final Revision revision = range.getRevision();
+		final Revision revision = range.getCurrent();
 		log.info("Building Spoon model for revision {}", revision.getId());
 		log.info("Enable auto imports: {}", autoImports);
 		log.info("Enable comments: {}", comments);