Api-Roll 53: 2017-08-21

generated/googleapis/lib/clouddebugger/v2.dart

 // This is a generated file (see the discoveryapis_generator project).
 
 library googleapis.clouddebugger.v2;
 
 import 'dart:core' as core;
 import 'dart:async' as async;
 import 'dart:convert' as convert;
 
 import 'package:_discoveryapis_commons/_discoveryapis_commons.dart' as commons;
 import 'package:http/http.dart' as http;
@@ skipping 39 matching lines @@
   final commons.ApiRequester _requester;
 
   ControllerDebuggeesBreakpointsResourceApi get breakpoints => new ControllerDebuggeesBreakpointsResourceApi(_requester);
 
   ControllerDebuggeesResourceApi(commons.ApiRequester client) : 
       _requester = client;
 
   /**
    * Registers the debuggee with the controller service.
    *
-   * All agents attached to the same application should call this method with
-   * the same request content to get back the same stable `debuggee_id`. Agents
-   * should call this method again whenever `google.rpc.Code.NOT_FOUND` is
-   * returned from any controller method.
+   * All agents attached to the same application must call this method with
+   * exactly the same request content to get back the same stable `debuggee_id`.
+   * Agents should call this method again whenever `google.rpc.Code.NOT_FOUND`
+   * is returned from any controller method.
    *
-   * This allows the controller service to disable the agent or recover from any
-   * data loss. If the debuggee is disabled by the server, the response will
-   * have `is_disabled` set to `true`.
+   * This protocol allows the controller service to disable debuggees, recover
+   * from data loss, or change the `debuggee_id` format. Agents must handle
+   * `debuggee_id` value changing upon re-registration.
    *
    * [request] - The metadata request object.
    *
    * Request parameters:
    *
    * Completes with a [RegisterDebuggeeResponse].
    *
    * Completes with a [commons.ApiRequestError] if the API endpoint returned an
    * error.
    *
@@ skipping 45 matching lines @@
    * This means that an agent does not need to check if a breakpoint has changed
    * when it encounters the same breakpoint on a successive call.
    * Moreover, an agent should remember the breakpoints that are completed
    * until the controller removes them from the active list to avoid
    * setting those breakpoints again.
    *
    * Request parameters:
    *
    * [debuggeeId] - Identifies the debuggee.
    *
-   * [successOnTimeout] - If set to `true`, returns `google.rpc.Code.OK` status
-   * and sets the
-   * `wait_expired` response field to `true` when the server-selected timeout
-   * has expired (recommended).
+   * [successOnTimeout] - If set to `true` (recommended), returns
+   * `google.rpc.Code.OK` status and
+   * sets the `wait_expired` response field to `true` when the server-selected
+   * timeout has expired.
    *
-   * If set to `false`, returns `google.rpc.Code.ABORTED` status when the
-   * server-selected timeout has expired (deprecated).
+   * If set to `false` (deprecated), returns `google.rpc.Code.ABORTED` status
+   * when the server-selected timeout has expired.
    *
-   * [waitToken] - A wait token that, if specified, blocks the method call until
-   * the list
-   * of active breakpoints has changed, or a server selected timeout has
-   * expired.  The value should be set from the last returned response.
+   * [waitToken] - A token that, if specified, blocks the method call until the
+   * list
+   * of active breakpoints has changed, or a server-selected timeout has
+   * expired. The value should be set from the `next_wait_token` field in
+   * the last response. The initial value should be set to `"init"`.
    *
    * Completes with a [ListActiveBreakpointsResponse].
    *
    * Completes with a [commons.ApiRequestError] if the API endpoint returned an
    * error.
    *
    * If the used [http.Client] completes with an error when making a REST call,
    * this method will complete with the same error.
    */
   async.Future<ListActiveBreakpointsResponse> list(core.String debuggeeId, {core.bool successOnTimeout, core.String waitToken}) {
@@ skipping 21 matching lines @@
                                        body: _body,
                                        queryParams: _queryParams,
                                        uploadOptions: _uploadOptions,
                                        uploadMedia: _uploadMedia,
                                        downloadOptions: _downloadOptions);
     return _response.then((data) => new ListActiveBreakpointsResponse.fromJson(data));
   }
 
   /**
    * Updates the breakpoint state or mutable fields.
-   * The entire Breakpoint message must be sent back to the controller
-   * service.
+   * The entire Breakpoint message must be sent back to the controller service.
    *
    * Updates to active breakpoint fields are only allowed if the new value
    * does not change the breakpoint specification. Updates to the `location`,
    * `condition` and `expressions` fields should not alter the breakpoint
    * semantics. These may only make changes such as canonicalizing a value
    * or snapping the location to the correct line of code.
    *
    * [request] - The metadata request object.
    *
    * Request parameters:
@@ skipping 55 matching lines @@
 
 class DebuggerDebuggeesResourceApi {
   final commons.ApiRequester _requester;
 
   DebuggerDebuggeesBreakpointsResourceApi get breakpoints => new DebuggerDebuggeesBreakpointsResourceApi(_requester);
 
   DebuggerDebuggeesResourceApi(commons.ApiRequester client) : 
       _requester = client;
 
   /**
-   * Lists all the debuggees that the user can set breakpoints to.
+   * Lists all the debuggees that the user has access to.
    *
    * Request parameters:
    *
+   * [clientVersion] - The client version making the call.
+   * Schema: `domain/type/version` (e.g., `google.com/intellij/v1`).
+   *
    * [includeInactive] - When set to `true`, the result includes all debuggees.
    * Otherwise, the
    * result includes only debuggees that are active.
    *
    * [project] - Project number of a Google Cloud project whose debuggees to
    * list.
    *
-   * [clientVersion] - The client version making the call.
-   * Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
-   *
    * Completes with a [ListDebuggeesResponse].
    *
    * Completes with a [commons.ApiRequestError] if the API endpoint returned an
    * error.
    *
    * If the used [http.Client] completes with an error when making a REST call,
    * this method will complete with the same error.
    */
