diff --git a/README.md b/README.md index 407b0ec715a55fa525b2a107268e5934b6c7e919..57d8c9657d26f5dc6b5999a8bfa607a7308fa4e9 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ To utilize the GitLab API for Java in your project, simply add the following dep ```java dependencies { ... - compile group: 'org.gitlab4j', name: 'gitlab4j-api', version: '4.2.5' + compile group: 'org.gitlab4j', name: 'gitlab4j-api', version: '4.3.0' } ``` @@ -20,11 +20,11 @@ dependencies { org.gitlab4j gitlab4j-api - 4.2.5 + 4.3.0 ``` -If you are not using Gradle or Maven you can download the latest gitlab4j-api JAR file here: [gitlab4j-api-4.2.5.jar](https://oss.sonatype.org/service/local/repositories/releases/content/org/gitlab4j/gitlab4j-api/4.2.5/gitlab4j-api-4.2.5.jar "Download JAR") +If you are not using Gradle or Maven you can download the latest gitlab4j-api JAR file here: [gitlab4j-api-4.3.0.jar](https://oss.sonatype.org/service/local/repositories/releases/content/org/gitlab4j/gitlab4j-api/4.3.0/gitlab4j-api-4.3.0.jar "Download JAR") Javadocs are available here: Javadocs @@ -45,6 +45,21 @@ As of GitLab4J-API 4.2.0 support has been added for GitLab API V4. If your appli GitLabApi gitLabApi = new GitLabApi(ApiVersion.V3, "http://your.gitlab.server.com", "YOUR_PRIVATE_TOKEN"); ``` +GitLab4J-API provides an easy to use paging mechanism to page through lists of results from the GitLab API. Here is an example on how to use the Pager: +```java +// Get a Pager instance that will page through the projects with 10 projects per page +Pager projectPager = gitlabApi.getProjectsApi().getProjectsPager(10); + +// Iterate through the pages and print out the name and description +while (projectsPager.hasNext())) { + + List projects = projectsPager.next(); + for (Project project : projects) { + System.out.println(project.getName() + " -: " + project.getDescription()); + } +} +``` + The API has been broken up into sub APIs classes to make it easier to learn and to separate concerns. Following is a list of the sub APIs along with a sample use of each API. See the Javadocs for a complete list of available methods for each sub API. Available Sub APIs diff --git a/src/main/java/org/gitlab4j/api/AbstractApi.java b/src/main/java/org/gitlab4j/api/AbstractApi.java index af6efdcc5063558d85f2c132f5f9be8caee21c04..557c000526a902899d81d1b56504fff46fd24b3e 100644 --- a/src/main/java/org/gitlab4j/api/AbstractApi.java +++ b/src/main/java/org/gitlab4j/api/AbstractApi.java @@ -1,5 +1,8 @@ package org.gitlab4j.api; +import java.net.URL; +import java.net.URLEncoder; + import javax.ws.rs.NotAuthorizedException; import javax.ws.rs.core.Form; import javax.ws.rs.core.MultivaluedMap; @@ -7,14 +10,11 @@ import javax.ws.rs.core.Response; import org.gitlab4j.api.GitLabApi.ApiVersion; -import java.net.URL; -import java.net.URLEncoder; - /** * This class is the base class for all the sub API classes. It provides implementations of * delete(), get(), post() and put() that are re-used by all the sub-classes. */ -public abstract class AbstractApi { +public abstract class AbstractApi implements Constants { private GitLabApi gitLabApi; @@ -49,7 +49,7 @@ public abstract class AbstractApi { /** * Perform an HTTP GET call with the specified query parameters and path objects, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param queryParams multivalue map of request parameters * @param pathArgs variable list of arguments used to build the URI @@ -67,7 +67,7 @@ public abstract class AbstractApi { /** * Perform an HTTP GET call with the specified query parameters and URL, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param queryParams multivalue map of request parameters * @param url the fully formed path to the GitLab API endpoint @@ -85,7 +85,7 @@ public abstract class AbstractApi { /** * Perform an HTTP POST call with the specified form data and path objects, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param formData the Form containing the name/value pairs for the POST data * @param pathArgs variable list of arguments used to build the URI @@ -103,7 +103,7 @@ public abstract class AbstractApi { /** * Perform an HTTP POST call with the specified form data and path objects, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param queryParams multivalue map of request parameters * @param pathArgs variable list of arguments used to build the URI @@ -121,7 +121,7 @@ public abstract class AbstractApi { /** * Perform an HTTP POST call with the specified form data and URL, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param formData the Form containing the name/value pairs for the POST data * @param url the fully formed path to the GitLab API endpoint @@ -139,7 +139,7 @@ public abstract class AbstractApi { /** * Perform an HTTP PUT call with the specified form data and path objects, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param queryParams multivalue map of request parameters * @param pathArgs variable list of arguments used to build the URI @@ -157,7 +157,7 @@ public abstract class AbstractApi { /** * Perform an HTTP PUT call with the specified form data and URL, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param queryParams multivalue map of request parameters * @param url the fully formed path to the GitLab API endpoint @@ -193,7 +193,7 @@ public abstract class AbstractApi { /** * Perform an HTTP DELETE call with the specified form data and URL, returning * a ClientResponse instance with the data returned from the endpoint. - * + * * @param expectedStatus the HTTP status that should be returned from the server * @param queryParams multivalue map of request parameters * @param url the fully formed path to the GitLab API endpoint @@ -210,7 +210,7 @@ public abstract class AbstractApi { /** * Convenience method for adding query and form parameters to a get() or post() call. - * + * * @param formData the Form containing the name/value pairs * @param name the name of the field/attribute to add * @param value the value of the field/attribute to add @@ -222,7 +222,7 @@ public abstract class AbstractApi { /** * Convenience method for adding query and form parameters to a get() or post() call. * If required is true and value is null, will throw an IllegalArgumentException. - * + * * @param formData the Form containing the name/value pairs * @param name the name of the field/attribute to add * @param value the value of the field/attribute to add @@ -251,7 +251,7 @@ public abstract class AbstractApi { /** * Validates response the response from the server against the expected HTTP status and * the returned secret token, if either is not correct will throw a GitLabApiException. - * + * * @param response response * @param expected expected response status * @return original response if the response status is expected @@ -272,9 +272,9 @@ public abstract class AbstractApi { /** * Wraps an exception in a GitLabApiException if needed. - * + * * @param thrown the exception that should be wrapped - * @return either the untouched GitLabApiException or a new GitLabApiExceptin wrapping a non-GitLabApiException + * @return either the untouched GitLabApiException or a new GitLabApiExceptin wrapping a non-GitLabApiException */ protected GitLabApiException handle(Exception thrown) { @@ -284,4 +284,24 @@ public abstract class AbstractApi { return (new GitLabApiException(thrown)); } + + /** + * Creates a MultivaluedMap instance containing "page" and "per_page" params. + * + * @param page the page to get + * @param perPage the number of projects per page + * @return a MultivaluedMap instance containing "page" and "per_page" params + */ + protected MultivaluedMap getPageQueryParams(int page, int perPage) { + return (new GitLabApiForm().withParam(PAGE_PARAM, page).withParam(PER_PAGE_PARAM, perPage).asMap()); + } + + /** + * Creates a MultivaluedMap instance containing the "per_page" param with the default value. + * + * @return a MultivaluedMap instance containing the "per_page" param with the default value + */ + protected MultivaluedMap getDefaultPerPageParam() { + return (new GitLabApiForm().withParam(PER_PAGE_PARAM, getDefaultPerPage()).asMap()); + } } diff --git a/src/main/java/org/gitlab4j/api/CommitsApi.java b/src/main/java/org/gitlab4j/api/CommitsApi.java index d02b6871e5ea3f82ebedc42a5d346c918b3660fe..86858927fa3c2721cd027e109fa95bf28e938df9 100644 --- a/src/main/java/org/gitlab4j/api/CommitsApi.java +++ b/src/main/java/org/gitlab4j/api/CommitsApi.java @@ -1,5 +1,7 @@ package org.gitlab4j.api; +import java.util.List; + import javax.ws.rs.core.Form; import javax.ws.rs.core.GenericType; import javax.ws.rs.core.Response; @@ -7,8 +9,6 @@ import javax.ws.rs.core.Response; import org.gitlab4j.api.models.Commit; import org.gitlab4j.api.models.Diff; -import java.util.List; - /** * This class implements the client side API for the GitLab commits calls. */ @@ -20,41 +20,68 @@ public class CommitsApi extends AbstractApi { /** * Get a list of repository commits in a project. - * + * * GET /projects/:id/repository/commits - * + * * @param projectId the project ID to get the list of commits for * @return a list containing the commits for the specified project ID * @throws GitLabApiException GitLabApiException if any exception occurs during execution */ public List getCommits(int projectId) throws GitLabApiException { - Form formData = new GitLabApiForm().withParam("per_page", getDefaultPerPage()); - Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "repository", "commits"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "repository", "commits"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of repository commits in a project. + * + * GET /projects/:id/repository/commits + * + * @param projectId the project ID to get the list of commits for + * @param page the page to get + * @param perPage the number of commits per page + * @return a list containing the commits for the specified project ID + * @throws GitLabApiException GitLabApiException if any exception occurs during execution + */ + public List getCommits(int projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "repository", "commits"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of repository commits in a project. + * + * GET /projects/:id/repository/commits + * + * @param projectId the project ID to get the list of commits for + * @param itemsPerPage the number of Commit instances that will be fetched per page + * @return a Pager containing the commits for the specified project ID + * @throws GitLabApiException GitLabApiException if any exception occurs during execution + */ + public Pager getCommits(int projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Commit.class, itemsPerPage, null, "projects", projectId, "repository", "commits")); } /** * Get a specific commit identified by the commit hash or name of a branch or tag. - * + * * GET /projects/:id/repository/commits/:sha - * + * * @param projectId the project ID that the commit belongs to * @param sha a commit hash or name of a branch or tag * @return the Commit instance for the specified project ID/sha pair * @throws GitLabApiException GitLabApiException if any exception occurs during execution */ - public Commit getCommits(int projectId, String sha) throws GitLabApiException { - Form formData = new GitLabApiForm().withParam("per_page", getDefaultPerPage()); - Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "repository", "commits", sha); + public Commit getCommit(int projectId, String sha) throws GitLabApiException { + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "repository", "commits", sha); return (response.readEntity(Commit.class)); } /** * Get the diff of a commit in a project. - * + * * GET /projects/:id/repository/commits/:sha/diff - * + * * @param projectId the project ID that the commit belongs to * @param sha a commit hash or name of a branch or tag * @return the Diff instance for the specified project ID/sha pair @@ -64,4 +91,4 @@ public class CommitsApi extends AbstractApi { Response response = get(Response.Status.OK, null, "projects", projectId, "repository", "commits", sha, "diff"); return (response.readEntity(Diff.class)); } -} \ No newline at end of file +} diff --git a/src/main/java/org/gitlab4j/api/Constants.java b/src/main/java/org/gitlab4j/api/Constants.java index 2c738630a6688efca64747336bdc4f1c89065754..e8cf701ab740e2664faa741eabecd8852c7a588d 100644 --- a/src/main/java/org/gitlab4j/api/Constants.java +++ b/src/main/java/org/gitlab4j/api/Constants.java @@ -7,6 +7,30 @@ import com.fasterxml.jackson.annotation.JsonValue; public interface Constants { + /** The total number of items HTTP header key. */ + public static final String TOTAL_HEADER = "X-Total"; + + /** The total number of pages HTTP header key. */ + public static final String TOTAL_PAGES_HEADER = "X-Total-Pages"; + + /** The number of items per page HTTP header key. */ + public static final String PER_PAGE = "X-Per-Page"; + + /** The index of the current page (starting at 1) HTTP header key. */ + public static final String PAGE_HEADER = "X-Page"; + + /** The index of the next page HTTP header key. */ + public static final String NEXT_PAGE_HEADER = "X-Next-Page"; + + /** The index of the previous page HTTP header key. */ + public static final String PREV_PAGE_HEADER = "X-Prev-Page"; + + /** Items per page param HTTP header key. */ + public static final String PER_PAGE_PARAM = "per_page"; + + /** Page param HTTP header key. */ + public static final String PAGE_PARAM = "page"; + /** Enum to use for ordering the results of various API calls. */ public enum SortOrder { diff --git a/src/main/java/org/gitlab4j/api/GitLabApi.java b/src/main/java/org/gitlab4j/api/GitLabApi.java index 294f05528a872228a6e06b5364d6463c560322d6..813fc5a188369b0c9a57258864d31dca3bfb7b66 100644 --- a/src/main/java/org/gitlab4j/api/GitLabApi.java +++ b/src/main/java/org/gitlab4j/api/GitLabApi.java @@ -38,7 +38,7 @@ public class GitLabApi { private Session session; /** - * Logs into GitLab using provided {@code username} and {@code password}, and creates a new {@code GitLabApi} instance + * Logs into GitLab using provided {@code username} and {@code password}, and creates a new {@code GitLabApi} instance * using returned private token and the specified GitLab API version. * * @param apiVersion the ApiVersion specifying which version of the API to use @@ -55,7 +55,7 @@ public class GitLabApi { } /** - * Logs into GitLab using provided {@code username} and {@code password}, and creates a new {@code GitLabApi} instance + * Logs into GitLab using provided {@code username} and {@code password}, and creates a new {@code GitLabApi} instance * using returned private token using GitLab API version 4. * * @param url GitLab URL @@ -69,7 +69,7 @@ public class GitLabApi { } /** - * Logs into GitLab using provided {@code username} and {@code password}, and creates a new {@code GitLabApi} instance + * Logs into GitLab using provided {@code username} and {@code password}, and creates a new {@code GitLabApi} instance * using returned private token and specified GitLab API version. * * @param url GitLab URL @@ -107,7 +107,7 @@ public class GitLabApi { /** * Constructs a GitLabApi instance set up to interact with the GitLab server using GitLab API version 4. - * + * * @param hostUrl the URL of the GitLab server * @param privateToken to private token to use for access to the API */ @@ -129,7 +129,7 @@ public class GitLabApi { /** * Constructs a GitLabApi instance set up to interact with the GitLab server using GitLab API version 4. - * + * * @param hostUrl the URL of the GitLab server * @param session the Session instance obtained by logining into the GitLab server */ @@ -151,7 +151,7 @@ public class GitLabApi { /** * Constructs a GitLabApi instance set up to interact with the GitLab server using GitLab API version 4. - * + * * @param hostUrl the URL of the GitLab server * @param privateToken to private token to use for access to the API * @param secretToken use this token to validate received payloads @@ -162,7 +162,7 @@ public class GitLabApi { /** * Constructs a GitLabApi instance set up to interact with the GitLab server specified by GitLab API version. - * + * * @param apiVersion the ApiVersion specifying which version of the API to use * @param hostUrl the URL of the GitLab server * @param privateToken to private token to use for access to the API @@ -199,7 +199,7 @@ public class GitLabApi { /** * Return the GitLab API version that this instance is using. - * + * * @return the GitLab API version that this instance is using */ public ApiVersion getApiVersion() { @@ -227,7 +227,7 @@ public class GitLabApi { /** * Return the GitLabApiClient associated with this instance. This is used by all the sub API classes * to communicate with the GitLab API. - * + * * @return the GitLabApiClient associated with this instance */ GitLabApiClient getApiClient() { @@ -237,7 +237,7 @@ public class GitLabApi { /** * Gets the CommitsApi instance owned by this GitLabApi instance. The CommitsApi is used * to perform all commit related API calls. - * + * * @return the CommitsApi instance owned by this GitLabApi instance */ public CommitsApi getCommitsApi() { @@ -247,7 +247,7 @@ public class GitLabApi { /** * Gets the MergeRequestApi instance owned by this GitLabApi instance. The MergeRequestApi is used * to perform all merge request related API calls. - * + * * @return the MergeRequestApi instance owned by this GitLabApi instance */ public MergeRequestApi getMergeRequestApi() { @@ -257,7 +257,7 @@ public class GitLabApi { /** * Gets the NamespaceApi instance owned by this GitLabApi instance. The NamespaceApi is used * to perform all namespace related API calls. - * + * * @return the NamespaceApi instance owned by this GitLabApi instance */ public NamespaceApi getNamespaceApi() { @@ -271,7 +271,7 @@ public class GitLabApi { /** * Gets the GroupApi instance owned by this GitLabApi instance. The GroupApi is used * to perform all group related API calls. - * + * * @return the GroupApi instance owned by this GitLabApi instance */ public GroupApi getGroupApi() { @@ -281,17 +281,17 @@ public class GitLabApi { /** * Gets the PipelineApi instance owned by this GitLabApi instance. The PipelineApi is used * to perform all pipeline related API calls. - * + * * @return the PipelineApi instance owned by this GitLabApi instance */ public PipelineApi getPipelineApi() { return (pipelineApi); } - + /** * Gets the ProjectApi instance owned by this GitLabApi instance. The ProjectApi is used * to perform all project related API calls. - * + * * @return the ProjectApi instance owned by this GitLabApi instance */ public ProjectApi getProjectApi() { @@ -301,7 +301,7 @@ public class GitLabApi { /** * Gets the RepositoryApi instance owned by this GitLabApi instance. The RepositoryApi is used * to perform all repository related API calls. - * + * * @return the RepositoryApi instance owned by this GitLabApi instance */ public RepositoryApi getRepositoryApi() { @@ -311,7 +311,7 @@ public class GitLabApi { /** * Gets the RepositoryFileApi instance owned by this GitLabApi instance. The RepositoryFileApi is used * to perform all repository files related API calls. - * + * * @return the RepositoryFileApi instance owned by this GitLabApi instance */ public RepositoryFileApi getRepositoryFileApi() { @@ -321,7 +321,7 @@ public class GitLabApi { /** * Gets the ServicesApi instance owned by this GitLabApi instance. The ServicesApi is used * to perform all services related API calls. - * + * * @return the ServicesApi instance owned by this GitLabApi instance */ public ServicesApi getServicesApi() { @@ -331,7 +331,7 @@ public class GitLabApi { /** * Gets the SessionApi instance owned by this GitLabApi instance. The SessionApi is used * to perform a login to the GitLab API. - * + * * @return the SessionApi instance owned by this GitLabApi instance */ public SessionApi getSessionApi() { @@ -341,7 +341,7 @@ public class GitLabApi { /** * Gets the UserApi instance owned by this GitLabApi instance. The UserApi is used * to perform all user related API calls. - * + * * @return the UserApi instance owned by this GitLabApi instance */ public UserApi getUserApi() { diff --git a/src/main/java/org/gitlab4j/api/GroupApi.java b/src/main/java/org/gitlab4j/api/GroupApi.java index 1294f11b7bb9a327f5451cdf8901d72b981ac251..ef0994e391f25bfb2c347105ef0c255a1df5860d 100644 --- a/src/main/java/org/gitlab4j/api/GroupApi.java +++ b/src/main/java/org/gitlab4j/api/GroupApi.java @@ -1,16 +1,17 @@ package org.gitlab4j.api; +import java.util.List; + +import javax.ws.rs.core.Form; +import javax.ws.rs.core.GenericType; +import javax.ws.rs.core.Response; + import org.gitlab4j.api.GitLabApi.ApiVersion; import org.gitlab4j.api.models.Group; import org.gitlab4j.api.models.Member; import org.gitlab4j.api.models.Project; import org.gitlab4j.api.models.Visibility; -import javax.ws.rs.core.Form; -import javax.ws.rs.core.GenericType; -import javax.ws.rs.core.Response; -import java.util.List; - /** * This class implements the client side API for the GitLab groups calls. */ @@ -22,30 +23,84 @@ public class GroupApi extends AbstractApi { /** * Get a list of groups. (As user: my groups, as admin: all groups) - * + * * GET /groups - * + * * @return the list of groups viewable by the authenticated user * @throws GitLabApiException if any exception occurs */ public List getGroups() throws GitLabApiException { - Response response = get(Response.Status.OK, null, "groups"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "groups"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of groups (As user: my groups, as admin: all groups) and in the specified page range. + * + * GET /groups + * + * @param page the page to get + * @param perPage the number of Group instances per page + * @return the list of groups viewable by the authenticated userin the specified page range + * @throws GitLabApiException if any exception occurs + */ + public List getGroups(int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "groups"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of groups. (As user: my groups, as admin: all groups) + * + * GET /groups + * + * @param itemsPerPage the number of Group instances that will be fetched per page + * @return the list of groups viewable by the authenticated user + * @throws GitLabApiException if any exception occurs + */ + public Pager getGroups(int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Group.class, itemsPerPage, null, "groups")); } /** * Get all groups that match your string in their name or path. - * + * * @param search the group name or path search criteria * @return a List containing matching Group instances * @throws GitLabApiException if any exception occurs */ public List getGroups(String search) throws GitLabApiException { - Form formData = new GitLabApiForm().withParam("search", search).withParam("per_page", getDefaultPerPage()); + Form formData = new GitLabApiForm().withParam("search", search).withParam(PER_PAGE_PARAM, getDefaultPerPage()); + Response response = get(Response.Status.OK, formData.asMap(), "groups"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get all groups that match your string in their name or path. + * + * @param search the group name or path search criteria + * @param page the page to get + * @param perPage the number of Group instances per page + * @return a List containing matching Group instances + * @throws GitLabApiException if any exception occurs + */ + public List getGroups(String search, int page, int perPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("search", search).withParam(PAGE_PARAM, page).withParam(PER_PAGE_PARAM, perPage); Response response = get(Response.Status.OK, formData.asMap(), "groups"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get all groups that match your string in their name or path. + * + * @param search the group name or path search criteria + * @param itemsPerPage the number of Group instances that will be fetched per page + * @return a List containing matching Group instances + * @throws GitLabApiException if any exception occurs + */ + public Pager getGroups(String search, int itemsPerPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("search", search); + return (new Pager(this, Group.class, itemsPerPage, formData.asMap(), "groups")); } /** @@ -58,16 +113,45 @@ public class GroupApi extends AbstractApi { * @throws GitLabApiException if any exception occurs */ public List getProjects(int groupId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "groups", groupId, "projects"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "groups", groupId, "projects"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of projects belonging to the specified group ID in the specified page range. + * + * GET /groups/:id/projects + * + * @param groupId the group ID to list the projects for + * @param page the page to get + * @param perPage the number of Project instances per page + * @return a list of projects belonging to the specified group ID in the specified page range + * @throws GitLabApiException if any exception occurs + */ + public List getProjects(int groupId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "groups", groupId, "projects"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of projects belonging to the specified group ID. + * + * GET /groups/:id/projects + * + * @param groupId the group ID to list the projects for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of projects belonging to the specified group ID + * @throws GitLabApiException if any exception occurs + */ + public Pager getProjects(int groupId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Project.class, itemsPerPage, null, "groups", groupId, "projects")); } /** * Get all details of a group. - * + * * GET /groups/:id - * + * * @param groupId the group ID to get * @return the Group instance for the specified group ID * @throws GitLabApiException if any exception occurs @@ -79,9 +163,9 @@ public class GroupApi extends AbstractApi { /** * Creates a new project group. Available only for users who can create groups. - * + * * POST /groups - * + * * @param name the name of the group to add * @param path the path for the group * @throws GitLabApiException if any exception occurs @@ -96,9 +180,9 @@ public class GroupApi extends AbstractApi { /** * Creates a new project group. Available only for users who can create groups. - * + * * POST /groups - * + * * @param name the name of the group to add * @param path the path for the group * @param description (optional) - The group's description @@ -131,7 +215,7 @@ public class GroupApi extends AbstractApi { /** * Creates a new project group. Available only for users who can create groups. - * + * * PUT /groups * * @param groupId the ID of the group to update @@ -170,9 +254,9 @@ public class GroupApi extends AbstractApi { /** * Removes group with all projects inside. - * + * * DELETE /groups/:id - * + * * @param groupId the group ID to delete * @throws GitLabApiException if any exception occurs */ @@ -188,9 +272,9 @@ public class GroupApi extends AbstractApi { /** * Removes group with all projects inside. - * + * * DELETE /groups/:id - * + * * @param group the Group instance to delete * @throws GitLabApiException if any exception occurs */ @@ -200,24 +284,53 @@ public class GroupApi extends AbstractApi { /** * Get a list of group members viewable by the authenticated user. - * + * * GET /groups/:id/members - * + * * @param groupId the group ID to list the members for * @return a list of group members viewable by the authenticated user * @throws GitLabApiException if any exception occurs */ public List getMembers(int groupId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "groups", groupId, "members"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "groups", groupId, "members"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of group members viewable by the authenticated user in the specified page range. + * + * GET /groups/:id/members + * + * @param groupId the group ID to list the members for + * @param page the page to get + * @param perPage the number of Member instances per page + * @return a list of group members viewable by the authenticated user in the specified page range + * @throws GitLabApiException if any exception occurs + */ + public List getMembers(int groupId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "groups", groupId, "members"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of group members viewable by the authenticated user. + * + * GET /groups/:id/members + * + * @param groupId the group ID to list the members for + * @param itemsPerPage the number of Member instances that will be fetched per page + * @return a list of group members viewable by the authenticated user + * @throws GitLabApiException if any exception occurs + */ + public Pager getMembers(int groupId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Member.class, itemsPerPage, null, "groups", groupId, "members")); } /** * Adds a user to the list of group members. - * + * * POST /groups/:id/members - * + * * @param groupId the project ID to add the member to * @param userId the user ID of the member to add * @param accessLevel the access level for the new member @@ -235,9 +348,9 @@ public class GroupApi extends AbstractApi { /** * Removes member from the group team. - * + * * DELETE /groups/:id/members/:user_id - * + * * @param projectId the project ID to remove the member from * @param userId the user ID of the member to remove * @throws GitLabApiException if any exception occurs @@ -246,4 +359,4 @@ public class GroupApi extends AbstractApi { Response.Status expectedStatus = (isApiVersion(ApiVersion.V3) ? Response.Status.OK : Response.Status.NO_CONTENT); delete(expectedStatus, null, "groups", projectId, "members", userId); } -} \ No newline at end of file +} diff --git a/src/main/java/org/gitlab4j/api/MergeRequestApi.java b/src/main/java/org/gitlab4j/api/MergeRequestApi.java index ed9d45ded51de140e4e969591a40ce012fb40452..f8cf56ef54a32c7e628c6258a4ec8daa99c4fac1 100644 --- a/src/main/java/org/gitlab4j/api/MergeRequestApi.java +++ b/src/main/java/org/gitlab4j/api/MergeRequestApi.java @@ -27,9 +27,38 @@ public class MergeRequestApi extends AbstractApi { * @throws GitLabApiException if any exception occurs */ public List getMergeRequests(Integer projectId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "projects", projectId, "merge_requests"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "merge_requests"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get all merge requests for the specified project. + * + * GET /projects/:id/merge_requests + * + * @param projectId the project ID to get the merge requests for + * @param page the page to get + * @param perPage the number of MergeRequest instances per page + * @return all merge requests for the specified project + * @throws GitLabApiException if any exception occurs + */ + public List getMergeRequests(Integer projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "merge_requests"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get all merge requests for the specified project. + * + * GET /projects/:id/merge_requests + * + * @param projectId the project ID to get the merge requests for + * @param itemsPerPage the number of MergeRequest instances that will be fetched per page + * @return all merge requests for the specified project + * @throws GitLabApiException if any exception occurs + */ + public Pager getMergeRequests(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, MergeRequest.class, itemsPerPage, null, "projects", projectId, "merge_requests")); } /** diff --git a/src/main/java/org/gitlab4j/api/NamespaceApi.java b/src/main/java/org/gitlab4j/api/NamespaceApi.java index 3162ff4bf4979c1afe5d186f07158202c527bbc5..339d0e85dad1d9f165022534de472504d9c0d51c 100644 --- a/src/main/java/org/gitlab4j/api/NamespaceApi.java +++ b/src/main/java/org/gitlab4j/api/NamespaceApi.java @@ -18,32 +18,92 @@ public class NamespaceApi extends AbstractApi { /** * Get a list of the namespaces of the authenticated user. If the user is an administrator, - * a list of all namespaces in the GitLab instance is shown. - * + * a list of all namespaces in the GitLab instance is created. + * * GET /namespaces - * + * * @return a List of Namespace instances * @throws GitLabApiException if any exception occurs */ public List getNamespaces() throws GitLabApiException { - Response response = get(Response.Status.OK, null, "namespaces"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "namespaces"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of the namespaces of the authenticated user. If the user is an administrator, + * a list of all namespaces in the GitLab instance is created. + * + * GET /namespaces + * + * @param page the page to get + * @param perPage the number of Namespace instances per page + * @return a List of Namespace instances in the specified page range + * @throws GitLabApiException if any exception occurs + */ + public List getNamespaces(int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "namespaces"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of the namespaces of the authenticated user. If the user is an administrator, + * a Pager of all namespaces in the GitLab instance is created. + * + * GET /namespaces + * + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of Namespace instances + * @throws GitLabApiException if any exception occurs + */ + public Pager getNamespaces(int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Namespace.class, itemsPerPage, null, "namespaces")); } /** * Get all namespaces that match a string in their name or path. * * GET /namespaces?search=:query - * + * * @param query the search string * @return the Namespace List with the matching namespaces * @throws GitLabApiException if any exception occurs */ public List findNamespaces(String query) throws GitLabApiException { - GitLabApiForm formData = new GitLabApiForm().withParam("search", query, true); + GitLabApiForm formData = new GitLabApiForm().withParam("search", query, true).withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "namespaces"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get all namespaces that match a string in their name or path in the specified page range. + * + * GET /namespaces?search=:query + * + * @param query the search string + * @param page the page to get + * @param perPage the number of Namespace instances per page + * @return the Namespace List with the matching namespaces + * @throws GitLabApiException if any exception occurs + */ + public List findNamespaces(String query, int page, int perPage) throws GitLabApiException { + GitLabApiForm formData = new GitLabApiForm().withParam("search", query, true).withParam(PAGE_PARAM, perPage).withParam(PER_PAGE_PARAM, perPage); + Response response = get(Response.Status.OK, formData.asMap(), "namespaces"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of all namespaces that match a string in their name or path. + * + * GET /namespaces?search=:query + * + * @param query the search string + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of Namespace instances with the matching namespaces + * @throws GitLabApiException if any exception occurs + */ + public Pager getNamespaces(String query, int itemsPerPage) throws GitLabApiException { + GitLabApiForm formData = new GitLabApiForm().withParam("search", query, true); + return (new Pager(this, Namespace.class, itemsPerPage, formData.asMap(), "namespaces")); } } diff --git a/src/main/java/org/gitlab4j/api/PipelineApi.java b/src/main/java/org/gitlab4j/api/PipelineApi.java index 3ff62bcd18f01ee50f1e112bfc275b61594f3e96..795551c887721426aa129dc93bdaadfd2e63b626 100644 --- a/src/main/java/org/gitlab4j/api/PipelineApi.java +++ b/src/main/java/org/gitlab4j/api/PipelineApi.java @@ -27,9 +27,38 @@ public class PipelineApi extends AbstractApi implements Constants { * @throws GitLabApiException if any exception occurs during execution */ public List getPipelines(int projectId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "projects", projectId, "pipelines"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "pipelines"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of pipelines in a project in the specified page range. + * + * GET /projects/:id/pipelines + * + * @param projectId the project ID to get the list of pipelines for + * @param page the page to get + * @param perPage the number of Pipeline instances per page + * @return a list containing the pipelines for the specified project ID in the specified page range + * @throws GitLabApiException if any exception occurs during execution + */ + public List getPipelines(int projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "pipelines"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of pipelines in a project. + * + * GET /projects/:id/pipelines + * + * @param projectId the project ID to get the list of pipelines for + * @param itemsPerPage the number of Pipeline instances that will be fetched per page + * @return a Pager containing the pipelines for the specified project ID + * @throws GitLabApiException if any exception occurs during execution + */ + public Pager getPipelines(int projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Pipeline.class, itemsPerPage, null, "projects", projectId, "pipelines")); } /** @@ -49,7 +78,7 @@ public class PipelineApi extends AbstractApi implements Constants { * @return a list containing the pipelines for the specified project ID * @throws GitLabApiException if any exception occurs during execution */ - public List getPipelines(int projectId, PipelineScope scope, PipelineStatus status, String ref, boolean yamlErrors, + public List getPipelines(int projectId, PipelineScope scope, PipelineStatus status, String ref, boolean yamlErrors, String name, String username, PipelineOrderBy orderBy, SortOrder sort) throws GitLabApiException { GitLabApiForm formData = new GitLabApiForm() .withParam("scope", scope) @@ -59,11 +88,81 @@ public class PipelineApi extends AbstractApi implements Constants { .withParam("name", name) .withParam("username", username) .withParam("order_by", orderBy) - .withParam("sort", sort); + .withParam("sort", sort) + .withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "pipelines"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of pipelines in a project in the specified page range. + * + * GET /projects/:id/pipelines + * + * @param projectId the project ID to get the list of pipelines for + * @param scope the scope of pipelines, one of: RUNNING, PENDING, FINISHED, BRANCHES, TAGS + * @param status the status of pipelines, one of: RUNNING, PENDING, SUCCESS, FAILED, CANCELED, SKIPPED + * @param ref the ref of pipelines + * @param yamlErrors returns pipelines with invalid configurations + * @param name the name of the user who triggered pipelines + * @param username the username of the user who triggered pipelines + * @param orderBy order pipelines by ID, STATUS, REF, USER_ID (default: ID) + * @param sort sort pipelines in ASC or DESC order (default: DESC) + * @param page the page to get + * @param perPage the number of Pipeline instances per page + * @return a list containing the pipelines for the specified project ID + * @throws GitLabApiException if any exception occurs during execution + */ + public List getPipelines(int projectId, PipelineScope scope, PipelineStatus status, String ref, boolean yamlErrors, + String name, String username, PipelineOrderBy orderBy, SortOrder sort, int page, int perPage) throws GitLabApiException { + GitLabApiForm formData = new GitLabApiForm() + .withParam("scope", scope) + .withParam("status", status) + .withParam("ref", ref) + .withParam("yaml_errors", yamlErrors) + .withParam("name", name) + .withParam("username", username) + .withParam("order_by", orderBy) + .withParam("sort", sort) + .withParam("page", page) + .withParam(PER_PAGE_PARAM, perPage); + + Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "pipelines"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of pipelines in a project. + * + * GET /projects/:id/pipelines + * + * @param projectId the project ID to get the list of pipelines for + * @param scope the scope of pipelines, one of: RUNNING, PENDING, FINISHED, BRANCHES, TAGS + * @param status the status of pipelines, one of: RUNNING, PENDING, SUCCESS, FAILED, CANCELED, SKIPPED + * @param ref the ref of pipelines + * @param yamlErrors returns pipelines with invalid configurations + * @param name the name of the user who triggered pipelines + * @param username the username of the user who triggered pipelines + * @param orderBy order pipelines by ID, STATUS, REF, USER_ID (default: ID) + * @param sort sort pipelines in ASC or DESC order (default: DESC) + * @param itemsPerPage the number of Pipeline instances that will be fetched per page + * @return a list containing the pipelines for the specified project ID + * @throws GitLabApiException if any exception occurs during execution + */ + public Pager getPipelines(int projectId, PipelineScope scope, PipelineStatus status, String ref, boolean yamlErrors, + String name, String username, PipelineOrderBy orderBy, SortOrder sort, int itemsPerPage) throws GitLabApiException { + GitLabApiForm formData = new GitLabApiForm() + .withParam("scope", scope) + .withParam("status", status) + .withParam("ref", ref) + .withParam("yaml_errors", yamlErrors) + .withParam("name", name) + .withParam("username", username) + .withParam("order_by", orderBy) + .withParam("sort", sort); + + return (new Pager(this, Pipeline.class, itemsPerPage, formData.asMap(), "projects", projectId, "pipelines")); } /** diff --git a/src/main/java/org/gitlab4j/api/ProjectApi.java b/src/main/java/org/gitlab4j/api/ProjectApi.java index d67f716b9b75f200358d278999d20e9b1c564415..a4b2541868dd8ece4cd58e649b18372453e00ced 100644 --- a/src/main/java/org/gitlab4j/api/ProjectApi.java +++ b/src/main/java/org/gitlab4j/api/ProjectApi.java @@ -23,21 +23,19 @@ public class ProjectApi extends AbstractApi implements Constants { public ProjectApi(GitLabApi gitLabApi) { super(gitLabApi); - } + } /** * Get a list of projects accessible by the authenticated user. * * GET /projects - * + * * @return a list of projects accessible by the authenticated user * @throws GitLabApiException if any exception occurs */ public List getProjects() throws GitLabApiException { - Form formData = new GitLabApiForm().withParam("per_page", getDefaultPerPage()); - Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects"); + return (response.readEntity(new GenericType>() {})); } /** @@ -51,14 +49,23 @@ public class ProjectApi extends AbstractApi implements Constants { * @throws GitLabApiException if any exception occurs */ public List getProjects(int page, int perPage) throws GitLabApiException { - GitLabApiForm formData = new GitLabApiForm() - .withParam("page", page, false) - .withParam("per_page", perPage, false); - Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects"); + return (response.readEntity(new GenericType>() { })); } - + + /** + * Get a Pager instance of projects accessible by the authenticated user. + * + * GET /projects + * + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager instance of projects accessible by the authenticated user + * @throws GitLabApiException if any exception occurs + */ + public Pager getProjects(int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Project.class, itemsPerPage, null, "projects")); + } + /** * Get a list of projects accessible by the authenticated user and matching the supplied filter parameters. * All filter parameters are optional. @@ -77,7 +84,7 @@ public class ProjectApi extends AbstractApi implements Constants { * @param statistics include project statistics * @return a list of projects accessible by the authenticated user and matching the supplied parameters * @throws GitLabApiException if any exception occurs - * @deprecated Will be removed in version 5.0, replaced by {@link #getProjects(Boolean, Visibility, + * @deprecated Will be removed in version 5.0, replaced by {@link #getProjects(Boolean, Visibility, * Constants.ProjectOrderBy, Constants.SortOrder, String, Boolean, Boolean, Boolean, Boolean, Boolean)} */ public List getProjects(Boolean archived, Visibility visibility, String orderBy, @@ -95,11 +102,10 @@ public class ProjectApi extends AbstractApi implements Constants { .withParam("membership", membership) .withParam("starred", starred) .withParam("statistics", statistics) - .withParam("per_page", getDefaultPerPage()); + .withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); } /** @@ -110,7 +116,7 @@ public class ProjectApi extends AbstractApi implements Constants { * * @param archived limit by archived status * @param visibility limit by visibility public, internal, or private - * @param orderBy return projects ordered by ID, NAME, PATH, CREATED_AT, UPDATED_AT, or + * @param orderBy return projects ordered by ID, NAME, PATH, CREATED_AT, UPDATED_AT, or * LAST_ACTIVITY_AT fields, default is CREATED_AT * @param sort return projects sorted in asc or desc order. Default is desc * @param search return list of projects matching the search criteria @@ -137,11 +143,94 @@ public class ProjectApi extends AbstractApi implements Constants { .withParam("membership", membership) .withParam("starred", starred) .withParam("statistics", statistics) - .withParam("per_page", getDefaultPerPage()); + .withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of projects accessible by the authenticated user and matching the supplied filter parameters. + * All filter parameters are optional. + * + * GET /projects + * + * @param archived limit by archived status + * @param visibility limit by visibility public, internal, or private + * @param orderBy return projects ordered by ID, NAME, PATH, CREATED_AT, UPDATED_AT, or + * LAST_ACTIVITY_AT fields, default is CREATED_AT + * @param sort return projects sorted in asc or desc order. Default is desc + * @param search return list of projects matching the search criteria + * @param simple return only the ID, URL, name, and path of each project + * @param owned limit by projects owned by the current user + * @param membership limit by projects that the current user is a member of + * @param starred limit by projects starred by the current user + * @param statistics include project statistics + * @param page the page to get + * @param perPage the number of projects per page + * @return a list of projects accessible by the authenticated user and matching the supplied parameters + * @throws GitLabApiException if any exception occurs + */ + public List getProjects(Boolean archived, Visibility visibility, ProjectOrderBy orderBy, + SortOrder sort, String search, Boolean simple, Boolean owned, Boolean membership, + Boolean starred, Boolean statistics, int page, int perPage) throws GitLabApiException { + + GitLabApiForm formData = new GitLabApiForm() + .withParam("archived", archived) + .withParam("visibility", visibility) + .withParam("order_by", orderBy) + .withParam("sort", sort) + .withParam("search", search) + .withParam("simple", simple) + .withParam("owned", owned) + .withParam("membership", membership) + .withParam("starred", starred) + .withParam("statistics", statistics) + .withParam(PAGE_PARAM, page) + .withParam(PER_PAGE_PARAM, perPage); + + Response response = get(Response.Status.OK, formData.asMap(), "projects"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of projects accessible by the authenticated user and matching the supplied filter parameters. + * All filter parameters are optional. + * + * GET /projects + * + * @param archived limit by archived status + * @param visibility limit by visibility public, internal, or private + * @param orderBy return projects ordered by ID, NAME, PATH, CREATED_AT, UPDATED_AT, or + * LAST_ACTIVITY_AT fields, default is CREATED_AT + * @param sort return projects sorted in asc or desc order. Default is desc + * @param search return list of projects matching the search criteria + * @param simple return only the ID, URL, name, and path of each project + * @param owned limit by projects owned by the current user + * @param membership limit by projects that the current user is a member of + * @param starred limit by projects starred by the current user + * @param statistics include project statistics + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of projects accessible by the authenticated user and matching the supplied parameters + * @throws GitLabApiException if any exception occurs + */ + public Pager getProjects(Boolean archived, Visibility visibility, ProjectOrderBy orderBy, + SortOrder sort, String search, Boolean simple, Boolean owned, Boolean membership, + Boolean starred, Boolean statistics, int itemsPerPage) throws GitLabApiException { + + GitLabApiForm formData = new GitLabApiForm() + .withParam("archived", archived) + .withParam("visibility", visibility) + .withParam("order_by", orderBy) + .withParam("sort", sort) + .withParam("search", search) + .withParam("simple", simple) + .withParam("owned", owned) + .withParam("membership", membership) + .withParam("starred", starred) + .withParam("statistics", statistics); + + return (new Pager(this, Project.class, itemsPerPage, formData.asMap(), "projects")); } /** @@ -154,33 +243,92 @@ public class ProjectApi extends AbstractApi implements Constants { * @throws GitLabApiException if any exception occurs */ public List getProjects(String search) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("search", search).withParam(PER_PAGE_PARAM, getDefaultPerPage()); + Response response = get(Response.Status.OK, formData.asMap(), "projects"); + return (response.readEntity(new GenericType>() {})); + } - Form formData = new GitLabApiForm().withParam("search", search).withParam("per_page", getDefaultPerPage()); + /** + * Get a list of projects accessible by the authenticated user that match the provided search string. + * + * GET /projects?search=search + * + * @param search the project name search criteria + * @param page the page to get + * @param perPage the number of projects per page + * @return a list of projects accessible by the authenticated user that match the provided search string + * @throws GitLabApiException if any exception occurs + */ + public List getProjects(String search, int page, int perPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("search", search).withParam(PAGE_PARAM, page).withParam(PER_PAGE_PARAM, perPage); Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of projects accessible by the authenticated user that match the provided search string. + * + * GET /projects?search=search + * + * @param search the project name search criteria + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of projects accessible by the authenticated user that match the provided search string + * @throws GitLabApiException if any exception occurs + */ + public Pager getProjects(String search, int itemsPerPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("search", search); + return (new Pager(this, Project.class, itemsPerPage, formData.asMap(), "projects")); } /** * Get a list of projects that the authenticated user is a member of. * * GET /projects - * + * * @return a list of projects that the authenticated user is a member of * @throws GitLabApiException if any exception occurs */ public List getMemberProjects() throws GitLabApiException { - Form formData = new GitLabApiForm().withParam("membership", true).withParam("per_page", getDefaultPerPage()); + Form formData = new GitLabApiForm().withParam("membership", true).withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of projects that the authenticated user is a member of in the specified page range. + * + * GET /projects + * + * @param page the page to get + * @param perPage the number of projects per page + * @return a list of projects that the authenticated user is a member of + * @throws GitLabApiException if any exception occurs + */ + public List getMemberProjects(int page, int perPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("membership", true).withParam(PAGE_PARAM, page).withParam(PER_PAGE_PARAM, perPage); + Response response = get(Response.Status.OK, formData.asMap(), "projects"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of projects that the authenticated user is a member of. + * + * GET /projects + * + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager o Project instances that the authenticated user is a member of + * @throws GitLabApiException if any exception occurs + */ + public Pager getMemberProjects(int itemsPerPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("membership", true); + return (new Pager(this, Project.class, itemsPerPage, formData.asMap(), "projects")); } /** * Get a list of all GitLab projects (admin only). * * GET /projects/all - * + * * @return a list of all GitLab projects * @throws GitLabApiException if any exception occurs * @deprecated Will be removed, no longer supported by the GitLab API @@ -191,10 +339,9 @@ public class ProjectApi extends AbstractApi implements Constants { throw new GitLabApiException("Not supported by GitLab API version " + this.getApiVersion()); } - Form formData = new GitLabApiForm().withParam("per_page", getDefaultPerPage()); + Form formData = new GitLabApiForm().withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "projects", "all"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); } /** @@ -206,36 +353,90 @@ public class ProjectApi extends AbstractApi implements Constants { * @throws GitLabApiException if any exception occurs */ public List getOwnedProjects() throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("owned", true).withParam(PER_PAGE_PARAM, getDefaultPerPage()); + Response response = get(Response.Status.OK, formData.asMap(), "projects"); + return (response.readEntity(new GenericType>() { })); + } - Form formData = new GitLabApiForm().withParam("owned", true).withParam("per_page", getDefaultPerPage()); + /** + * Get a list of projects owned by the authenticated user in the specified page range. + * + * GET /projects + * + * @param page the page to get + * @param perPage the number of projects per page + * @return a list of projects owned by the authenticated user + * @throws GitLabApiException if any exception occurs + */ + public List getOwnedProjects(int page, int perPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("owned", true).withParam(PAGE_PARAM, page).withParam(PER_PAGE_PARAM, perPage); Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of projects owned by the authenticated user. + * + * GET /projects + * + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a list of projects owned by the authenticated user + * @throws GitLabApiException if any exception occurs + */ + public Pager getOwnedProjects(int itemsPerPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("owned", true); + return (new Pager(this, Project.class, itemsPerPage, formData.asMap(), "projects")); } /** * Get a list of projects starred by the authenticated user. - * + * * GET /projects - * + * * @return a list of projects starred by the authenticated user * @throws GitLabApiException if any exception occurs */ public List getStarredProjects() throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("starred", true).withParam(PER_PAGE_PARAM, getDefaultPerPage()); + Response response = get(Response.Status.OK, formData.asMap(), "projects"); + return (response.readEntity(new GenericType>() {})); + } - Form formData = new GitLabApiForm() - .withParam("starred", true) - .withParam("per_page", getDefaultPerPage()); + /** + * Get a list of projects starred by the authenticated user in the specified page range. + * + * GET /projects + * + * @param page the page to get + * @param perPage the number of projects per page + * @return a list of projects starred by the authenticated user + * @throws GitLabApiException if any exception occurs + */ + public List getStarredProjects(int page, int perPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("starred", true).withParam(PAGE_PARAM, page).withParam(PER_PAGE_PARAM, perPage); Response response = get(Response.Status.OK, formData.asMap(), "projects"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of projects starred by the authenticated user. + * + * GET /projects + * + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of projects starred by the authenticated user + * @throws GitLabApiException if any exception occurs + */ + public Pager getStarredProjects(int itemsPerPage) throws GitLabApiException { + Form formData = new GitLabApiForm().withParam("starred", true).withParam(PER_PAGE_PARAM, getDefaultPerPage()); + return (new Pager(this, Project.class, itemsPerPage, formData.asMap(), "projects")); } /** * Get a specific project, which is owned by the authentication user. * * GET /projects/:id - * + * * @param projectId the ID of the project to get * @return the specified project * @throws GitLabApiException if any exception occurs @@ -249,7 +450,7 @@ public class ProjectApi extends AbstractApi implements Constants { * Get a specific project, which is owned by the authentication user. * * GET /projects/:id - * + * * @param namespace the name of the project namespace or group * @param project the name of the project to get * @return the specified project @@ -278,7 +479,7 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Create a new project in the specified group. - * + * * @param groupId the group ID to create the project under * @param projectName the name of the project top create * @return the created project @@ -286,33 +487,27 @@ public class ProjectApi extends AbstractApi implements Constants { */ public Project createProject(Integer groupId, String projectName) throws GitLabApiException { - GitLabApiForm formData = new GitLabApiForm() - .withParam("namespace_id", groupId) - .withParam("name", projectName, true); - + GitLabApiForm formData = new GitLabApiForm().withParam("namespace_id", groupId).withParam("name", projectName, true); Response response = post(Response.Status.CREATED, formData, "projects"); return (response.readEntity(Project.class)); } /** * Create a new project with the current user's namespace. - * + * * @param projectName the name of the project top create * @return the created project * @throws GitLabApiException if any exception occurs */ public Project createProject(String projectName) throws GitLabApiException { - - GitLabApiForm formData = new GitLabApiForm() - .withParam("name", projectName, true); - + GitLabApiForm formData = new GitLabApiForm().withParam("name", projectName, true); Response response = post(Response.Status.CREATED, formData, "projects"); return (response.readEntity(Project.class)); } /** * Creates new project owned by the current user. - * + * * @param project the Project instance with the configuration for the new project * @return a Project instance with the newly created project info * @throws GitLabApiException if any exception occurs @@ -324,7 +519,7 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Creates new project owned by the current user. The following properties on the Project instance * are utilized in the creation of the project: - * + * * name (name or path are required) - new project name * path (name or path are required) - new project path * defaultBranch (optional) - master by default @@ -345,7 +540,7 @@ public class ProjectApi extends AbstractApi implements Constants { * requestAccessEnabled (optional) - Allow users to request member access * repositoryStorage (optional) - Which storage shard the repository is on. Available only to admins * approvalsBeforeMerge (optional) - How many approvers should approve merge request by default - * + * * @param project the Project instance with the configuration for the new project * @param importUrl the URL to import the repository from * @return a Project instance with the newly created project info @@ -497,9 +692,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Removes project with all resources(issues, merge requests etc). - * + * * DELETE /projects/:id - * + * * @param projectId the project ID to remove * @throws GitLabApiException if any exception occurs */ @@ -515,9 +710,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Removes project with all resources(issues, merge requests etc). - * + * * DELETE /projects/:id - * + * * @param project the Project instance to remove * @throws GitLabApiException if any exception occurs */ @@ -527,24 +722,53 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Get a list of project team members. - * + * * GET /projects/:id/members - * + * * @param projectId the project ID to get team members for * @return the members belonging to the specified project * @throws GitLabApiException if any exception occurs */ public List getMembers(Integer projectId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "projects", projectId, "members"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, this.getDefaultPerPageParam(), "projects", projectId, "members"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of project team members in the specified page range. + * + * GET /projects/:id/members + * + * @param projectId the project ID to get team members for + * @param page the page to get + * @param perPage the number of Member instances per page + * @return the members belonging to the specified project + * @throws GitLabApiException if any exception occurs + */ + public List getMembers(Integer projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "members"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of project team members. + * + * GET /projects/:id/members + * + * @param projectId the project ID to get team members for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return the members belonging to the specified project + * @throws GitLabApiException if any exception occurs + */ + public Pager getMembers(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Member.class, itemsPerPage, null, "projects", projectId, "members")); } /** * Gets a project team member. - * + * * GET /projects/:id/members/:user_id - * + * * @param projectId the project ID to get team member for * @param userId the user ID of the member * @return the member specified by the project ID/user ID pair @@ -559,9 +783,9 @@ public class ProjectApi extends AbstractApi implements Constants { * Adds a user to a project team. This is an idempotent method and can be called multiple times * with the same parameters. Adding team membership to a user that is already a member does not * affect the existing membership. - * + * * POST /projects/:id/members - * + * * @param projectId the project ID to add the team member to * @param userId the user ID of the member to add * @param accessLevel the access level for the new member @@ -569,19 +793,16 @@ public class ProjectApi extends AbstractApi implements Constants { * @throws GitLabApiException if any exception occurs */ public Member addMember(Integer projectId, Integer userId, Integer accessLevel) throws GitLabApiException { - - GitLabApiForm formData = new GitLabApiForm() - .withParam("user_id", userId, true) - .withParam("access_level", accessLevel, true); + GitLabApiForm formData = new GitLabApiForm().withParam("user_id", userId, true).withParam("access_level", accessLevel, true); Response response = post(Response.Status.CREATED, formData, "projects", projectId, "members"); return (response.readEntity(Member.class)); } /** * Removes user from project team. - * + * * DELETE /projects/:id/members/:user_id - * + * * @param projectId the project ID to remove the team member from * @param userId the user ID of the member to remove * @throws GitLabApiException if any exception occurs @@ -592,40 +813,98 @@ public class ProjectApi extends AbstractApi implements Constants { } /** - * Get a project events for specific project. Sorted from newest to latest. - * + * Get the project events for specific project. Sorted from newest to latest. + * * GET /projects/:id/events - * + * * @param projectId the project ID to get events for * @return the project events for the specified project * @throws GitLabApiException if any exception occurs */ public List getProjectEvents(Integer projectId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "projects", projectId, "events"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "events"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get the project events for specific project. Sorted from newest to latest in the specified page range. + * + * GET /projects/:id/events + * + * @param projectId the project ID to get events for + * @param page the page to get + * @param perPage the number of Event instances per page + * @return the project events for the specified project + * @throws GitLabApiException if any exception occurs + */ + public List getProjectEvents(Integer projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "events"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of project events for specific project. Sorted from newest to latest. + * + * GET /projects/:id/events + * + * @param projectId the project ID to get events for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of project events for the specified project + * @throws GitLabApiException if any exception occurs + */ + public Pager getProjectEvents(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Event.class, itemsPerPage, null, "projects", projectId, "events")); } /** * Get list of project hooks. - * + * * GET /projects/:id/hooks - * + * * @param projectId the project ID to get project hooks for * @return a list of project hooks for the specified project * @throws GitLabApiException if any exception occurs */ public List getHooks(Integer projectId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "projects", projectId, "hooks"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "hooks"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get list of project hooks in the specified page range. + * + * GET /projects/:id/hooks + * + * @param projectId the project ID to get project hooks for + * @param page the page to get + * @param perPage the number of ProjectHook instances per page + * @return a list of project hooks for the specified project in the specified page range + * @throws GitLabApiException if any exception occurs + */ + public List getHooks(Integer projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "hooks"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get Pager of project hooks. + * + * GET /projects/:id/hooks + * + * @param projectId the project ID to get project hooks for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of project hooks for the specified project + * @throws GitLabApiException if any exception occurs + */ + public Pager getHooks(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, ProjectHook.class, itemsPerPage, null, "projects", projectId, "hooks")); } /** * Get a specific hook for project. - * + * * GET /projects/:id/hooks/:hook_id - * + * * @param projectId the project ID to get the hook for * @param hookId the ID of the hook to get * @return the project hook for the specified project ID/hook ID pair @@ -635,12 +914,12 @@ public class ProjectApi extends AbstractApi implements Constants { Response response = get(Response.Status.OK, null, "projects", projectId, "hooks", hookId); return (response.readEntity(ProjectHook.class)); } - + /** * Adds a hook to project. - * + * * POST /projects/:id/hooks - * + * * @param projectName the name of the project * @param url the callback URL for the hook * @param enabledHooks a ProjectHook instance specifying which hooks to enable @@ -654,7 +933,7 @@ public class ProjectApi extends AbstractApi implements Constants { if (projectName == null) { return (null); } - + GitLabApiForm formData = new GitLabApiForm() .withParam("url", url, true) .withParam("push_events", enabledHooks.getPushEvents(), false) @@ -673,9 +952,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Adds a hook to project. - * + * * POST /projects/:id/hooks - * + * * @param projectId the project ID to add the project hook to * @param url the callback URL for the hook * @param enabledHooks a ProjectHook instance specifying which hooks to enable @@ -689,7 +968,7 @@ public class ProjectApi extends AbstractApi implements Constants { if (projectId == null) { return (null); } - + GitLabApiForm formData = new GitLabApiForm() .withParam("url", url, true) .withParam("push_events", enabledHooks.getPushEvents(), false) @@ -708,9 +987,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Adds a hook to project. - * + * * POST /projects/:id/hooks - * + * * @param project the Project instance to add the project hook to * @param url the callback URL for the hook * @param enabledHooks a ProjectHook instance specifying which hooks to enable @@ -730,9 +1009,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Adds a hook to project. - * + * * POST /projects/:id/hooks - * + * * @param project the Project instance to add the project hook to * @param url the callback URL for the hook * @param doPushEvents flag specifying whether to do push events @@ -752,9 +1031,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Adds a hook to project. - * + * * POST /projects/:id/hooks - * + * * @param projectId the project ID to add the project hook to * @param url the callback URL for the hook * @param doPushEvents flag specifying whether to do push events @@ -777,9 +1056,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Deletes a hook from the project. - * + * * DELETE /projects/:id/hooks/:hook_id - * + * * @param projectId the project ID to delete the project hook from * @param hookId the project hook ID to delete * @throws GitLabApiException if any exception occurs @@ -791,9 +1070,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Deletes a hook from the project. - * + * * DELETE /projects/:id/hooks/:hook_id - * + * * @param hook the ProjectHook instance to remove * @throws GitLabApiException if any exception occurs */ @@ -803,9 +1082,9 @@ public class ProjectApi extends AbstractApi implements Constants { /** * Modifies a hook for project. - * + * * PUT /projects/:id/hooks/:hook_id - * + * * @param hook the ProjectHook instance that contains the project hook info to modify * @return the modified project hook * @throws GitLabApiException if any exception occurs @@ -839,10 +1118,8 @@ public class ProjectApi extends AbstractApi implements Constants { * @throws GitLabApiException if any exception occurs */ public List getIssues(Integer projectId) throws GitLabApiException { - Form formData = new GitLabApiForm().withParam("per_page", getDefaultPerPage()); - Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "issues"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "issues"); + return (response.readEntity(new GenericType>() {})); } /** @@ -857,12 +1134,21 @@ public class ProjectApi extends AbstractApi implements Constants { * @throws GitLabApiException if any exception occurs */ public List getIssues(Integer projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "issues"); + return (response.readEntity(new GenericType>() {})); + } - GitLabApiForm formData = new GitLabApiForm() - .withParam("page", page, false) - .withParam("per_page", perPage, false); - Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "issues"); - return (response.readEntity(new GenericType>() { - })); + /** + * Get a Pager of project's issues. + * + * GET /projects/:id/issues + * + * @param projectId the project ID to get the issues for + * @param itemsPerPage the number of issues per page + * @return the list of issues in the specified range + * @throws GitLabApiException if any exception occurs + */ + public Pager getIssues(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Issue.class, itemsPerPage, null, "projects", projectId, "issues")); } } diff --git a/src/main/java/org/gitlab4j/api/RepositoryApi.java b/src/main/java/org/gitlab4j/api/RepositoryApi.java index 65e06a0faaecd41e0cc90db507e50854615d2e26..31b0b8663d1cf7d30ded1a95b2c2cbfd92753358 100644 --- a/src/main/java/org/gitlab4j/api/RepositoryApi.java +++ b/src/main/java/org/gitlab4j/api/RepositoryApi.java @@ -28,25 +28,54 @@ public class RepositoryApi extends AbstractApi { /** * Get a list of repository branches from a project, sorted by name alphabetically. - * + * * GET /projects/:id/repository/branches - * + * * @param projectId the project to get the list of branches for * @return the list of repository branches for the specified project ID * @throws GitLabApiException if any exception occurs */ public List getBranches(Integer projectId) throws GitLabApiException { - Form formData = new GitLabApiForm().withParam("per_page", getDefaultPerPage()); - Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "repository", "branches"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "repository", "branches"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of repository branches from a project, sorted by name alphabetically. + * + * GET /projects/:id/repository/branches + * + * @param projectId the project to get the list of branches for + * @return the list of repository branches for the specified project ID + * @param page the page to get + * @param perPage the number of Branch instances per page + * @throws GitLabApiException if any exception occurs + */ + public List getBranches(Integer projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "repository", "branches"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of repository branches from a project, sorted by name alphabetically. + * + * GET /projects/:id/repository/branches + * + * @param projectId the project to get the list of branches for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return the list of repository branches for the specified project ID + * + * @throws GitLabApiException if any exception occurs + */ + public Pager getBranches(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Branch.class, itemsPerPage, null, "projects", projectId, "repository", "branches")); } /** * Get a single project repository branch. - * + * * GET /projects/:id/repository/branches/:branch - * + * * @param projectId the project to get the branch for * @param branchName the name of the branch to get * @return the branch info for the specified project ID/branch name pair @@ -59,9 +88,9 @@ public class RepositoryApi extends AbstractApi { /** * Creates a branch for the project. Support as of version 6.8.x - * + * * POST /projects/:id/repository/branches - * + * * @param projectId the project to create the branch for * @param branchName the name of the branch to create * @param ref Source to create the branch from, can be an existing branch, tag or commit SHA @@ -81,9 +110,9 @@ public class RepositoryApi extends AbstractApi { /** * Delete a single project repository branch. This is an idempotent function, * protecting an already protected repository branch will not produce an error. - * + * * DELETE /projects/:id/repository/branches/:branch - * + * * @param projectId the project that the branch belongs to * @param branchName the name of the branch to delete * @throws GitLabApiException if any exception occurs @@ -96,9 +125,9 @@ public class RepositoryApi extends AbstractApi { /** * Protects a single project repository branch. This is an idempotent function, * protecting an already protected repository branch will not produce an error. - * + * * PUT /projects/:id/repository/branches/:branch/protect - * + * * @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 @@ -112,9 +141,9 @@ public class RepositoryApi extends AbstractApi { /** * Unprotects a single project repository branch. This is an idempotent function, unprotecting an * already unprotected repository branch will not produce an error. - * + * * PUT /projects/:id/repository/branches/:branch/unprotect - * + * * @param projectId the ID of the project to un-protect * @param branchName the name of the branch to un-protect * @return the branch info for the unprotected branch @@ -127,24 +156,53 @@ public class RepositoryApi extends AbstractApi { /** * Get a list of repository tags from a project, sorted by name in reverse alphabetical order. - * + * * GET /projects/:id/repository/tags - * + * * @param projectId the ID of the project to get the tags for * @return the list of tags for the specified project ID * @throws GitLabApiException if any exception occurs */ public List getTags(Integer projectId) throws GitLabApiException { - Response response = get(Response.Status.OK, null, "projects", projectId, "repository", "tags"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "projects", projectId, "repository", "tags"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a list of repository tags from a project, sorted by name in reverse alphabetical order and in the specified page range. + * + * GET /projects/:id/repository/tags + * + * @param projectId the ID of the project to get the tags for + * @param page the page to get + * @param perPage the number of Tag instances per page + * @return the list of tags for the specified project ID + * @throws GitLabApiException if any exception occurs + */ + public List getTags(Integer projectId, int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "projects", projectId, "repository", "tags"); + return (response.readEntity(new GenericType>() {})); } - + + /** + * Get a list of repository tags from a project, sorted by name in reverse alphabetical order. + * + * GET /projects/:id/repository/tags + * + * @param projectId the ID of the project to get the tags for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return the list of tags for the specified project ID + * @throws GitLabApiException if any exception occurs + */ + public Pager getTags(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (new Pager(this, Tag.class, itemsPerPage, null, "projects", projectId, "repository", "tags")); + } + /** * Creates a tag on a particular ref of the given project. A message and release notes are optional. - * + * * POST /projects/:id/repository/tags - * + * * @param projectId the ID of the project * @param tagName The name of the tag Must be unique for the project * @param ref the git ref to place the tag on @@ -168,9 +226,9 @@ public class RepositoryApi extends AbstractApi { * Creates a tag on a particular ref of a given project. A message and a File instance containing the * release notes are optional. This method is the same as {@link #createTag(Integer, String, String, String, String)}, * but instead allows the release notes to be supplied in a file. - * + * * POST /projects/:id/repository/tags - * + * * @param projectId the ID of the project * @param tagName the name of the tag, must be unique for the project * @param ref the git ref to place the tag on @@ -180,7 +238,7 @@ public class RepositoryApi extends AbstractApi { * @throws GitLabApiException if any exception occurs */ public Tag createTag(Integer projectId, String tagName, String ref, String message, File releaseNotesFile) throws GitLabApiException { - + String releaseNotes; if (releaseNotesFile != null) { try { @@ -197,9 +255,9 @@ public class RepositoryApi extends AbstractApi { /** * Deletes the tag from a project with the specified tag name. - * + * * DELETE /projects/:id/repository/tags/:tag_name - * + * * @param projectId the ID of the project * @param tagName The name of the tag to delete * @throws GitLabApiException if any exception occurs @@ -211,15 +269,29 @@ public class RepositoryApi extends AbstractApi { /** * Get a list of repository files and directories in a project. - * + * * GET /projects/:id/repository/tree - * + * * @param projectId the ID of the project to get the files for * @return a tree with the root directories and files of a project * @throws GitLabApiException if any exception occurs */ public List getTree(Integer projectId) throws GitLabApiException { - return this.getTree(projectId, "/", "master"); + return (getTree(projectId, "/", "master")); + } + + /** + * Get a Pager of repository files and directories in a project. + * + * GET /projects/:id/repository/tree + * + * @param projectId the ID of the project to get the files for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager containing a tree with the root directories and files of a project + * @throws GitLabApiException if any exception occurs + */ + public Pager getTree(Integer projectId, int itemsPerPage) throws GitLabApiException { + return (getTree(projectId, "/", "master", false, itemsPerPage)); } /** @@ -230,7 +302,7 @@ public class RepositoryApi extends AbstractApi { * id (required) - The ID of a project * path (optional) - The path inside repository. Used to get content of subdirectories * ref_name (optional) - The name of a repository branch or tag or if not given the default branch - * + * * @param projectId the ID of the project to get the files for * @param filePath the path inside repository, used to get content of subdirectories * @param refName the name of a repository branch or tag or if not given the default branch @@ -241,6 +313,26 @@ public class RepositoryApi extends AbstractApi { return (getTree(projectId, filePath, refName, false)); } + /** + * Get a Pager of repository files and directories in a project. + * + * GET /projects/:id/repository/tree + * + * id (required) - The ID of a project + * path (optional) - The path inside repository. Used to get content of subdirectories + * ref_name (optional) - The name of a repository branch or tag or if not given the default branch + * + * @param projectId the ID of the project to get the files for + * @param filePath the path inside repository, used to get content of subdirectories + * @param refName the name of a repository branch or tag or if not given the default branch + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager containing a tree with the directories and files of a project + * @throws GitLabApiException if any exception occurs + */ + public Pager getTree(Integer projectId, String filePath, String refName, int itemsPerPage) throws GitLabApiException { + return (getTree(projectId, filePath, refName, false, itemsPerPage)); + } + /** * Get a list of repository files and directories in a project. * @@ -263,10 +355,37 @@ public class RepositoryApi extends AbstractApi { .withParam("id", projectId, true) .withParam("path", filePath, false) .withParam("ref_name", refName, false) - .withParam("recursive", recursive, false); + .withParam("recursive", recursive, false) + .withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "repository", "tree"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Get a Pager of repository files and directories in a project. + * + * GET /projects/:id/repository/tree + * + * id (required) - The ID of a project + * path (optional) - The path inside repository. Used to get contend of subdirectories + * ref_name (optional) - The name of a repository branch or tag or if not given the default branch + * recursive (optional) - Boolean value used to get a recursive tree (false by default) + * + * @param projectId the ID of the project to get the files for + * @param filePath the path inside repository, used to get content of subdirectories + * @param refName the name of a repository branch or tag or if not given the default branch + * @param recursive flag to get a recursive tree or not + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a tree with the directories and files of a project + * @throws GitLabApiException if any exception occurs + */ + public Pager getTree(Integer projectId, String filePath, String refName, Boolean recursive, int itemsPerPage) throws GitLabApiException { + Form formData = new GitLabApiForm() + .withParam("id", projectId, true) + .withParam("path", filePath, false) + .withParam("ref_name", refName, false) + .withParam("recursive", recursive, false); + return (new Pager(this, TreeItem.class, itemsPerPage, formData.asMap(), "projects", projectId, "repository", "tree")); } /** @@ -280,25 +399,25 @@ public class RepositoryApi extends AbstractApi { * @return a string with the file content for the specified file * @throws GitLabApiException if any exception occurs */ - public String getRawFileContent(Integer projectId, String commitOrBranchName, String filepath) throws GitLabApiException { + public InputStream getRawFileContent(Integer projectId, String commitOrBranchName, String filepath) throws GitLabApiException { Form formData = new GitLabApiForm().withParam("filepath", filepath, true); Response response = get(Response.Status.OK, formData.asMap(), "projects", projectId, "repository", "blobs", commitOrBranchName); - return (response.readEntity(String.class)); + return (response.readEntity(InputStream.class)); } /** * Get the raw file contents for a blob by blob SHA. - * + * * GET /projects/:id/repository/raw_blobs/:sha - * - * @param projectId the ID of the project + * + * @param projectId the ID of the project * @param sha the SHA of the file to get the contents for - * @return the raw file contents for the blob + * @return the raw file contents for the blob on an InputStream * @throws GitLabApiException if any exception occurs */ - public String getRawBlobCotent(Integer projectId, String sha) throws GitLabApiException { + public InputStream getRawBlobContent(Integer projectId, String sha) throws GitLabApiException { Response response = get(Response.Status.OK, null, "projects", projectId, "repository", "raw_blobs", sha); - return (response.readEntity(String.class)); + return (response.readEntity(InputStream.class)); } /** @@ -306,7 +425,7 @@ public class RepositoryApi extends AbstractApi { * * GET /projects/:id/repository/archive * - * @param projectId the ID of the project + * @param projectId the ID of the project * @param sha the SHA of the archive to get * @return an input stream that can be used to save as a file * or to read the content of the archive @@ -324,7 +443,7 @@ public class RepositoryApi extends AbstractApi { * * GET /projects/:id/repository/archive * - * @param projectId the ID of the project + * @param projectId the ID of the project * @param sha the SHA of the archive to get * @param directory the File instance of the directory to save the archive to, if null will use "java.io.tmpdir" * @return a File instance pointing to the downloaded instance diff --git a/src/main/java/org/gitlab4j/api/SessionApi.java b/src/main/java/org/gitlab4j/api/SessionApi.java index 7dfb120cb14bea7625f947c6446c25f7ca1ef7ab..1cf92eb7889d9fd0778e24960cb7ee081b33e6c4 100644 --- a/src/main/java/org/gitlab4j/api/SessionApi.java +++ b/src/main/java/org/gitlab4j/api/SessionApi.java @@ -16,9 +16,9 @@ public class SessionApi extends AbstractApi { /** * Login to get private token. - * + * * POST /session - * + * * @param username the username to login * @param email the email address to login * @param password the password of the user diff --git a/src/main/java/org/gitlab4j/api/UserApi.java b/src/main/java/org/gitlab4j/api/UserApi.java index 0eb805577de15c1987e1f7aec5a80d1dfa883bda..ac70c178419f47813e2803433edd04aa20fb7482 100644 --- a/src/main/java/org/gitlab4j/api/UserApi.java +++ b/src/main/java/org/gitlab4j/api/UserApi.java @@ -20,43 +20,50 @@ public class UserApi extends AbstractApi { /** * Get a list of users. Only returns the first page - * + * * GET /users - * + * * @return a list of Users, this list will only contain the first 20 users in the system. * @throws GitLabApiException if any exception occurs */ public List getUsers() throws GitLabApiException { - Response response = get(Response.Status.OK, null, "users"); - return (response.readEntity(new GenericType>() { - })); + Response response = get(Response.Status.OK, getDefaultPerPageParam(), "users"); + return (response.readEntity(new GenericType>() {})); } /** * Get a list of users using the specified page and per page settings. - * + * * GET /users - * + * * @param page the page to get * @param perPage the number of users per page * @return the list of Users in the specified range * @throws GitLabApiException if any exception occurs */ public List getUsers(int page, int perPage) throws GitLabApiException { + Response response = get(Response.Status.OK, getPageQueryParams(page, perPage), "users"); + return (response.readEntity(new GenericType>() {})); + } - GitLabApiForm formData = new GitLabApiForm() - .withParam("page", page, false) - .withParam("per_page", perPage, false); - Response response = get(Response.Status.OK, formData.asMap(), "users"); - return (response.readEntity(new GenericType>() { - })); + /** + * Get a Pager of users. + * + * GET /users + * + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return a Pager of User + * @throws GitLabApiException if any exception occurs + */ + public Pager getUsers(int itemsPerPage) throws GitLabApiException { + return (new Pager(this, User.class, itemsPerPage, null, "users")); } /** * Get a single user. - * + * * GET /users/:id - * + * * @param userId the ID of the user to get * @return the User instance for the specified user ID * @throws GitLabApiException if any exception occurs @@ -70,16 +77,47 @@ public class UserApi extends AbstractApi { * Search users by Email or username * * GET /users?search=:email_or_username - * + * * @param emailOrUsername the email or username to search for * @return the User List with the email or username like emailOrUsername * @throws GitLabApiException if any exception occurs */ public List findUsers(String emailOrUsername) throws GitLabApiException { - GitLabApiForm formData = new GitLabApiForm().withParam("search", emailOrUsername, true); + GitLabApiForm formData = new GitLabApiForm().withParam("search", emailOrUsername, true).withParam(PER_PAGE_PARAM, getDefaultPerPage()); Response response = get(Response.Status.OK, formData.asMap(), "users"); - return (response.readEntity(new GenericType>() { - })); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Search users by Email or username in the specified page range. + * + * GET /users?search=:email_or_username + * + * @param emailOrUsername the email or username to search for + * @param page the page to get + * @param perPage the number of users per page + * @return the User List with the email or username like emailOrUsername in the specified page range + * @throws GitLabApiException if any exception occurs + */ + public List findUsers(String emailOrUsername, int page, int perPage) throws GitLabApiException { + GitLabApiForm formData = new GitLabApiForm().withParam("search", emailOrUsername, true).withParam(PAGE_PARAM, page).withParam(PER_PAGE_PARAM, perPage); + Response response = get(Response.Status.OK, formData.asMap(), "users"); + return (response.readEntity(new GenericType>() {})); + } + + /** + * Search users by Email or username and return a Pager + * + * GET /users?search=:email_or_username + * + * @param emailOrUsername the email or username to search for + * @param itemsPerPage the number of Project instances that will be fetched per page + * @return the User Pager with the email or username like emailOrUsername + * @throws GitLabApiException if any exception occurs + */ + public Pager findUsers(String emailOrUsername, int itemsPerPage) throws GitLabApiException { + GitLabApiForm formData = new GitLabApiForm().withParam("search", emailOrUsername, true); + return (new Pager(this, User.class, itemsPerPage, formData.asMap(), "users")); } /** @@ -101,10 +139,10 @@ public class UserApi extends AbstractApi { * bio (optional) - User's bio * admin (optional) - User is admin - true or false (default) * can_create_group (optional) - User can create groups - true or false - * + * * @param user the User instance with the user info to create * @param password the password for the new user - * @param projectsLimit the maximum number of project + * @param projectsLimit the maximum number of project * @return created User instance * @throws GitLabApiException if any exception occurs */ @@ -116,9 +154,9 @@ public class UserApi extends AbstractApi { /** * Modifies an existing user. Only administrators can change attributes of a user. - * + * * PUT /users/:id - * + * * email (required) - Email * password (required) - Password * username (required) - Username @@ -133,10 +171,10 @@ public class UserApi extends AbstractApi { * bio (optional) - User's bio * admin (optional) - User is admin - true or false (default) * can_create_group (optional) - User can create groups - true or false - * + * * @param user the User instance with the user info to modify * @param password the new password for the user - * @param projectsLimit the maximum number of project + * @param projectsLimit the maximum number of project * @return the modified User instance * @throws GitLabApiException if any exception occurs */ @@ -148,9 +186,9 @@ public class UserApi extends AbstractApi { /** * Deletes a user. Available only for administrators. - * + * * DELETE /users/:id - * + * * @param userId the user ID to delete * @throws GitLabApiException if any exception occurs */ @@ -166,9 +204,9 @@ public class UserApi extends AbstractApi { /** * Deletes a user. Available only for administrators. - * + * * DELETE /users/:id - * + * * @param user the User instance to delete * @throws GitLabApiException if any exception occurs */ @@ -178,7 +216,7 @@ public class UserApi extends AbstractApi { /** * Populate the REST form with data from the User instance. - * + * * @param user the User iunstance to populate the Form instance with * @param projectsLimit the maximum number of projects the user is allowed (optional) * @param password the password, required when creating a new user