Project Branches API (#153)

* added new protected branch API
* updated README

Author: lamdav

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

@@ -0,0 +1,5 @@
+# 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 String getApiNamespace() {
     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 UserApi getUserApi() {
         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

@@ -0,0 +1,79 @@
+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.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 Branch createBranch(Integer projectId, String branchName, String ref) thr
         return (response.readEntity(Branch.class));
     }
 
-
     /**
      * Delete a single project repository branch.
      *
@@ -463,7 +463,7 @@ public File getRepositoryArchive(Integer projectId, String sha, File directory)
     /**
      * 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 CompareResults compare(Integer projectId, String from, String to) throws
     /**
      * 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

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,43 @@
+
+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);
+    }
+}