Fix #621 : Add deployment API

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

@@ -243,6 +243,28 @@ public interface Constants {
         }
     }
 
+    /** Enum to use for ordering the results of getDeployments. */
+    public static enum DeploymentOrderBy {
+
+        ID, IID, CREATED_AT, UPDATED_AT, REF;
+        private static JacksonJsonEnumHelper<DeploymentOrderBy> enumHelper = new JacksonJsonEnumHelper<>(DeploymentOrderBy.class);
+
+        @JsonCreator
+        public static DeploymentOrderBy forValue(String value) {
+            return enumHelper.forValue(value);
+        }
+
+        @JsonValue
+        public String toValue() {
+            return (enumHelper.toString(this));
+        }
+
+        @Override
+        public String toString() {
+            return (enumHelper.toString(this));
+        }
+    }
+
     /** Enum to use for specifying the scope when calling getPipelines(). */
     public enum PipelineScope {
 

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

+package org.gitlab4j.api;
+
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Stream;
+
+import javax.ws.rs.core.Response;
+
+import org.gitlab4j.api.models.Deployment;
+import org.gitlab4j.api.models.DeploymentFilter;
+import org.gitlab4j.api.models.MergeRequest;
+
+/**
+ * This class implements the client side API for the GitLab Deployments API calls.
+ * See https://docs.gitlab.com/ee/api/deployments.html
+ *
+ */
+public class DeploymentsApi extends AbstractApi {
+
+    public DeploymentsApi(GitLabApi gitLabApi) {
+        super(gitLabApi);
+    }
+
+    /**
+     * Get a list of deployments for the specified project.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @return a list of Deployments
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<Deployment> getProjectDeployments(Object projectIdOrPath) throws GitLabApiException {
+        return (getProjectDeployments(projectIdOrPath, null, getDefaultPerPage()).all());
+    }
+
+    /**
+     * Get a Pager of all deployments for the specified project.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param itemsPerPage the number of Deployments instances that will be fetched per page
+     * @return a Pager of Deployment
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Deployment> getProjectDeployments(Object projectIdOrPath, int itemsPerPage) throws GitLabApiException {
+        return (getProjectDeployments(projectIdOrPath, null, itemsPerPage));
+    }
+
+    /**
+     * Get a Pager of all deployments for the specified project.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param filter  {@link DeploymentFilter} a DeploymentFilter instance with the filter settings
+     * @return a Pager of Deployment
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Deployment> getProjectDeployments(Object projectIdOrPath, DeploymentFilter filter) throws GitLabApiException {
+        return (getProjectDeployments(projectIdOrPath, filter, getDefaultPerPage()));
+    }
+
+    /**
+     * Get a Pager of all deployments for the specified project.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param filter  {@link DeploymentFilter} a DeploymentFilter instance with the filter settings
+     * @param itemsPerPage the number of Deployments instances that will be fetched per page
+     * @return a Pager of Deployment
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Deployment> getProjectDeployments(Object projectIdOrPath, DeploymentFilter filter, int itemsPerPage) throws GitLabApiException {
+        GitLabApiForm formData = (filter != null ? filter.getQueryParams() : new GitLabApiForm());
+        return (new Pager<Deployment>(this, Deployment.class, itemsPerPage, formData.asMap(),
+                "projects", getProjectIdOrPath(projectIdOrPath), "deployments"));
+    }
+
+    /**
+     * Get a Stream of all deployments for the specified project.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @return a list of Deployment
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Stream<Deployment> getProjectDeploymentsStream(Object projectIdOrPath) throws GitLabApiException {
+        return (getProjectDeployments(projectIdOrPath, null, getDefaultPerPage()).stream());
+    }
+
+    /**
+     * Get a Stream of all deployments for the specified project.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param filter  {@link DeploymentFilter} a DeploymentFilter instance with the filter settings
+     * @return a list of Deployment
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Stream<Deployment> getProjectDeploymentsStream(Object projectIdOrPath, DeploymentFilter filter) throws GitLabApiException {
+        return (getProjectDeployments(projectIdOrPath, filter, getDefaultPerPage()).stream());
+    }
+
+    /**
+     * Get a specific deployment.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments/:deployment_id</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param deploymentId the ID of a project's deployment
+     * @return the specified Deployment instance
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Deployment getDeployment(Object projectIdOrPath, Integer deploymentId) throws GitLabApiException {
+        Response response = get(Response.Status.OK, getDefaultPerPageParam(),
+                "projects", getProjectIdOrPath(projectIdOrPath), "deployments", deploymentId);
+        return (response.readEntity(Deployment.class));
+    }
+
+    /**
+     * Get a specific deployment as an Optional instance.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments/:deployment_id</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param deploymentId the ID of a project's deployment
+     * @return the specified Deployment as an Optional instance
+     */
+    public Optional<Deployment> getOptionalDeployment(Object projectIdOrPath, Integer deploymentId) {
+        try {
+            return (Optional.ofNullable(getDeployment(projectIdOrPath, deploymentId)));
+        } catch (GitLabApiException glae) {
+            return (GitLabApi.createOptionalFromException(glae));
+        }
+    }
+
+    /**
+     * Creates a new deployment for a project.
+     *
+     * <pre><code>GitLab Endpoint: POST /projects/:id/deployments</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param environment The name of the environment to create the deployment for, required
+     * @param sha The SHA of the commit that is deployed, required
+     * @param ref The name of the branch or tag that is deployed, required
+     * @param tag A boolean that indicates if the deployed ref is a tag (true) or not (false). , required
+     * @param status The status to filter deployments by, optional
+     * @return a Deployment instance with info on the added deployment
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Deployment addDeployment(Object projectIdOrPath, String environment, String sha, String ref, Boolean tag, DeploymentStatus status) throws GitLabApiException {
+
+        GitLabApiForm formData = new GitLabApiForm()
+                .withParam("environment", environment, true)
+                .withParam("sha", sha, true)
+                .withParam("ref", ref, true)
+                .withParam("tag", tag, true)
+                .withParam("status",  status);
+        Response response = post(Response.Status.CREATED, formData,
+                "projects", getProjectIdOrPath(projectIdOrPath), "deployments");
+        return (response.readEntity(Deployment.class));
+    }
+
+    /**
+     * Updates an existing project deploy key.
+     *
+     * <pre><code>GitLab Endpoint: PUT /projects/:id/deployments/:key_id</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param deploymentId The ID of the deployment to update, required
+     * @param status The new status of the deployment, optional
+     * @return an updated Deployment instance
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Deployment updateDeployment(Object projectIdOrPath, Integer deploymentId, DeploymentStatus status) throws GitLabApiException {
+
+        if (deploymentId == null) {
+            throw new RuntimeException("deploymentId cannot be null");
+        }
+
+        final Deployment key = new Deployment();
+        key.setStatus(status);
+        final Response response = put(Response.Status.OK, key,
+                "projects", getProjectIdOrPath(projectIdOrPath), "deployments", deploymentId);
+
+        return (response.readEntity(Deployment.class));
+    }
+
+    /**
+     * Get a list of Merge Requests shipped with a given deployment.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments/:deployment_id/merge_requests</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param deploymentId The ID of the deployment to update, required
+     * @return a list containing the MergeRequest instances shipped with a given deployment
+     * @throws GitLabApiException GitLabApiException if any exception occurs during execution
+     */
+    public List<MergeRequest> getMergeRequests(Object projectIdOrPath, Integer deploymentId) throws GitLabApiException {
+        return (getMergeRequests(projectIdOrPath, deploymentId, getDefaultPerPage()).all());
+    }
+
+    /**
+     * Get a Pager of Merge Requests shipped with a given deployment.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments/:deployment_id/merge_requests</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param deploymentId The ID of the deployment to update, required
+     * @param itemsPerPage the number of Commit instances that will be fetched per page
+     * @return a Pager containing the MergeRequest instances shipped with a given deployment
+     * @throws GitLabApiException GitLabApiException if any exception occurs during execution
+     */
+    public Pager<MergeRequest> getMergeRequests(Object projectIdOrPath, Integer deploymentId, int itemsPerPage) throws GitLabApiException {
+    return (new Pager<MergeRequest>(this, MergeRequest.class, itemsPerPage, null,
+                "projects", getProjectIdOrPath(projectIdOrPath), "repository", "commits", deploymentId, "merge_requests"));
+    }
+
+    /**
+     * Get a Stream of Merge Requests shipped with a given deployment.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/deployments/:deployment_id/merge_requests</code></pre>
+     *
+     * @param projectIdOrPath the project in the form of an Integer(ID), String(path), or Project instance
+     * @param deploymentId The ID of the deployment to update, required
+     * @return a Stream containing the MergeRequest instances shipped with a given deployment
+     * @throws GitLabApiException GitLabApiException if any exception occurs during execution
+     */
+    public Stream<MergeRequest> getMergeRequestsStream(Object projectIdOrPath, Integer deploymentId) throws GitLabApiException {
+        return (getMergeRequests(projectIdOrPath, deploymentId, getDefaultPerPage()).stream());
+    }
+
+
+}

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

+package org.gitlab4j.api.models;
+
+import java.util.Date;
+
+import org.gitlab4j.api.Constants;
+import org.gitlab4j.api.GitLabApiForm;
+import org.gitlab4j.api.Constants.DeploymentOrderBy;
+import org.gitlab4j.api.Constants.DeploymentStatus;
+import org.gitlab4j.api.Constants.SortOrder;
+import org.gitlab4j.api.utils.ISO8601;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+
+public class DeploymentFilter {
+
+	/**
+	 * Return deployments ordered by either one of id, iid, created_at, updated_at or ref fields. Default is id.
+	 */
+	private DeploymentOrderBy orderBy;
+
+	/**
+	 * Return deployments sorted in asc or desc order. Default is asc.
+	 */
+	private SortOrder sortOrder;
+
+	/**
+     * Return deployments updated after the specified date. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
+     */
+    private Date finishedAfter;
+
+    /**
+     * Return deployments updated before the specified date. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
+     */
+    private Date finishedBefore;
+
+    /**
+     * The name of the environment to filter deployments by.
+     */
+    private String environment;
+
+    /**
+     * The status to filter deployments by.
+     */
+    private DeploymentStatus status;
+
+	public DeploymentOrderBy getOrderBy() {
+		return orderBy;
+	}
+
+	public void setOrderBy(DeploymentOrderBy orderBy) {
+		this.orderBy = orderBy;
+	}
+
+	public SortOrder getSortOrder() {
+		return sortOrder;
+	}
+
+	public void setSortOrder(SortOrder sortOrder) {
+		this.sortOrder = sortOrder;
+	}
+
+	public Date getFinishedAfter() {
+		return finishedAfter;
+	}
+
+	public void setFinishedAfter(Date finishedAfter) {
+		this.finishedAfter = finishedAfter;
+	}
+
+	public Date getFinishedBefore() {
+		return finishedBefore;
+	}
+
+	public void setFinishedBefore(Date finishedBefore) {
+		this.finishedBefore = finishedBefore;
+	}
+
+	public String getEnvironment() {
+		return environment;
+	}
+
+	public void setEnvironment(String environment) {
+		this.environment = environment;
+	}
+
+	public DeploymentStatus getStatus() {
+		return status;
+	}
+
+	public void setStatus(DeploymentStatus status) {
+		this.status = status;
+	}
+
+    public DeploymentFilter withOrderBy(DeploymentOrderBy orderBy) {
+        this.orderBy = orderBy;
+        return (this);
+    }
+
+    public DeploymentFilter withSortOrder(SortOrder sortOrder) {
+        this.sortOrder = sortOrder;
+        return (this);
+    }
+
+    public DeploymentFilter withFinishedAfter(Date finishedAfter) {
+        this.finishedAfter = finishedAfter;
+        return (this);
+    }
+
+    public DeploymentFilter withFinishedBefore(Date finishedBefore) {
+        this.finishedBefore = finishedBefore;
+        return (this);
+    }
+
+    public DeploymentFilter withEnvironment(String environment) {
+        this.environment = environment;
+        return (this);
+    }
+
+    public DeploymentFilter withStatus(DeploymentStatus status) {
+        this.status = status;
+        return (this);
+    }
+
+    @JsonIgnore
+    public GitLabApiForm getQueryParams(int page, int perPage) {
+        return (getQueryParams()
+                .withParam(Constants.PAGE_PARAM, page)
+                .withParam(Constants.PER_PAGE_PARAM, perPage));
+    }
+
+    @JsonIgnore
+    public GitLabApiForm getQueryParams() {
+        return (new GitLabApiForm()
+                .withParam("order_by", orderBy)
+                .withParam("sort", sortOrder)
+                .withParam("finished_after", ISO8601.toString(finishedAfter, false))
+                .withParam("finished_before", ISO8601.toString(finishedBefore, false))
+                .withParam("environment", environment)
+                .withParam("status", status));
+    }
+
+}