Project Branches API (#153)

* added new protected branch API
* updated README

README.md

@@ -149,6 +149,7 @@ The API has been broken up into sub APIs classes to make it easier to learn and
 &nbsp;&nbsp;[NotificationSettingsApi](#notificationsettingsapi)<br/>
 &nbsp;&nbsp;[PipelineApi](#pipelineapi)<br/>
 &nbsp;&nbsp;[ProjectApi](#projectapi)<br/>
+&nbsp;&nbsp;[ProtectedBranchesApi](#protectedbranchesapi) <br/>
 &nbsp;&nbsp;[RepositoryApi](#repositoryapi)<br/>
 &nbsp;&nbsp;[RepositoryFileApi](#repositoryfileapi)<br/>
 &nbsp;&nbsp;[ServicesApi](#servicesapi)<br/>
@@ -261,6 +262,11 @@ Project projectSpec = new Project()
 Project newProject = gitLabApi.getProjectApi().createProject(projectSpec);
 ```
 
+#### ProtectedBranchesApi
+```java
+List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+```
+
 #### RepositoryApi
 ```java
 // Get a list of repository branches from a project, sorted by name alphabetically

example-test-gitlab4j.properties

+# Rename this file to test-gitlab4j.properties with proper property values.
+TEST_NAMESPACE=some-namespace
+TEST_PROJECT_NAME=some-project-name
+TEST_HOST_URL=some-gitlab-url
+TEST_PRIVATE_TOKEN=some-private-token

src/main/java/org/gitlab4j/api/GitLabApi.java

@@ -62,6 +62,7 @@ public class GitLabApi {
     private LabelsApi labelsApi;
     private NotesApi notesApi;
     private EventsApi eventsApi;
+    private ProtectedBranchesApi protectedBranchesApi;
 
     /**
      * Create a new GitLabApi instance that is logically a duplicate of this instance, with the exception off sudo state.
@@ -1020,6 +1021,25 @@ public class GitLabApi {
         return (userApi);
     }
 
+    /**
+     * Gets the ProtectedBranchesApi instance owned by this GitLabApi instance. The ProtectedBranchesApi is used
+     * to perform all protection related actions on a branch of a project.
+     *
+     * @return the ProtectedBranchesApi instance owned by this GitLabApi instance
+     */
+    public ProtectedBranchesApi getProtectedBranchesApi() {
+
+        if (this.protectedBranchesApi == null) {
+            synchronized (this) {
+                if (this.protectedBranchesApi == null) {
+                    this.protectedBranchesApi = new ProtectedBranchesApi(this);
+                }
+            }
+        }
+
+        return (this.protectedBranchesApi);
+    }
+
     /**
      * Create and return an Optional instance associated with a GitLabApiException.
      *

src/main/java/org/gitlab4j/api/ProtectedBranchesApi.java

+package org.gitlab4j.api;
+
+import org.gitlab4j.api.models.AccessLevel;
+import org.gitlab4j.api.models.ProtectedBranch;
+
+import javax.ws.rs.core.Form;
+import javax.ws.rs.core.GenericType;
+import javax.ws.rs.core.Response;
+import java.util.List;
+
+public class ProtectedBranchesApi extends AbstractApi {
+    public ProtectedBranchesApi(GitLabApi gitLabApi) {
+        super(gitLabApi);
+    }
+
+    /**
+     * Gets a list of protected branches from a project.
+     *
+     * GET /projects/:id/protected_branches
+     *
+     * @param projectId the ID of the project to protect
+     * @return the list of protected branches for the project
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<ProtectedBranch> getProtectedBranches(Integer projectId) throws GitLabApiException {
+        Response response = get(Response.Status.OK, null, "projects", projectId, "protected_branches");
+        return (response.readEntity(new GenericType<List<ProtectedBranch>>() {
+        }));
+    }
+
+    /**
+     * Unprotects the given protected branch or wildcard protected branch.
+     *
+     * DELETE /projects/:id/protected_branches/:name
+     *
+     * @param projectId  the ID of the project to un-protect
+     * @param branchName the name of the branch to un-protect
+     * @throws GitLabApiException if any exception occurs
+     */
+    public void unprotectBranch(Integer projectId, String branchName) throws GitLabApiException {
+        delete(Response.Status.NO_CONTENT, null, "projects", projectId, "protected_branches", urlEncode(branchName));
+    }
+
+    /**
+     * Protects a single repository branch or several project repository branches using a wildcard protected branch.
+     *
+     * POST /projects/:id/protected_branches
+     *
+     * @param projectId  the ID of the project to protect
+     * @param branchName the name of the branch to protect
+     * @return the branch info for the protected branch
+     * @throws GitLabApiException if any exception occurs
+     */
+    public ProtectedBranch protectBranch(Integer projectId, String branchName) throws GitLabApiException {
+        return protectBranch(projectId, branchName, AccessLevel.MASTER, AccessLevel.MASTER);
+    }
+
+    /**
+     * Protects a single repository branch or several project repository branches using a wildcard protected branch.
+     *
+     * POST /projects/:id/protected_branches
+     *
+     * @param projectId        the ID of the project to protect
+     * @param branchName       the name of the branch to protect
+     * @param pushAccessLevel  Access levels allowed to push (defaults: 40, master access level)
+     * @param mergeAccessLevel Access levels allowed to merge (defaults: 40, master access level)
+     * @return the branch info for the protected branch
+     * @throws GitLabApiException if any exception occurs
+     */
+    public ProtectedBranch protectBranch(Integer projectId, String branchName, AccessLevel pushAccessLevel, AccessLevel mergeAccessLevel) throws GitLabApiException {
+        Form formData = new GitLabApiForm()
+                .withParam("id", projectId, true)
+                .withParam("name", branchName, true)
+                .withParam("push_access_level", pushAccessLevel.toValue(), false)
+                .withParam("merge_access_level", mergeAccessLevel.toValue(), false);
+        Response response = post(Response.Status.CREATED, formData.asMap(), "projects", projectId, "protected_branches");
+        return (response.readEntity(ProtectedBranch.class));
+    }
+}

src/main/java/org/gitlab4j/api/RepositoryApi.java

@@ -15,6 +15,7 @@ import javax.ws.rs.core.MediaType;
 import javax.ws.rs.core.Response;
 
 import org.gitlab4j.api.GitLabApi.ApiVersion;
+import org.gitlab4j.api.models.AccessLevel;
 import org.gitlab4j.api.models.Branch;
 import org.gitlab4j.api.models.CompareResults;
 import org.gitlab4j.api.models.Tag;
@@ -110,7 +111,6 @@ public class RepositoryApi extends AbstractApi {
         return (response.readEntity(Branch.class));
     }
 
-
     /**
      * Delete a single project repository branch.
      *
@@ -463,7 +463,7 @@ public class RepositoryApi extends AbstractApi {
     /**
      * Compare branches, tags or commits. This can be accessed without authentication
      * if the repository is publicly accessible.
-     * 
+     *
      * @param projectId the ID of the project owned by the authenticated user
      * @param from the commit SHA or branch name
      * @param to the commit SHA or branch name
@@ -479,7 +479,7 @@ public class RepositoryApi extends AbstractApi {
     /**
      * Compare branches, tags or commits. This can be accessed without authentication
      * if the repository is publicly accessible.
-     * 
+     *
      * @param projectPath the path of the project owned by the authenticated user
      * @param from the commit SHA or branch name
      * @param to the commit SHA or branch name

src/main/java/org/gitlab4j/api/models/BranchAccessLevelDetail.java

+package org.gitlab4j.api.models;
+
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlRootElement;
+
+@XmlRootElement
+@XmlAccessorType(XmlAccessType.FIELD)
+public class BranchAccessLevelDetail {
+    private String accessLevel;
+    private String accessLevelDescription;
+
+    public String getAccessLevel() {
+        return this.accessLevel;
+    }
+
+    public void setAccessLevel(String accessLevel) {
+        this.accessLevel = accessLevel;
+    }
+
+    public String getAccessLevelDescription() {
+        return this.accessLevelDescription;
+    }
+
+    public void setAccessLevelDescription(String accessLevelDescription) {
+        this.accessLevelDescription = accessLevelDescription;
+    }
+}

src/main/java/org/gitlab4j/api/models/ProtectedBranch.java

+
+package org.gitlab4j.api.models;
+
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlRootElement;
+import java.util.List;
+
+@XmlRootElement
+@XmlAccessorType(XmlAccessType.FIELD)
+public class ProtectedBranch {
+    private String name;
+    private List<BranchAccessLevelDetail> pushAccessLevels;
+    private List<BranchAccessLevelDetail> mergeAccessLevels;
+
+    public String getName() {
+        return this.name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public List<BranchAccessLevelDetail> getPushAccessLevels() {
+        return this.pushAccessLevels;
+    }
+
+    public void setPushAccessLevels(List<BranchAccessLevelDetail> pushAccessLevels) {
+        this.pushAccessLevels = pushAccessLevels;
+    }
+
+    public List<BranchAccessLevelDetail> getMergeAccessLevels() {
+        return this.mergeAccessLevels;
+    }
+
+    public void setMergeAccessLevels(List<BranchAccessLevelDetail> mergeAccessLevels) {
+        this.mergeAccessLevels = mergeAccessLevels;
+    }
+
+    public static final boolean isValid(ProtectedBranch branch) {
+        return (branch != null && branch.getName() != null);
+    }
+}

src/test/java/org/gitlab4j/api/TestProtectedBranchesApi.java

+package org.gitlab4j.api;
+
+import org.gitlab4j.api.models.Branch;
+import org.gitlab4j.api.models.Project;
+import org.gitlab4j.api.models.ProtectedBranch;
+import org.junit.AfterClass;
+import org.junit.Before;
+import org.junit.BeforeClass;
+import org.junit.FixMethodOrder;
+import org.junit.Test;
+import org.junit.runners.MethodSorters;
+
+import java.util.List;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assume.assumeTrue;
+
+/**
+ * In order for these tests to run you must set the following properties in test-gitlab4j.properties
+ *
+ * TEST_NAMESPACE
+ * TEST_PROJECT_NAME
+ * TEST_HOST_URL
+ * TEST_PRIVATE_TOKEN
+ *
+ * If any of the above are NULL, all tests in this class will be skipped.
+ *
+ * NOTE: &FixMethodOrder(MethodSorters.NAME_ASCENDING) is very important to insure that testCreate() is executed first.
+ */
+@FixMethodOrder(MethodSorters.NAME_ASCENDING)
+public class TestProtectedBranchesApi {
+    // The following needs to be set to your test repository
+    private static final String TEST_PROJECT_NAME;
+    private static final String TEST_NAMESPACE;
+    private static final String TEST_HOST_URL;
+    private static final String TEST_PRIVATE_TOKEN;
+
+    static {
+        TEST_NAMESPACE = TestUtils.getProperty("TEST_NAMESPACE");
+        TEST_PROJECT_NAME = TestUtils.getProperty("TEST_PROJECT_NAME");
+        TEST_HOST_URL = TestUtils.getProperty("TEST_HOST_URL");
+        TEST_PRIVATE_TOKEN = TestUtils.getProperty("TEST_PRIVATE_TOKEN");
+    }
+
+    private static GitLabApi gitLabApi;
+
+    private static final String TEST_BRANCH_REF = "master";
+    private static final String TEST_BRANCH_NAME = "feature/test_branch";
+    private static final String TEST_PROTECT_BRANCH_NAME = "feature/protect_branch";
+
+    @BeforeClass
+    public static void setup() {
+
+        String problems = "";
+        if (TEST_NAMESPACE == null || TEST_NAMESPACE.trim().length() == 0) {
+            problems += "TEST_NAMESPACE cannot be empty\n";
+        }
+
+        if (TEST_PROJECT_NAME == null || TEST_PROJECT_NAME.trim().length() == 0) {
+            problems += "TEST_PROJECT_NAME cannot be empty\n";
+        }
+
+        if (TEST_HOST_URL == null || TEST_HOST_URL.trim().length() == 0) {
+            problems += "TEST_HOST_URL cannot be empty\n";
+        }
+
+        if (TEST_PRIVATE_TOKEN == null || TEST_PRIVATE_TOKEN.trim().length() == 0) {
+            problems += "TEST_PRIVATE_TOKEN cannot be empty\n";
+        }
+
+        if (problems.isEmpty()) {
+            gitLabApi = new GitLabApi(GitLabApi.ApiVersion.V4, TEST_HOST_URL, TEST_PRIVATE_TOKEN);
+        } else {
+            System.err.print(problems);
+        }
+    }
+
+    @AfterClass
+    public static void teardown() {
+        if (gitLabApi != null) {
+
+            try {
+                Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+
+                try {
+                    gitLabApi.getProtectedBranchesApi().unprotectBranch(project.getId(), TEST_BRANCH_NAME);
+                    gitLabApi.getRepositoryApi().deleteBranch(project.getId(), TEST_BRANCH_NAME);
+                } catch (GitLabApiException ignore) {
+                }
+
+                try {
+                    gitLabApi.getProtectedBranchesApi().unprotectBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+                    gitLabApi.getRepositoryApi().deleteBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+                } catch (GitLabApiException ignore) {
+                }
+            } catch (GitLabApiException ignore) {
+            }
+        }
+    }
+
+    @Before
+    public void beforeMethod() throws GitLabApiException {
+        assumeTrue(gitLabApi != null);
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        Branch protectedBranch;
+        try {
+            protectedBranch = gitLabApi.getRepositoryApi().getBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+        } catch (GitLabApiException e) {
+            protectedBranch = gitLabApi.getRepositoryApi().createBranch(project.getId(), TEST_PROTECT_BRANCH_NAME, TEST_BRANCH_REF);
+        }
+        assertNotNull(protectedBranch);
+        gitLabApi.getRepositoryApi().protectBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+
+        Branch branch;
+        try {
+            branch = gitLabApi.getRepositoryApi().getBranch(project.getId(), TEST_BRANCH_NAME);
+        } catch (GitLabApiException e) {
+            branch = gitLabApi.getRepositoryApi().createBranch(project.getId(), TEST_BRANCH_NAME, TEST_BRANCH_REF);
+        }
+        assertNotNull(branch);
+    }
+
+    @Test
+    public void testGetProtectedBranches() throws GitLabApiException {
+
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        assertNotNull(project);
+
+        List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+        assertNotNull(branches);
+        assertTrue(branches.stream()
+                .anyMatch((branch) -> branch.getName().equals(TEST_PROTECT_BRANCH_NAME)));
+    }
+
+    @Test
+    public void testUnprotectBranch() throws GitLabApiException {
+
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        assertNotNull(project);
+
+        gitLabApi.getProtectedBranchesApi().unprotectBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+        List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+        assertNotNull(branches);
+        assertTrue(branches.stream()
+                .noneMatch((branch) -> branch.getName().equals(TEST_PROTECT_BRANCH_NAME)));
+    }
+
+    @Test
+    public void testProtectBranch() throws GitLabApiException {
+
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        assertNotNull(project);
+
+        ProtectedBranch branch = gitLabApi.getProtectedBranchesApi().protectBranch(project.getId(), TEST_BRANCH_NAME);
+        List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+        assertNotNull(branches);
+        assertTrue(branches.stream()
+                .anyMatch((protectedBranch) -> protectedBranch.getName().equals(TEST_BRANCH_NAME)));
+    }
+}

src/test/java/org/gitlab4j/api/TestRepositoryApi.java

@@ -28,13 +28,13 @@ import org.junit.Test;
 import org.junit.runners.MethodSorters;
 
 /**
-* In order for these tests to run you must set the following properties in test-gitlab4j.properties
- * 
+ * In order for these tests to run you must set the following properties in test-gitlab4j.properties
+ *
  * TEST_NAMESPACE
  * TEST_PROJECT_NAME
  * TEST_HOST_URL
  * TEST_PRIVATE_TOKEN
- * 
+ *
  * If any of the above are NULL, all tests in this class will be skipped.
  *
  * NOTE: &FixMethodOrder(MethodSorters.NAME_ASCENDING) is very important to insure that testCreate() is executed first.
@@ -47,6 +47,7 @@ public class TestRepositoryApi {
     private static final String TEST_NAMESPACE;
     private static final String TEST_HOST_URL;
     private static final String TEST_PRIVATE_TOKEN;
+
     static {
         TEST_NAMESPACE = TestUtils.getProperty("TEST_NAMESPACE");
         TEST_PROJECT_NAME = TestUtils.getProperty("TEST_PROJECT_NAME");
@@ -96,19 +97,19 @@ public class TestRepositoryApi {
 
             try {
                 Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
-                
+
                 try {
                     gitLabApi.getRepositoryFileApi().deleteFile(TEST_FILEPATH, project.getId(), TEST_BRANCH_NAME, "Cleanup test files.");
                 } catch (GitLabApiException ignore) {
                 }
-                
+
                 try {
                     gitLabApi.getRepositoryApi().deleteBranch(project.getId(), TEST_BRANCH_NAME);
                 } catch (GitLabApiException ignore) {
                 }
 
                 gitLabApi.getRepositoryApi().deleteBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
-                
+
             } catch (GitLabApiException ignore) {
             }
         }
@@ -203,14 +204,14 @@ public class TestRepositoryApi {
 
     @Test
     public void testCompare() throws GitLabApiException {
-        
+
         Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
         assertNotNull(project);
 
         List<Commit> commits = gitLabApi.getCommitsApi().getCommits(project.getId());
         assertNotNull(commits);
         assertTrue(commits.size() > 1);
-        
+
         int numCommits = commits.size();
         CompareResults compareResults = gitLabApi.getRepositoryApi().compare(project.getId(), commits.get(numCommits - 1).getId(), commits.get(numCommits - 2).getId());
         assertNotNull(compareResults);
@@ -221,7 +222,7 @@ public class TestRepositoryApi {
 
     @Test
     public void testCreateFileAndDeleteFile() throws GitLabApiException {
-        
+
         Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
         assertNotNull(project);
 
@@ -230,7 +231,7 @@ public class TestRepositoryApi {
         file.setContent("This is a test file.");
         RepositoryFile createdFile = gitLabApi.getRepositoryFileApi().createFile(file, project.getId(), TEST_BRANCH_NAME, "Testing createFile().");
         assertNotNull(createdFile);
-        
+
         gitLabApi.getRepositoryFileApi().deleteFile(TEST_FILEPATH, project.getId(), TEST_BRANCH_NAME, "Testing deleteFile().");
     }
 
@@ -244,9 +245,9 @@ public class TestRepositoryApi {
         assertNotNull(branch);
 
         Branch protectedBranch = gitLabApi.getRepositoryApi().protectBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
-        assertNotNull(protectedBranch);        
+        assertNotNull(protectedBranch);
         assertTrue(protectedBranch.getProtected());
-        
+
         Branch unprotectedBranch = gitLabApi.getRepositoryApi().unprotectBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
         assertNotNull(unprotectedBranch);
         assertFalse(unprotectedBranch.getProtected());

src/test/java/org/gitlab4j/api/TestUtils.java

 package org.gitlab4j.api;
 
-import java.io.File;
 import java.io.FileInputStream;
 import java.io.IOException;
 import java.io.InputStream;
@@ -33,8 +32,7 @@ public class TestUtils {
     static {
 
         testProperties = new Properties();
-        File path = new File(System.getProperty("user.home"), "test-gitlab4j.properties");
-        try (InputStream input = new FileInputStream(path)) {
+        try (InputStream input = new FileInputStream("test-gitlab4j.properties")) {
             testProperties.load(input);
         } catch (IOException ioe) {
         }
@@ -49,4 +47,4 @@ public class TestUtils {
     public static final String getProperty(String key) {
         return (testProperties.getProperty(key));
     }
-}
+}
\ No newline at end of file