Merge branch 'master' into B1

# Conflicts:
#	build.gradle

Author: host6

.travis.yml

@@ -0,0 +1,12 @@
+language: java
+before_install:
+ - chmod +x gradlew
+before_cache:
+  - rm -f  $HOME/.gradle/caches/modules-2/modules-2.lock
+  - rm -fr $HOME/.gradle/caches/*/plugin-resolution/
+cache:
+  directories:
+    - $HOME/.gradle/caches/
+    - $HOME/.gradle/wrapper/
+after_success:
+  - ./gradlew jacocoTestReport coveralls

README.md

@@ -1,10 +1,12 @@
-[![Release](https://jitpack.io/v/scm4j/scm4j-vcs-api.svg)](https://jitpack.io/#scm4j/scm4j-vcs-api)	
+[![Release](https://jitpack.io/v/scm4j/scm4j-vcs-api.svg)](https://jitpack.io/#scm4j/scm4j-vcs-api)
+[![Build Status](https://travis-ci.org/scm4j/scm4j-ai.svg?branch=master)](https://travis-ci.org/scm4j/scm4j-ai)
+[![Coverage Status](https://coveralls.io/repos/github/scm4j/scm4j-vcs-api/badge.svg?branch=master)](https://coveralls.io/github/scm4j/scm4j-vcs-api?branch=master) 
 
 # Overview
 scm4j-vcs-api is set of base classes and interfaces to build VCS support (Git, SVN, etc) libraries which exposes basic vcs-related operations: merge, branch create etc.
 scm4j-vcs-api provides:
 - A simple interface to implement basic VCS-related operations
-- Set of functional tests which are common to each VCS implementation. Functional tests for a certain VCS implementation are done by implementing few abstract methods of base test class. Implemented in [scm4j-vcs-test](https://github.com/scm4j/scm4j-vcs-test)
+- Set of functional tests wchich are common to each VCS implementation. Functional tests for a certain VCS implementation are done by implementing few abstract methods of base test class. Implemented in [scm4j-vcs-test](https://github.com/scm4j/scm4j-vcs-test)
 - Working copy management for operations which must be executed on local file system
 
 # Terms
@@ -36,6 +38,8 @@ scm4j-vcs-api provides:
 	- The latest commit or state of a branch
 - Master Branch
 	- "Master" for Git, "Trunk" for SVN etc
+- `VCSTag`, Tag
+    - Contains tag name, tag log message, tag author and `VCSCommit` instance which represents the tagged commit
 
 # Using VCS interface
 IVCS interface consists of few basic vcs functions.
@@ -64,27 +68,38 @@ Note: null passed as a branch name is considered as Master Branch. Any non-null
 	- `fileRelativePath` is a path to file within `branchName` branch 
 	- The Head file state is used
 	- Use `String getFileContent(String branchName, String fileRelativePath)` overload to use UTF-8 encoding by default
-- `String setFileContent(String branchName, String filePath, String content, String commitMessage)`
+- `VCSCommit setFileContent(String branchName, String filePath, String content, String commitMessage)`
 	- Rewrites a file with path `filePath` within branch `branchName` with content `content` and applies `commitMessage` message to commit
 	- Creates the file and its parent folders if doesn't exists
-	- Returns commit id (hash, revision number etc)
 - `List<VCSDiffEntry> getBranchesDiff(String srcBranchName, String destBranchName)`
 	- Returns list of `VCSDiffEntry` showing what was made within branch `srcBranchName` relative to branch `destBranchName`
-	- Note: result is a commit which would be made on merging the branch `srcBranchName` into `destBranchName`
+	- Note: result could be considered as a commit which would be made on merging the branch `srcBranchName` into `destBranchName`
 - `Set<String> getBranches()`
 	- Returns list of names of all branches. Branches here are considered as user-created branches and Master Branch. I.e. any branch for Git, "Trunk" and any branch within "Branches" branch (not "Tags" branches) for SVN etc
 - `List<String> getCommitMessages(Sting branchName, Integer limit)`
 	- Returns list of commit messages of branch `branchName` limited by `limit` in descending order
 - `String getVCSTypeString`
 	- Returns short name of current IVCS implementation: "git", "svn" etc
-- `String removeFile(String branchName, String filePath, String commitMessage)`
-	- Removes the file located by `filePath` within branch `branchName`. Operation is executed as separate commit with `commitMessage` message attached. Note: filePath = "folder\file.txt" -> file.txt is removed, folder is kept
-	- Returns commit id (hash, revision number etc)
-- `List<VCSCommit> getCommitsRange(String branchName, String afterCommitId, String untilCommitId);`
-	- Returns ordered list of all commits located between commits specified by `aftercommitId` and `untilCommitId` within branch `branchName` 
-	- If `aftercommitId` is null then all commits until commit specified by `untilCommitId` are fetched 
-	- If `untilCommitId` is null then all commits after commit specified by `afterCommitId` are fetched  
-
+- `VCSCommit removeFile(String branchName, String filePath, String commitMessage)`
+	- Removes the file with path `filePath` within branch `branchName`. Operation is executed as separate commit with `commitMessage` message attached. Note: filePath = "folder\file.txt" -> file.txt is removed, folder is kept
+- `List<VCSCommit> getCommitsRange(String branchName, String firstCommitId, String untilCommitId)`
+	- Returns ordered list of all commits located between commits specified by `firstCommitId` and `untilCommitId` inclusively within branch `branchName` 
+	- If `firstCommitId` is null then all commits until commit specified by `untilCommitId` inclusively are fetched 
+	- If `untilCommitId` is null then all commits starting from commit specified by `firstCommitId` are fetched
+- `List<VCSCommit> getCommitsRange(String branchName, String firstCommitId, WalkDirection direction, int limit)`
+    - Returns ordered list of `limit` commits (0 is unlimited) starting from commit specified by `firstCommitId` in direction specified by `direction`
+    - If `firstCommitId` is null then commits are starting at branch `branchName` first commit (for ASC direction) or at head of branch (for DESC direction)
+- `VCSCommit getHeadCommit(String branchName)`
+    - Returns `VCSCommit` instance pointing to the head (last) commit of the branch `branchName`  
+- `Boolean fileExists(String branchName, String filePath)`
+    - Returns true if the file with path `filePath` exists in repository in branch `branchName`, false otherwise
+- `VCSTag createTag(String branchName, String tagName, String tagMessage) throws EVCSTagExists`
+    - Creates a tag named `tagName` with log message `tagMessage` on a Head of branch `branchName`
+- `List<VCSTag> getTags()`
+    - Returns list of all tags
+- `VCSTag getLastTag()`
+    - Returns the last created tag
+    
 # Using Locked Working Copy
 Let's assume we developing a multiuser server which has ability to merge branches of user's repositories. So few users could request to merge theirs branches of different repositories simultaneously. For example, Git merge operation consists of few underlying operations (check in\out, merge itself, push) which must be executed on a local file system in a certain folder. So we have following requirements:
 - The simple way to allocate place for vcs operations execution
@@ -186,7 +201,7 @@ Lock way: `new FileOutputStream(lockFile, false).getChannel.lock()`
 	- Throw exceptions from scm4j.vcs.api.exceptions package. Abstract Test checks throwning of these exceptions.
 - Implement functional tests
 	- Create VCSAbstractTest subclass within test package, implement all abstract methods
-	- Normally test class should not include any test, just @After\@Before methods. All necessary functional testing is implemented within VCSAbstractTest
+	- Normally test class should not include any test, just @After and @Before methods. All necessary functional testing is implemented within VCSAbstractTest
 	- See [scm4j-vcs-test](https://github.com/scm4j/scm4j-vcs-test) for details
 - Example of gradle usage to export IVCS implementation, its sources and javadoc as separate single JARs:
 ```gradle

build.gradle

@@ -1,21 +1,36 @@
+plugins {
+	id 'jacoco'
+	id 'com.github.kt3k.coveralls' version '2.8.1'
+}
+
 apply plugin: 'java'
 apply plugin: 'maven'
+apply plugin: 'eclipse'
+apply plugin: 'idea'
 
 sourceCompatibility = JavaVersion.VERSION_1_7
 targetCompatibility = JavaVersion.VERSION_1_7
 
 group = 'org.scm4j'
-version = '2.0'
+version = '3.0'
+
+jacocoTestReport {
+	reports {
+		xml.enabled = true // coveralls plugin depends on xml format report
+		html.enabled = true
+	}
+}
 
 repositories {
         mavenCentral()
 }
 
 dependencies {
-        testCompile 'junit:junit:4.12'
-        testCompile 'org.mockito:mockito-core:2.0.62-beta'
-
-        compile 'commons-io:commons-io:2.5'
+	testCompile 'junit:junit:4.12'
+	testCompile 'org.mockito:mockito-core:2.0.62-beta'
+	testCompile 'nl.jqno.equalsverifier:equalsverifier:2.3'
+        
+	compile 'commons-io:commons-io:2.5'
 }
 
 task sourcesJar(type: Jar, dependsOn: classes) {

src/main/java/org/scm4j/vcs/api/IVCS.java

@@ -1,13 +1,15 @@
 package org.scm4j.vcs.api;
 
-import java.util.List;
-import java.util.Set;
-
+import org.scm4j.vcs.api.exceptions.EVCSBranchExists;
 import org.scm4j.vcs.api.exceptions.EVCSFileNotFound;
+import org.scm4j.vcs.api.exceptions.EVCSTagExists;
 import org.scm4j.vcs.api.workingcopy.IVCSWorkspace;
 
+import java.util.List;
+import java.util.Set;
+
 public interface IVCS {
-	void createBranch(String srcBranchName, String dstBranchName, String commitMessage);
+	void createBranch(String srcBranchName, String dstBranchName, String commitMessage) throws EVCSBranchExists;
 
 	VCSMergeResult merge(String srcBranchName, String dstBranchName, String commitMessage);
 
@@ -23,7 +25,7 @@ public interface IVCS {
 
 	String getFileContent(String branchName, String fileRelativePath) throws EVCSFileNotFound;
 
-	String setFileContent(String branchName, String filePath, String content, String commitMessage);
+	VCSCommit setFileContent(String branchName, String filePath, String content, String commitMessage);
 
 	List<VCSDiffEntry> getBranchesDiff(String srcBranchName, String destBranchName);
 
@@ -33,9 +35,21 @@ public interface IVCS {
 
 	String getVCSTypeString();
 
-	String removeFile(String branchName, String filePath, String commitMessage);
+	VCSCommit removeFile(String branchName, String filePath, String commitMessage);
+	
+	List<VCSCommit> getCommitsRange(String branchName, String firstCommitId, String untilCommitId);
+	
+	List<VCSCommit> getCommitsRange(String branchName, String firstCommitId, WalkDirection direction, int limit);
+	
+	IVCSWorkspace getWorkspace();
+	
+	VCSCommit getHeadCommit(String branchName);
+	
+	Boolean fileExists(String branchName, String filePath);
+	
+	VCSTag createTag(String branchName, String tagName, String tagMessage) throws EVCSTagExists;
 
-	List<VCSCommit> getCommitsRange(String branchName, String afterCommitId, String untilCommitId);
+	List<VCSTag> getTags();
 
-	IVCSWorkspace getWorkspace(); 
+	VCSTag getLastTag();
 }

src/main/java/org/scm4j/vcs/api/VCSCommit.java

@@ -1,31 +1,75 @@
 package org.scm4j.vcs.api;
 
 public class VCSCommit {
-	private final String id;
+	public static final VCSCommit EMPTY = new VCSCommit();
+	private final String revision;
 	private final String logMessage;
 	private final String author;
-	
+
 	public String getAuthor() {
 		return author;
 	}
 
-	public String getId() {
-		return id;
+	public String getRevision() {
+		return revision;
 	}
 
 	public String getLogMessage() {
 		return logMessage;
 	}
 
-	public VCSCommit(String id, String logMessage, String author) {
-		super();
-		this.id = id;
+	@Override
+	public int hashCode() {
+		final int prime = 31;
+		int result = 1;
+		result = prime * result + ((author == null) ? 0 : author.hashCode());
+		result = prime * result + ((logMessage == null) ? 0 : logMessage.hashCode());
+		result = prime * result + ((revision == null) ? 0 : revision.hashCode());
+		return result;
+	}
+
+	@Override
+	public boolean equals(Object obj) {
+		if (this == obj)
+			return true;
+		if (obj == null)
+			return false;
+		if (getClass() != obj.getClass())
+			return false;
+		VCSCommit other = (VCSCommit) obj;
+		if (author == null) {
+			if (other.author != null)
+				return false;
+		} else if (!author.equals(other.author))
+			return false;
+		if (logMessage == null) {
+			if (other.logMessage != null)
+				return false;
+		} else if (!logMessage.equals(other.logMessage))
+			return false;
+		if (revision == null) {
+			if (other.revision != null)
+				return false;
+		} else if (!revision.equals(other.revision))
+			return false;
+		return true;
+	}
+
+	protected VCSCommit() {
+		revision = null;
+		logMessage = null;
+		author = null;
+	}
+
+	public VCSCommit(String revision, String logMessage, String author) {
+		this.revision = revision;
 		this.logMessage = logMessage;
 		this.author = author;
 	}
 
 	@Override
 	public String toString() {
-		return "VCSCommit [id=" + id + ", logMessage=" + logMessage + ", author=" + author + "]";
+		return this == EMPTY ? "EMPTY"
+				: "VCSCommit [revision=" + revision + ", logMessage=" + logMessage + ", author=" + author + "]";
 	}
 }

src/main/java/org/scm4j/vcs/api/VCSDiffEntry.java

@@ -2,69 +2,30 @@
 
 public class VCSDiffEntry {
 
-	private String filePath;
-	private VCSChangeType changeType;
-	private String unifiedDiff;
-	
+	private final String filePath;
+	private final VCSChangeType changeType;
+	private final String unifiedDiff;
+
 	public String getUnifiedDiff() {
 		return unifiedDiff;
 	}
 
-	public void setUnifiedDiff(String unifiedDiff) {
-		this.unifiedDiff = unifiedDiff;
-	}
-
 	public String getFilePath() {
 		return filePath;
 	}
 
-	public void setFilePath(String filePath) {
-		this.filePath = filePath;
-	}
-
 	public VCSChangeType getChangeType() {
 		return changeType;
 	}
 
-	public void setChangeType(VCSChangeType changeType) {
-		this.changeType = changeType;
-	}
-
-	public VCSDiffEntry(String filePath, VCSChangeType changeType) {
+	public VCSDiffEntry(String filePath, VCSChangeType changeType, String unifiedDiff) {
 		this.filePath = filePath;
 		this.changeType = changeType;
+		this.unifiedDiff = unifiedDiff;
 	}
 
 	@Override
 	public String toString() {
 		return "VCSDiffEntry [filePath=" + filePath + ", changeType=" + changeType + "]";
 	}
-
-	@Override
-	public int hashCode() {
-		final int prime = 31;
-		int result = 1;
-		result = prime * result + ((changeType == null) ? 0 : changeType.hashCode());
-		result = prime * result + ((filePath == null) ? 0 : filePath.hashCode());
-		return result;
-	}
-
-	@Override
-	public boolean equals(Object obj) {
-		if (this == obj)
-			return true;
-		if (obj == null)
-			return false;
-		if (getClass() != obj.getClass())
-			return false;
-		VCSDiffEntry other = (VCSDiffEntry) obj;
-		if (changeType != other.changeType)
-			return false;
-		if (filePath == null) {
-			if (other.filePath != null)
-				return false;
-		} else if (!filePath.equals(other.filePath))
-			return false;
-		return true;
-	}
 }

src/main/java/org/scm4j/vcs/api/VCSMergeResult.java

@@ -1,26 +1,22 @@
 package org.scm4j.vcs.api;
 
-import java.util.ArrayList;
 import java.util.List;
 
 public class VCSMergeResult {
 
-	private Boolean success;
-	private List<String> conflictingFiles = new ArrayList<>();
+	private final Boolean success;
+	private final List<String> conflictingFiles;
 
 	public Boolean getSuccess() {
 		return success;
 	}
 
-	public void setSuccess(Boolean success) {
-		this.success = success;
-	}
-
 	public List<String> getConflictingFiles() {
 		return conflictingFiles;
 	}
 
-	public void setConflictingFiles(List<String> conflictingFiles) {
+	public VCSMergeResult(Boolean success, List<String> conflictingFiles) {
+		this.success = success;
 		this.conflictingFiles = conflictingFiles;
 	}
 }