Fixed getAllRunners() methods and added support to filter on runner type and status (#365).

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

 package org.gitlab4j.api;
 
+import java.util.List;
+import java.util.stream.Stream;
+
+import javax.ws.rs.core.GenericType;
+import javax.ws.rs.core.Response;
+
 import org.gitlab4j.api.models.Job;
 import org.gitlab4j.api.models.JobStatus;
 import org.gitlab4j.api.models.Runner;
+import org.gitlab4j.api.models.Runner.RunnerStatus;
+import org.gitlab4j.api.models.Runner.RunnerType;
 import org.gitlab4j.api.models.RunnerDetail;
 
-import javax.ws.rs.core.GenericType;
-import javax.ws.rs.core.Response;
-import java.util.List;
-import java.util.stream.Stream;
-
 /**
  * This class provides an entry point to all the GitLab API repository files calls.
  */
@@ -28,7 +31,34 @@ public class RunnersApi extends AbstractApi {
      * @throws GitLabApiException if any exception occurs
      */
     public List<Runner> getRunners() throws GitLabApiException {
-        return (getRunners(null, getDefaultPerPage()).all());
+        return (getRunners(null, null, getDefaultPerPage()).all());
+    }
+
+    /**
+     * Get a list of all available runners available to the user with pagination support.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners</code></pre>
+     *
+     * @param page    The page offset of runners
+     * @param perPage The number of runners to get after the page offset
+     * @return List of Runners
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<Runner> getRunners(int page, int perPage) throws GitLabApiException {
+        return getRunners(null, null, page, perPage);
+    }
+
+    /**
+     * Get a list of all available runners available to the user.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners</code></pre>
+     *
+     * @param itemsPerPage the number of Runner instances that will be fetched per page
+     * @return a Pager containing the Runners for the user
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Runner> getRunners(int itemsPerPage) throws GitLabApiException {
+        return (getRunners(null, null, itemsPerPage));
     }
 
     /**
@@ -40,7 +70,7 @@ public class RunnersApi extends AbstractApi {
      * @throws GitLabApiException if any exception occurs
      */
     public Stream<Runner> getRunnersStream() throws GitLabApiException {
-        return (getRunners(null, getDefaultPerPage()).stream());
+        return (getRunners(null, null, getDefaultPerPage()).stream());
     }
 
     /**
@@ -48,12 +78,51 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners</code></pre>
      *
-     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
      * @return List of Runners
      * @throws GitLabApiException if any exception occurs
      */
-    public List<Runner> getRunners(Runner.RunnerStatus scope) throws GitLabApiException {
-        return (getRunners(scope, getDefaultPerPage()).all());
+    public List<Runner> getRunners(RunnerType type, RunnerStatus status) throws GitLabApiException {
+        return (getRunners(type, status, getDefaultPerPage()).all());
+    }
+
+    /**
+     * Get a list of specific runners available to the user.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners</code></pre>
+     *
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
+     * @param page the page offset of runners
+     * @param perPage the number of runners to get after the page offset
+     * @return List of Runners
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<Runner> getRunners(RunnerType type, RunnerStatus status, int page, int perPage) throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm(page, perPage)
+                .withParam("type", type, false)
+                .withParam("status", status, false);
+        Response response = get(Response.Status.OK, formData.asMap(), "runners");
+        return (response.readEntity(new GenericType<List<Runner>>() {}));
+    }
+
+    /**
+     * Get a list of specific runners available to the user.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners</code></pre>
+     *
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
+     * @param itemsPerPage The number of Runner instances that will be fetched per page
+     * @return a Pager containing the Runners for the user
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Runner> getRunners(RunnerType type, RunnerStatus status, int itemsPerPage) throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm()
+                .withParam("type", type, false)
+                .withParam("status", status, false);
+        return (new Pager<>(this, Runner.class, itemsPerPage, formData.asMap(), "runners"));
     }
 
     /**
@@ -61,12 +130,13 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners</code></pre>
      *
-     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
      * @return Stream of Runners
      * @throws GitLabApiException if any exception occurs
      */
-    public Stream<Runner> getRunnersStream(Runner.RunnerStatus scope) throws GitLabApiException {
-        return (getRunners(scope, getDefaultPerPage()).stream());
+    public Stream<Runner> getRunnersStream(RunnerType type, RunnerStatus status) throws GitLabApiException {
+        return (getRunners(type, status, getDefaultPerPage()).stream());
     }
 
     /**
@@ -74,13 +144,14 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners</code></pre>
      *
-     * @param page    The page offset of runners
-     * @param perPage The number of runners to get after the page offset
+     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
      * @return List of Runners
      * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getRunners(Runner.RunnerType, Runner.RunnerStatus)}
      */
-    public List<Runner> getRunners(int page, int perPage) throws GitLabApiException {
-        return getRunners(null, page, perPage);
+    @Deprecated
+    public List<Runner> getRunners(RunnerStatus scope) throws GitLabApiException {
+        return (getRunners(scope, getDefaultPerPage()).all());
     }
 
     /**
@@ -93,8 +164,10 @@ public class RunnersApi extends AbstractApi {
      * @param perPage The number of runners to get after the page offset
      * @return List of Runners
      * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getRunners(Runner.RunnerType, Runner.RunnerStatus, int, int)}
      */
-    public List<Runner> getRunners(Runner.RunnerStatus scope, Integer page, Integer perPage) throws GitLabApiException {
+    @Deprecated
+    public List<Runner> getRunners(RunnerStatus scope, int page, int perPage) throws GitLabApiException {
         GitLabApiForm formData = new GitLabApiForm()
                 .withParam("scope", scope, false)
                 .withParam("page", page, false)
@@ -105,31 +178,35 @@ public class RunnersApi extends AbstractApi {
     }
 
     /**
-     * Get a list of all available runners available to the user.
+     * Get a list of specific runners available to the user.
      *
      * <pre><code>GitLab Endpoint: GET /runners</code></pre>
      *
-     * @param itemsPerPage the number of Runner instances that will be fetched per page
+     * @param scope the scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @param itemsPerPage The number of Runner instances that will be fetched per page
      * @return a Pager containing the Runners for the user
      * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getRunners(Runner.RunnerType, Runner.RunnerStatus, int)}
      */
-    public Pager<Runner> getRunners(int itemsPerPage) throws GitLabApiException {
-        return (getRunners(null, itemsPerPage));
+    @Deprecated
+    public Pager<Runner> getRunners(RunnerStatus scope, int itemsPerPage) throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm().withParam("scope", scope, false);
+        return (new Pager<>(this, Runner.class, itemsPerPage, formData.asMap(), "runners"));
     }
 
     /**
-     * Get a list of specific runners available to the user.
+     * Get a Stream of all available runners available to the user with pagination support.
      *
      * <pre><code>GitLab Endpoint: GET /runners</code></pre>
      *
-     * @param scope the scope of specific runners to show, one of: active, paused, online; showing all runners null
-     * @param itemsPerPage The number of Runner instances that will be fetched per page
-     * @return a Pager containing the Runners for the user
+     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @return Stream of Runners
      * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getRunnersStream(Runner.RunnerType, Runner.RunnerStatus)}
      */
-    public Pager<Runner> getRunners(Runner.RunnerStatus scope, int itemsPerPage) throws GitLabApiException {
-        GitLabApiForm formData = new GitLabApiForm().withParam("scope", scope, false);
-        return (new Pager<>(this, Runner.class, itemsPerPage, formData.asMap(), "runners"));
+    @Deprecated
+    public Stream<Runner> getRunnersStream(RunnerStatus scope) throws GitLabApiException {
+        return (getRunners(scope, getDefaultPerPage()).stream());
     }
 
     /**
@@ -141,19 +218,21 @@ public class RunnersApi extends AbstractApi {
      * @throws GitLabApiException if any exception occurs
      */
     public List<Runner> getAllRunners() throws GitLabApiException {
-        return (getAllRunners(null, getDefaultPerPage()).all());
+        return (getAllRunners(null, null, getDefaultPerPage()).all());
     }
 
     /**
-     * Get a Stream of all runners in the GitLab instance (specific and shared). Access is restricted to users with admin privileges.
+     * Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with admin privileges.
      *
      * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
      *
-     * @return a Stream of Runners
+     * @param page    The page offset of runners
+     * @param perPage The number of runners to get after the page offset
+     * @return a list of all runners in the GitLab instance
      * @throws GitLabApiException if any exception occurs
      */
-    public Stream<Runner> getAllRunnersStream() throws GitLabApiException {
-        return (getAllRunners(null, getDefaultPerPage()).stream());
+    public List<Runner> getAllRunners(int page, int perPage) throws GitLabApiException {
+        return (getAllRunners(null, page, perPage));
     }
 
     /**
@@ -161,12 +240,12 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
      *
-     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
-     * @return a List of Runners
+     * @param itemsPerPage The number of Runner instances that will be fetched per page
+     * @return List of Runners
      * @throws GitLabApiException if any exception occurs
      */
-    public List<Runner> getAllRunners(Runner.RunnerStatus scope) throws GitLabApiException {
-        return (getAllRunners(scope, getDefaultPerPage()).all());
+    public Pager<Runner> getAllRunners(int itemsPerPage) throws GitLabApiException {
+        return getAllRunners(null, null, itemsPerPage);
     }
 
     /**
@@ -174,12 +253,11 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
      *
-     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
      * @return a Stream of Runners
      * @throws GitLabApiException if any exception occurs
      */
-    public Stream<Runner> getAllRunnersStream(Runner.RunnerStatus scope) throws GitLabApiException {
-        return (getAllRunners(scope, getDefaultPerPage()).stream());
+    public Stream<Runner> getAllRunnersStream() throws GitLabApiException {
+        return (getAllRunners(null, null, getDefaultPerPage()).stream());
     }
 
     /**
@@ -187,13 +265,13 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
      *
-     * @param page    The page offset of runners
-     * @param perPage The number of runners to get after the page offset
-     * @return a list of all runners in the GitLab instance
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
+     * @return a List of Runners
      * @throws GitLabApiException if any exception occurs
      */
-    public List<Runner> getAllRunners(int page, int perPage) throws GitLabApiException {
-        return (getAllRunners(null, page, perPage));
+    public List<Runner> getAllRunners(RunnerType type, RunnerStatus status) throws GitLabApiException {
+        return (getAllRunners(type, status, getDefaultPerPage()).all());
     }
 
     /**
@@ -201,17 +279,17 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
      *
-     * @param scope   The scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
      * @param page    The page offset of runners
      * @param perPage The number of runners to get after the page offset
      * @return List of Runners
      * @throws GitLabApiException if any exception occurs
      */
-    public List<Runner> getAllRunners(Runner.RunnerStatus scope, Integer page, Integer perPage) throws GitLabApiException {
-        GitLabApiForm formData = new GitLabApiForm()
-                .withParam("scope", scope, false)
-                .withParam("page", page, false)
-                .withParam("per_page", perPage, false);
+    public List<Runner> getAllRunners(RunnerType type, RunnerStatus status, int page, int perPage) throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm(page, perPage)
+                .withParam("type", type, false)
+                .withParam("status", status, false);
         Response response = get(Response.Status.OK, formData.asMap(), "runners", "all");
         return (response.readEntity(new GenericType<List<Runner>>() {}));
     }
@@ -221,12 +299,65 @@ public class RunnersApi extends AbstractApi {
      *
      * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
      *
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
      * @param itemsPerPage The number of Runner instances that will be fetched per page
+     * @return a Pager containing the Runners
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Runner> getAllRunners(RunnerType type, RunnerStatus status, int itemsPerPage) throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm()
+                .withParam("type", type, false)
+                .withParam("status", status, false);
+        return (new Pager<>(this, Runner.class, itemsPerPage, formData.asMap(), "runners", "all"));
+    }
+
+    /**
+     * Get a Stream of all runners in the GitLab instance (specific and shared). Access is restricted to users with admin privileges.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
+     *
+     * @param type the type of runners to show, one of: instance_type, group_type, project_type, or null
+     * @param status the status of runners to show, one of: active, paused, online, offline, or null
+     * @return a Stream of Runners
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Stream<Runner> getAllRunnersStream(RunnerType type, RunnerStatus status) throws GitLabApiException {
+        return (getAllRunners(type, status, getDefaultPerPage()).stream());
+    }
+
+    /**
+     * Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with admin privileges.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
+     *
+     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @return a List of Runners
+     * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getAllRunners(Runner.RunnerType, Runner.RunnerStatus)}
+     */
+    @Deprecated
+    public List<Runner> getAllRunners(RunnerStatus scope) throws GitLabApiException {
+        return (getAllRunners(scope, getDefaultPerPage()).all());
+    }
+
+    /**
+     * Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with admin privileges.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
+     *
+     * @param scope   The scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @param page    The page offset of runners
+     * @param perPage The number of runners to get after the page offset
      * @return List of Runners
      * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getAllRunners(Runner.RunnerType, Runner.RunnerStatus, int, int)}
      */
-    public Pager<Runner> getAllRunners(int itemsPerPage) throws GitLabApiException {
-        return getAllRunners(null, itemsPerPage);
+    @Deprecated
+    public List<Runner> getAllRunners(RunnerStatus scope, int page, int perPage) throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm(page, perPage).withParam("scope", scope, false);
+        Response response = get(Response.Status.OK, formData.asMap(), "runners", "all");
+        return (response.readEntity(new GenericType<List<Runner>>() {}));
     }
 
     /**
@@ -238,10 +369,27 @@ public class RunnersApi extends AbstractApi {
      * @param itemsPerPage The number of Runner instances that will be fetched per page
      * @return a Pager containing the Runners
      * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getAllRunners(Runner.RunnerType, Runner.RunnerStatus, int)}
      */
-    public Pager<Runner> getAllRunners(Runner.RunnerStatus scope, int itemsPerPage) throws GitLabApiException {
+    @Deprecated
+    public Pager<Runner> getAllRunners(RunnerStatus scope, int itemsPerPage) throws GitLabApiException {
         GitLabApiForm formData = new GitLabApiForm().withParam("scope", scope, false);
-        return (new Pager<>(this, Runner.class, itemsPerPage, formData.asMap(), "runners"));
+        return (new Pager<>(this, Runner.class, itemsPerPage, formData.asMap(), "runners", "all"));
+    }
+
+    /**
+     * Get a Stream of all runners in the GitLab instance (specific and shared). Access is restricted to users with admin privileges.
+     *
+     * <pre><code>GitLab Endpoint: GET /runners/all</code></pre>
+     *
+     * @param scope The scope of specific runners to show, one of: active, paused, online; showing all runners null
+     * @return a Stream of Runners
+     * @throws GitLabApiException if any exception occurs
+     * @deprecated As of release 4.11.5, replaced by {@link #getAllRunnersStream(Runner.RunnerType, Runner.RunnerStatus)}
+     */
+    @Deprecated
+    public Stream<Runner> getAllRunnersStream(RunnerStatus scope) throws GitLabApiException {
+        return (getAllRunners(scope, getDefaultPerPage()).stream());
     }
 
     /**

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

@@ -18,7 +18,7 @@ public class Runner {
     private String ipAddress;
 
     /**
-     * Enum to use for RunnersApi filtering.
+     * Enum to use for RunnersApi filtering on status.
      */
     public enum RunnerStatus {
         SPECIFIC, SHARED, ACTIVE, ONLINE, PAUSED, OFFLINE;
@@ -41,6 +41,29 @@ public class Runner {
         }
     }
 
+    /**
+     * Enum to use for RunnersApi filtering on type.
+     */
+    public enum RunnerType {
+        INSTANCE_TYPE, GROUP_TYPE, PROJECT_TYPE;
+        private static JacksonJsonEnumHelper<RunnerType> enumHelper =
+                new JacksonJsonEnumHelper<>(RunnerType.class);
+
+        @JsonCreator
+        public static RunnerType forValue(String value) {
+            return enumHelper.forValue(value);
+        }
+
+        @JsonValue
+        public String toValue() {
+            return (enumHelper.toString(this));
+        }
+
+        @Override
+        public String toString() {
+            return (enumHelper.toString(this));
+        }
+    }
 
     public Integer getId() {
         return id;

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

@@ -25,6 +25,7 @@ package org.gitlab4j.api;
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
 import static org.junit.Assume.assumeTrue;
 
 import java.util.Arrays;
@@ -32,6 +33,8 @@ import java.util.List;
 
 import org.gitlab4j.api.models.Project;
 import org.gitlab4j.api.models.Runner;
+import org.gitlab4j.api.models.Runner.RunnerStatus;
+import org.gitlab4j.api.models.Runner.RunnerType;
 import org.gitlab4j.api.models.RunnerDetail;
 import org.junit.Before;
 import org.junit.BeforeClass;
@@ -111,7 +114,9 @@ public class TestRunnersApi extends AbstractIntegrationTest {
     @Test
     public void shouldHaveRunnerDetails() throws GitLabApiException {
 
-        assertNotNull("Runner was not created", createRunner());
+        // Arrange
+        Runner runner = createRunner();
+        assertNotNull("Failed to create test runner.", runner);
 
         List<Runner> runners = gitLabApi.getRunnersApi().getAllRunners();
         assertEquals(1, runners.size());
@@ -121,19 +126,30 @@ public class TestRunnersApi extends AbstractIntegrationTest {
     @Test
     public void shouldDeleteRunner() throws GitLabApiException {
 
-        assertNotNull("Runner was not created", createRunner());
-        assertNotNull("Runner was not created", createRunner());
-        assertNotNull("Runner was not created", createRunner());
+        for (int i = 0; i < 3; i++) {
+            Runner runner = createRunner();
+            assertNotNull("Failed to create test runner.", runner);
+        }
 
         List<Runner> allRunners = gitLabApi.getRunnersApi().getAllRunners();
         assertEquals(3, allRunners.size());
 
-        for (Runner runner : allRunners) {
-            RunnerDetail runnerDetail = gitLabApi.getRunnersApi().getRunnerDetail(runner.getId());
+        for (Runner r : allRunners) {
+            RunnerDetail runnerDetail = gitLabApi.getRunnersApi().getRunnerDetail(r.getId());
             gitLabApi.getRunnersApi().deleteRunner(runnerDetail.getToken());
         }
 
         allRunners = gitLabApi.getRunnersApi().getAllRunners();
         assertEquals(0, allRunners.size());
     }
+
+    @Test
+    public void shouldHavePausedRunner() throws GitLabApiException {
+
+        Runner runner = createRunner();
+        assertNotNull("Failed to create test runner.", runner);
+
+        List<Runner> runners = gitLabApi.getRunnersApi().getAllRunners(RunnerType.GROUP_TYPE, RunnerStatus.PAUSED);
+        assertTrue(runners.isEmpty());
+    }
 }