-  async.Future<ListDebuggeesResponse> list({core.bool includeInactive, core.String project, core.String clientVersion}) {
+  async.Future<ListDebuggeesResponse> list({core.String clientVersion, core.bool includeInactive, core.String project}) {
     var _url = null;
     var _queryParams = new core.Map();
     var _uploadMedia = null;
     var _uploadOptions = null;
     var _downloadOptions = commons.DownloadOptions.Metadata;
     var _body = null;
 
+    if (clientVersion != null) {
+      _queryParams["clientVersion"] = [clientVersion];
+    }
     if (includeInactive != null) {
       _queryParams["includeInactive"] = ["${includeInactive}"];
     }
     if (project != null) {
       _queryParams["project"] = [project];
     }
-    if (clientVersion != null) {
-      _queryParams["clientVersion"] = [clientVersion];
-    }
 
     _url = 'v2/debugger/debuggees';
 
     var _response = _requester.request(_url,
                                        "GET",
                                        body: _body,
                                        queryParams: _queryParams,
                                        uploadOptions: _uploadOptions,
                                        uploadMedia: _uploadMedia,
                                        downloadOptions: _downloadOptions);
@@ skipping 12 matching lines @@
   /**
    * Deletes the breakpoint from the debuggee.
    *
    * Request parameters:
    *
    * [debuggeeId] - ID of the debuggee whose breakpoint to delete.
    *
    * [breakpointId] - ID of the breakpoint to delete.
    *
    * [clientVersion] - The client version making the call.
-   * Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
+   * Schema: `domain/type/version` (e.g., `google.com/intellij/v1`).
    *
    * Completes with a [Empty].
    *
    * Completes with a [commons.ApiRequestError] if the API endpoint returned an
    * error.
    *
    * If the used [http.Client] completes with an error when making a REST call,
    * this method will complete with the same error.
    */
   async.Future<Empty> delete(core.String debuggeeId, core.String breakpointId, {core.String clientVersion}) {
@@ skipping 29 matching lines @@
   /**
    * Gets breakpoint information.
    *
    * Request parameters:
    *
    * [debuggeeId] - ID of the debuggee whose breakpoint to get.
    *
    * [breakpointId] - ID of the breakpoint to get.
    *
    * [clientVersion] - The client version making the call.
-   * Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
+   * Schema: `domain/type/version` (e.g., `google.com/intellij/v1`).
    *
    * Completes with a [GetBreakpointResponse].
    *
    * Completes with a [commons.ApiRequestError] if the API endpoint returned an
    * error.
    *
    * If the used [http.Client] completes with an error when making a REST call,
    * this method will complete with the same error.
    */
   async.Future<GetBreakpointResponse> get(core.String debuggeeId, core.String breakpointId, {core.String clientVersion}) {
@@ skipping 26 matching lines @@
     return _response.then((data) => new GetBreakpointResponse.fromJson(data));
   }
 
   /**
    * Lists all breakpoints for the debuggee.
    *
    * Request parameters:
    *
    * [debuggeeId] - ID of the debuggee whose breakpoints to list.
    *
+   * [stripResults] - This field is deprecated. The following fields are always
+   * stripped out of
+   * the result: `stack_frames`, `evaluated_expressions` and `variable_table`.
+   *
    * [waitToken] - A wait token that, if specified, blocks the call until the
    * breakpoints
    * list has changed, or a server selected timeout has expired.  The value
    * should be set from the last response. The error code
    * `google.rpc.Code.ABORTED` (RPC) is returned on wait timeout, which
    * should be called again with the same `wait_token`.
    *
    * [clientVersion] - The client version making the call.
-   * Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
+   * Schema: `domain/type/version` (e.g., `google.com/intellij/v1`).
    *
    * [action_value] - Only breakpoints with the specified action will pass the
    * filter.
    * Possible string values are:
    * - "CAPTURE" : A CAPTURE.
    * - "LOG" : A LOG.
    *
    * [includeInactive] - When set to `true`, the response includes active and
    * inactive
    * breakpoints. Otherwise, it includes only active breakpoints.
    *
    * [includeAllUsers] - When set to `true`, the response includes the list of
    * breakpoints set by
    * any user. Otherwise, it includes only breakpoints set by the caller.
    *
-   * [stripResults] - This field is deprecated. The following fields are always
-   * stripped out of
-   * the result: `stack_frames`, `evaluated_expressions` and `variable_table`.
-   *
    * Completes with a [ListBreakpointsResponse].
    *
    * Completes with a [commons.ApiRequestError] if the API endpoint returned an
    * error.
    *
    * If the used [http.Client] completes with an error when making a REST call,
    * this method will complete with the same error.
    */
-  async.Future<ListBreakpointsResponse> list(core.String debuggeeId, {core.String waitToken, core.String clientVersion, core.String action_value, core.bool includeInactive, core.bool includeAllUsers, core.bool stripResults}) {
+  async.Future<ListBreakpointsResponse> list(core.String debuggeeId, {core.bool stripResults, core.String waitToken, core.String clientVersion, core.String action_value, core.bool includeInactive, core.bool includeAllUsers}) {
     var _url = null;
     var _queryParams = new core.Map();
     var _uploadMedia = null;
     var _uploadOptions = null;
     var _downloadOptions = commons.DownloadOptions.Metadata;
     var _body = null;
 
     if (debuggeeId == null) {
       throw new core.ArgumentError("Parameter debuggeeId is required.");
     }
+    if (stripResults != null) {
+      _queryParams["stripResults"] = ["${stripResults}"];
+    }
     if (waitToken != null) {
       _queryParams["waitToken"] = [waitToken];
     }
     if (clientVersion != null) {
       _queryParams["clientVersion"] = [clientVersion];
     }
     if (action_value != null) {
       _queryParams["action.value"] = [action_value];
     }
     if (includeInactive != null) {
       _queryParams["includeInactive"] = ["${includeInactive}"];
     }
     if (includeAllUsers != null) {
       _queryParams["includeAllUsers"] = ["${includeAllUsers}"];
     }
-    if (stripResults != null) {
-      _queryParams["stripResults"] = ["${stripResults}"];
-    }
 
     _url = 'v2/debugger/debuggees/' + commons.Escaper.ecapeVariable('$debuggeeId') + '/breakpoints';
 
     var _response = _requester.request(_url,
                                        "GET",
                                        body: _body,
                                        queryParams: _queryParams,
                                        uploadOptions: _uploadOptions,
                                        uploadMedia: _uploadMedia,
                                        downloadOptions: _downloadOptions);
     return _response.then((data) => new ListBreakpointsResponse.fromJson(data));
   }
 
   /**
    * Sets the breakpoint to the debuggee.
    *
    * [request] - The metadata request object.
    *
    * Request parameters:
    *
    * [debuggeeId] - ID of the debuggee where the breakpoint is to be set.
    *
    * [clientVersion] - The client version making the call.
-   * Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
+   * Schema: `domain/type/version` (e.g., `google.com/intellij/v1`).
    *
    * Completes with a [SetBreakpointResponse].
    *
    * Completes with a [commons.ApiRequestError] if the API endpoint returned an
    * error.
    *
    * If the used [http.Client] completes with an error when making a REST call,
    * this method will complete with the same error.
    */
   async.Future<SetBreakpointResponse> set(Breakpoint request, core.String debuggeeId, {core.String clientVersion}) {
@@ skipping 406 matching lines @@
       _json["snapshotId"] = snapshotId;
     }
     if (workspaceId != null) {
       _json["workspaceId"] = (workspaceId).toJson();
     }
     return _json;
   }
 }
 
 /**
- * Represents the application to debug. The application may include one or more
+ * Represents the debugged application. The application may include one or more
  * replicated processes executing the same code. Each of these processes is
  * attached with a debugger agent, carrying out the debugging commands.
- * The agents attached to the same debuggee are identified by using exactly the
- * same field values when registering.
+ * Agents attached to the same debuggee identify themselves as such by using
+ * exactly the same Debuggee message value when registering.
  */
 class Debuggee {
   /**
-   * Version ID of the agent release. The version ID is structured as
-   * following: `domain/type/vmajor.minor` (for example
-   * `google.com/gcp-java/v1.1`).
+   * Version ID of the agent.
+   * Schema: `domain/language-platform/vmajor.minor` (for example
+   * `google.com/java-gcp/v1.1`).
    */
   core.String agentVersion;
   /**
    * Human readable description of the debuggee.
    * Including a human-readable project name, environment name and version
    * information is recommended.
    */
   core.String description;
   /**
    * References to the locations and revisions of the source code used in the
    * deployed application.
    *
-   * Contexts describing a remote repo related to the source code
-   * have a `category` label of `remote_repo`. Source snapshot source
-   * contexts have a `category` of `snapshot`.
+   * NOTE: this field is experimental and can be ignored.
    */
   core.List<ExtendedSourceContext> extSourceContexts;
   /**
    * Unique identifier for the debuggee generated by the controller service.
    */
   core.String id;
   /**
    * If set to `true`, indicates that the agent should disable itself and
    * detach from the debuggee.
    */
   core.bool isDisabled;
   /**
-   * If set to `true`, indicates that the debuggee is considered as inactive by
-   * the Controller service.
+   * If set to `true`, indicates that Controller service does not detect any
+   * activity from the debuggee agents and the application is possibly stopped.
    */
   core.bool isInactive;
   /**
    * A set of custom debuggee properties, populated by the agent, to be
    * displayed to the user.
    */
   core.Map<core.String, core.String> labels;
   /**
    * Project the debuggee is associated with.
-   * Use the project number when registering a Google Cloud Platform project.
+   * Use project number or id when registering a Google Cloud Platform project.
    */
   core.String project;
   /**
    * References to the locations and revisions of the source code used in the
    * deployed application.
-   *
-   * NOTE: This field is deprecated. Consumers should use
-   * `ext_source_contexts` if it is not empty. Debug agents should populate
-   * both this field and `ext_source_contexts`.
    */
   core.List<SourceContext> sourceContexts;
   /**
    * Human readable message to be displayed to the user about this debuggee.
    * Absence of this field indicates no status. The message can be either
    * informational or an error status.
    */
   StatusMessage status;
   /**
-   * Debuggee uniquifier within the project.
-   * Any string that identifies the application within the project can be used.
-   * Including environment and version or build IDs is recommended.
+   * Uniquifier to further distiguish the application.
+   * It is possible that different applications might have identical values in
+   * the debuggee message, thus, incorrectly identified as a single application
+   * by the Controller service. This field adds salt to further distiguish the
+   * application. Agents should consider seeding this field with value that
+   * identifies the code, binary, configuration and environment.
    */
   core.String uniquifier;
 
   Debuggee();
 
   Debuggee.fromJson(core.Map _json) {
     if (_json.containsKey("agentVersion")) {
       agentVersion = _json["agentVersion"];
     }
     if (_json.containsKey("description")) {
@@ skipping 284 matching lines @@
 }
 
 /** Response for listing active breakpoints. */
 class ListActiveBreakpointsResponse {
   /**
    * List of all active breakpoints.
    * The fields `id` and `location` are guaranteed to be set on each breakpoint.
    */
   core.List<Breakpoint> breakpoints;
   /**
-   * A wait token that can be used in the next method call to block until
+   * A token that can be used in the next method call to block until
    * the list of breakpoints changes.
    */
   core.String nextWaitToken;
   /**
-   * The `wait_expired` field is set to true by the server when the
-   * request times out and the field `success_on_timeout` is set to true.
+   * If set to `true`, indicates that there is no change to the
+   * list of active breakpoints and the server-selected timeout has expired.
+   * The `breakpoints` field would be empty and should be ignored.
    */
   core.bool waitExpired;
 
   ListActiveBreakpointsResponse();
 
   ListActiveBreakpointsResponse.fromJson(core.Map _json) {
     if (_json.containsKey("breakpoints")) {
       breakpoints = _json["breakpoints"].map((value) => new Breakpoint.fromJson(value)).toList();
     }
     if (_json.containsKey("nextWaitToken")) {
@@ skipping 54 matching lines @@
       _json["nextWaitToken"] = nextWaitToken;
     }
     return _json;
   }
 }
 
 /** Response for listing debuggees. */
 class ListDebuggeesResponse {
   /**
    * List of debuggees accessible to the calling user.
-   * Note that the `description` field is the only human readable field
-   * that should be displayed to the user.
-   * The fields `debuggee.id` and  `description` fields are guaranteed to be
-   * set on each debuggee.
+   * The fields `debuggee.id` and `description` are guaranteed to be set.
+   * The `description` field is a human readable field provided by agents and
+   * can be displayed to users.
    */
   core.List<Debuggee> debuggees;
 
   ListDebuggeesResponse();
 
   ListDebuggeesResponse.fromJson(core.Map _json) {
     if (_json.containsKey("debuggees")) {
       debuggees = _json["debuggees"].map((value) => new Debuggee.fromJson(value)).toList();
     }
   }
@@ skipping 64 matching lines @@
     }
     return _json;
   }
 }
 
 /** Response for registering a debuggee. */
 class RegisterDebuggeeResponse {
   /**
    * Debuggee resource.
    * The field `id` is guranteed to be set (in addition to the echoed fields).
+   * If the field `is_disabled` is set to `true`, the agent should disable
+   * itself by removing all breakpoints and detaching from the application.
+   * It should however continue to poll `RegisterDebuggee` until reenabled.
    */
   Debuggee debuggee;
 
   RegisterDebuggeeResponse();
 
   RegisterDebuggeeResponse.fromJson(core.Map _json) {
     if (_json.containsKey("debuggee")) {
       debuggee = new Debuggee.fromJson(_json["debuggee"]);
     }
   }
@@ skipping 252 matching lines @@
     }
     return _json;
   }
 }
 
 /** Request to update an active breakpoint. */
 class UpdateActiveBreakpointRequest {
   /**
    * Updated breakpoint information.
    * The field `id` must be set.
+   * The agent must echo all Breakpoint specification fields in the update.
    */
   Breakpoint breakpoint;
 
   UpdateActiveBreakpointRequest();
 
   UpdateActiveBreakpointRequest.fromJson(core.Map _json) {
     if (_json.containsKey("breakpoint")) {
       breakpoint = new Breakpoint.fromJson(_json["breakpoint"]);
     }
   }
@@ skipping 217 matching lines @@
     }
     if (value != null) {
       _json["value"] = value;
     }
     if (varTableIndex != null) {
       _json["varTableIndex"] = varTableIndex;
     }
     return _json;
   }
 }