feat: added methods for Endpoint "/groups/:id/groups/shared"

gitlab4j-api/src/main/java/org/gitlab4j/api/GroupApi.java

@@ -34,6 +34,7 @@
 import org.gitlab4j.api.models.Member;
 import org.gitlab4j.api.models.Project;
 import org.gitlab4j.api.models.SamlGroupLink;
+import org.gitlab4j.api.models.SharedGroupsFilter;
 import org.gitlab4j.api.models.UploadedFile;
 import org.gitlab4j.api.models.Variable;
 import org.gitlab4j.api.models.Visibility;
@@ -595,6 +596,130 @@ public Stream<Project> getProjectsStream(Object groupIdOrPath) throws GitLabApiE
         return (getProjects(groupIdOrPath, getDefaultPerPage()).stream());
     }
 
+    /**
+     * Get a list of groups where the given group has been invited.
+     * When accessed without authentication, only public shared groups are returned.
+     *
+     * <pre><code>GitLab Endpoint: GET /groups/:id/groups/shared</code></pre>
+     *
+     * @param groupIdOrPath the group ID, path of the group, or a Group instance holding the group ID or path
+     * @param filter the SharedGroupsFilter instance holding the filter values for the query
+     * @return a List containing the Group instances the given group has been invited to and match the provided filter
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<Group> getSharedGroups(Object groupIdOrPath, SharedGroupsFilter filter) throws GitLabApiException {
+        return (getSharedGroups(groupIdOrPath, filter, getDefaultPerPage()).all());
+    }
+
+    /**
+     * Get a Pager of groups where the given group has been invited.
+     * When accessed without authentication, only public shared groups are returned.
+     *
+     * <pre><code>GitLab Endpoint: GET /groups/:id/groups/shared</code></pre>
+     *
+     * @param groupIdOrPath the group ID, path of the group, or a Group instance holding the group ID or path
+     * @param filter the SharedGroupsFilter instance holding the filter values for the query
+     * @param itemsPerPage the number of Group instances that will be fetched per page
+     * @return a Pager containing the Group instances the given group has been invited to and match the provided filter
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Group> getSharedGroups(Object groupIdOrPath, SharedGroupsFilter filter, int itemsPerPage)
+            throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm(filter.getQueryParams());
+        return (new Pager<Group>(
+                this,
+                Group.class,
+                itemsPerPage,
+                formData.asMap(),
+                "groups",
+                getGroupIdOrPath(groupIdOrPath),
+                "groups",
+                "shared"));
+    }
+
+    /**
+     * Get a Stream of groups where the given group has been invited.
+     * When accessed without authentication, only public shared groups are returned.
+     *
+     * <pre><code>GitLab Endpoint: GET /groups/:id/groups/shared</code></pre>
+     *
+     * @param groupIdOrPath the group ID, path of the group, or a Group instance holding the group ID or path
+     * @param filter the SharedGroupsFilter instance holding the filter values for the query
+     * @return a Stream containing the Group instances the given group has been invited to and match the provided filter
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Stream<Group> getSharedGroupsStream(Object groupIdOrPath, SharedGroupsFilter filter)
+            throws GitLabApiException {
+        return (getSharedGroups(groupIdOrPath, filter, getDefaultPerPage()).stream());
+    }
+
+    /**
+     * Get a list of groups where the given group has been invited.
+     * When accessed without authentication, only public shared groups are returned.
+     *
+     * <pre><code>GitLab Endpoint: GET /groups/:id/groups/shared</code></pre>
+     *
+     * @param groupIdOrPath the group ID, path of the group, or a Group instance holding the group ID or path
+     * @return a list of groups where the specified group ID has been invited
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<Group> getSharedGroups(Object groupIdOrPath) throws GitLabApiException {
+        return (getSharedGroups(groupIdOrPath, getDefaultPerPage()).all());
+    }
+
+    /**
+     * Get a list of groups in the specified page range where the given group has been invited.
+     * When accessed without authentication, only public shared groups are returned.
+     *
+     * <pre><code>GitLab Endpoint: GET /groups/:id/groups/shared</code></pre>
+     *
+     * @param groupIdOrPath the group ID, path of the group, or a Group instance holding the group ID or path
+     * @param page the page to get
+     * @param perPage the number of Group instances per page
+     * @return a list of groups where the specified group ID has been invited in the specified page range
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<Group> getSharedGroups(Object groupIdOrPath, int page, int perPage) throws GitLabApiException {
+        Response response = get(
+                Response.Status.OK,
+                getPageQueryParams(page, perPage),
+                "groups",
+                getGroupIdOrPath(groupIdOrPath),
+                "groups",
+                "shared");
+        return (response.readEntity(new GenericType<List<Group>>() {}));
+    }
+
+    /**
+     * Get a list of groups where the given group has been invited.
+     * When accessed without authentication, only public shared groups are returned.
+     *
+     * <pre><code>GitLab Endpoint: GET /groups/:id/groups/shared</code></pre>
+     *
+     * @param groupIdOrPath the group ID, path of the group, or a Group instance holding the group ID or path
+     * @param itemsPerPage the number of Group instances that will be fetched per page
+     * @return a Pager of groups where the specified group ID has been invited
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Group> getSharedGroups(Object groupIdOrPath, int itemsPerPage) throws GitLabApiException {
+        return (new Pager<Group>(
+                this, Group.class, itemsPerPage, null, "groups", getGroupIdOrPath(groupIdOrPath), "groups", "shared"));
+    }
+
+    /**
+     * Get a Stream of groups where the given group has been invited.
+     * When accessed without authentication, only public shared groups are returned.
+     *
+     * <pre><code>GitLab Endpoint: GET /groups/:id/groups/shared</code></pre>
+     *
+     * @param groupIdOrPath the group ID, path of the group, or a Group instance holding the group ID or path
+     * @return a Stream of groups where the specified group ID has been invited
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Stream<Group> getSharedGroupsStream(Object groupIdOrPath) throws GitLabApiException {
+        return (getSharedGroups(groupIdOrPath, getDefaultPerPage()).stream());
+    }
+
     /**
      * Get all details of a group.
      *

gitlab4j-models/src/main/java/org/gitlab4j/api/models/SharedGroupsFilter.java

@@ -0,0 +1,122 @@
+package org.gitlab4j.api.models;
+
+import java.io.Serializable;
+import java.util.List;
+
+import org.gitlab4j.models.Constants.GroupOrderBy;
+import org.gitlab4j.models.Constants.SortOrder;
+import org.gitlab4j.models.GitLabForm;
+import org.gitlab4j.models.utils.JacksonJson;
+
+/**
+ *  This class is used to filter Groups when getting lists of groups for a specified group where it has been invited.
+ */
+public class SharedGroupsFilter implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    private List<Long> skipGroups;
+    private String search;
+    private GroupOrderBy orderBy;
+    private SortOrder sort;
+    private Visibility visibility;
+    private AccessLevel minAccessLevel;
+    private Boolean withCustomAttributes;
+
+    /**
+     * Do not include the provided groups IDs.
+     *
+     * @param skipGroups List of group IDs to not include in the search
+     * @return the reference to this SharedGroupsFilter instance
+     */
+    public SharedGroupsFilter withSkipGroups(List<Long> skipGroups) {
+        this.skipGroups = skipGroups;
+        return (this);
+    }
+
+    /**
+     * Return list of groups matching the search criteria.
+     *
+     * @param search the search criteria
+     * @return the reference to this SharedGroupsFilter instance
+     */
+    public SharedGroupsFilter withSearch(String search) {
+        this.search = search;
+        return (this);
+    }
+
+    /**
+     * Return groups ordered by name, path, id, or similarity. Default is name.
+     *
+     * @param orderBy specifies what field to order by
+     * @return the reference to this SharedGroupsFilter instance
+     */
+    public SharedGroupsFilter withOrderBy(GroupOrderBy orderBy) {
+        this.orderBy = orderBy;
+        return (this);
+    }
+
+    /**
+     * Return groups sorted in asc or desc order. Default is desc.
+     *
+     * @param sort sort direction, ASC or DESC
+     * @return the reference to this SharedGroupsFilter instance
+     */
+    public SharedGroupsFilter withSortOder(SortOrder sort) {
+        this.sort = sort;
+        return (this);
+    }
+
+    /**
+     * Limit by visibility public, internal, or private.
+     *
+     * @param visibility the visibility to match
+     * @return the reference to this SharedGroupsFilter instance
+     */
+    public SharedGroupsFilter withVisibility(Visibility visibility) {
+        this.visibility = visibility;
+        return (this);
+    }
+
+    /**
+     * Limit to groups where current user has at least the specified role (access_level).
+     *
+     * @param minAccessLevel the minimum access level to match
+     * @return the reference to this SharedGroupsFilter instance
+     */
+    public SharedGroupsFilter withMinAccessLevel(AccessLevel minAccessLevel) {
+        this.minAccessLevel = minAccessLevel;
+        return (this);
+    }
+
+    /**
+     *  Include custom attributes in response (admins only).
+     *
+     * @param withCustomAttributes if true, include custom attributes in the repsonse
+     * @return the reference to this SharedGroupsFilter instance
+     */
+    public SharedGroupsFilter withCustomAttributes(Boolean withCustomAttributes) {
+        this.withCustomAttributes = withCustomAttributes;
+        return (this);
+    }
+
+    /**
+     * Get the query params specified by this filter.
+     *
+     * @return a GitLabApiForm instance holding the query parameters for this SharedGroupsFilter instance
+     */
+    public GitLabForm getQueryParams() {
+        return (new GitLabForm()
+                .withParam("skip_groups", skipGroups)
+                .withParam("search", search)
+                .withParam("order_by", orderBy)
+                .withParam("sort", sort)
+                .withParam("visibility", visibility)
+                .withParam("simple", minAccessLevel)
+                .withParam("with_custom_attributes", withCustomAttributes));
+    }
+
+    @Override
+    public String toString() {
+        return (JacksonJson.toJsonString(this));
+    }
+}