feat: add support for application list pagination

Application list results are now paginated.
Add properties and helper classes for accessing application list pages.

Signed-off-by: Subin Shekhar <[email protected]>

Author: subinpc

.gitignore

@@ -83,3 +83,4 @@ secrets.tar
 
 # SDK generator
 .openapi-generator*
+.npmrc

examples/ibm-analytics-engine-api.v3.test.js

@@ -18,6 +18,7 @@
  */
 
 /* eslint-disable no-console */
+/* eslint-disable no-await-in-loop */
 
 const IbmAnalyticsEngineApiV3 = require('../dist/ibm-analytics-engine-api/v3');
 // eslint-disable-next-line node/no-unpublished-require
@@ -389,12 +390,20 @@ describe('IbmAnalyticsEngineApiV3', () => {
     const params = {
       instanceId: 'e64c907a-e82f-46fd-addc-ccfafbd28b09',
       state: ['accepted', 'running', 'finished', 'failed'],
+      limit: 10,
     };
 
-    let res;
+    const allResults = [];
     try {
-      res = await ibmAnalyticsEngineApiService.listApplications(params);
-      console.log(JSON.stringify(res.result, null, 2));
+      const pager = new IbmAnalyticsEngineApiV3.ApplicationsPager(
+        ibmAnalyticsEngineApiService,
+        params
+      );
+      while (pager.hasNext()) {
+        const nextPage = await pager.getNext();
+        allResults.push(...nextPage);
+      }
+      console.log(JSON.stringify(allResults, null, 2));
     } catch (err) {
       console.warn(err);
     }

ibm-analytics-engine-api/v3.ts

@@ -18,6 +18,9 @@
  * IBM OpenAPI SDK Code Generator Version: 3.66.0-d6c2d7e0-20230215-221247
  */
 
+/* eslint-disable max-classes-per-file */
+/* eslint-disable no-await-in-loop */
+
 import * as extend from 'extend';
 import { IncomingHttpHeaders, OutgoingHttpHeaders } from 'http';
 import {
@@ -713,6 +716,8 @@ class IbmAnalyticsEngineApiV3 extends BaseService {
    * @param {string} params.instanceId - The identifier of the Analytics Engine instance associated with the Spark
    * application(s).
    * @param {string[]} [params.state] - List of Spark application states that will be used to filter the response.
+   * @param {number} [params.limit] - Number of application entries to be included in the response.
+   * @param {string} [params.start] - Token used to fetch the next or the previous page of the applications list.
    * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
    * @returns {Promise<IbmAnalyticsEngineApiV3.Response<IbmAnalyticsEngineApiV3.ApplicationCollection>>}
    */
@@ -721,14 +726,16 @@ class IbmAnalyticsEngineApiV3 extends BaseService {
   ): Promise<IbmAnalyticsEngineApiV3.Response<IbmAnalyticsEngineApiV3.ApplicationCollection>> {
     const _params = { ...params };
     const _requiredParams = ['instanceId'];
-    const _validParams = ['instanceId', 'state', 'headers'];
+    const _validParams = ['instanceId', 'state', 'limit', 'start', 'headers'];
     const _validationErrors = validateParams(_params, _requiredParams, _validParams);
     if (_validationErrors) {
       return Promise.reject(_validationErrors);
     }
 
     const query = {
       'state': _params.state,
+      'limit': _params.limit,
+      'start': _params.start,
     };
 
     const path = {
@@ -1560,6 +1567,10 @@ namespace IbmAnalyticsEngineApiV3 {
     instanceId: string;
     /** List of Spark application states that will be used to filter the response. */
     state?: ListApplicationsConstants.State[] | string[];
+    /** Number of application entries to be included in the response. */
+    limit?: number;
+    /** Token used to fetch the next or the previous page of the applications list. */
+    start?: string;
     headers?: OutgoingHttpHeaders;
   }
 
@@ -1709,10 +1720,18 @@ namespace IbmAnalyticsEngineApiV3 {
     auto_termination_time?: string;
   }
 
-  /** An array of application details. */
+  /** A paginated collection of applications. */
   export interface ApplicationCollection {
     /** List of applications. */
-    applications?: Application[];
+    applications: Application[];
+    /** A reference to a page in a paginated collection. */
+    first?: PageLink;
+    /** A reference to a page in a paginated collection. */
+    next?: PageLink;
+    /** A reference to a page in a paginated collection. */
+    previous?: PageLink;
+    /** The maximum number of results in this page of the collection. */
+    limit: number;
   }
 
   /** Application details. */
@@ -1963,6 +1982,14 @@ namespace IbmAnalyticsEngineApiV3 {
     type?: string;
   }
 
+  /** A reference to a page in a paginated collection. */
+  export interface PageLink {
+    /** A url which returns a specific page of a collection. */
+    href: string;
+    /** A token which loads a specific page of a collection when it is provided the url of the collection. */
+    start?: string;
+  }
+
   /** Resource consumption limits for the instance. */
   export interface ResourceConsumptionLimitsResponse {
     /** Maximum number of virtual processor cores that be used in the instance. */
@@ -1992,6 +2019,92 @@ namespace IbmAnalyticsEngineApiV3 {
     /** Time when the Spark history server will be stopped automatically. */
     auto_termination_time?: string;
   }
+
+  /*************************
+   * pager classes
+   ************************/
+
+  /**
+   * ApplicationsPager can be used to simplify the use of listApplications().
+   */
+  export class ApplicationsPager {
+    protected _hasNext: boolean;
+
+    protected pageContext: any;
+
+    protected client: IbmAnalyticsEngineApiV3;
+
+    protected params: IbmAnalyticsEngineApiV3.ListApplicationsParams;
+
+    /**
+     * Construct a ApplicationsPager object.
+     *
+     * @param {IbmAnalyticsEngineApiV3}  client - The service client instance used to invoke listApplications()
+     * @param {Object} params - The parameters to be passed to listApplications()
+     * @constructor
+     * @returns {ApplicationsPager}
+     */
+    constructor(
+      client: IbmAnalyticsEngineApiV3,
+      params: IbmAnalyticsEngineApiV3.ListApplicationsParams
+    ) {
+      if (params && params.start) {
+        throw new Error(`the params.start field should not be set`);
+      }
+
+      this._hasNext = true;
+      this.pageContext = { next: undefined };
+      this.client = client;
+      this.params = JSON.parse(JSON.stringify(params || {}));
+    }
+
+    /**
+     * Returns true if there are potentially more results to be retrieved by invoking getNext().
+     * @returns {boolean}
+     */
+    public hasNext(): boolean {
+      return this._hasNext;
+    }
+
+    /**
+     * Returns the next page of results by invoking listApplications().
+     * @returns {Promise<IbmAnalyticsEngineApiV3.Application[]>}
+     */
+    public async getNext(): Promise<IbmAnalyticsEngineApiV3.Application[]> {
+      if (!this.hasNext()) {
+        throw new Error('No more results available');
+      }
+
+      if (this.pageContext.next) {
+        this.params.start = this.pageContext.next;
+      }
+      const response = await this.client.listApplications(this.params);
+      const { result } = response;
+
+      let next = null;
+      if (result && result.next) {
+        next = result.next.start;
+      }
+      this.pageContext.next = next;
+      if (!this.pageContext.next) {
+        this._hasNext = false;
+      }
+      return result.applications;
+    }
+
+    /**
+     * Returns all results by invoking listApplications() repeatedly until all pages of results have been retrieved.
+     * @returns {Promise<IbmAnalyticsEngineApiV3.Application[]>}
+     */
+    public async getAll(): Promise<IbmAnalyticsEngineApiV3.Application[]> {
+      const results: Application[] = [];
+      while (this.hasNext()) {
+        const nextPage = await this.getNext();
+        results.push(...nextPage);
+      }
+      return results;
+    }
+  }
 }
 
 export = IbmAnalyticsEngineApiV3;

package-lock.json

@@ -15,6 +15,7 @@
  */
 
 /* eslint-disable no-console */
+/* eslint-disable no-await-in-loop */
 
 const { readExternalSources } = require('ibm-cloud-sdk-core');
 const IbmAnalyticsEngineApiV3 = require('../../dist/ibm-analytics-engine-api/v3');
@@ -217,14 +218,38 @@ describe('IbmAnalyticsEngineApiV3_integration', () => {
     const params = {
       instanceId: instanceGuid,
       state: ['accepted', 'running', 'finished', 'failed'],
+      limit: 10,
     };
 
     const res = await ibmAnalyticsEngineApiService.listApplications(params);
     expect(res).toBeDefined();
     expect(res.status).toBe(200);
     expect(res.result).toBeDefined();
   });
+  test('listApplications() via ApplicationsPager', async () => {
+    const params = {
+      instanceId: instanceGuid,
+      state: ['accepted', 'running', 'finished', 'failed'],
+      limit: 1,
+    };
 
+    const allResults = [];
+
+    // Test getNext().
+    let pager = new IbmAnalyticsEngineApiV3.ApplicationsPager(ibmAnalyticsEngineApiService, params);
+    while (pager.hasNext()) {
+      const nextPage = await pager.getNext();
+      expect(nextPage).not.toBeNull();
+      allResults.push(...nextPage);
+    }
+
+    // Test getAll().
+    pager = new IbmAnalyticsEngineApiV3.ApplicationsPager(ibmAnalyticsEngineApiService, params);
+    const allItems = await pager.getAll();
+    expect(allItems).not.toBeNull();
+    expect(allItems).toHaveLength(allResults.length);
+    console.log(`Retrieved a total of ${allResults.length} items(s) with pagination.`);
+  });
   test('getApplication()', async () => {
     const params = {
       instanceId: instanceGuid,