SPI updates: logging docs, LRO support (#1419)

* Logging API: updating docs from proto
* Speech API: introducing OperationFuture and OperationCallable
to make handling of long-running operations easier

google-cloud-core/pom.xml

@@ -111,7 +111,7 @@
     <dependency>
       <groupId>com.google.api</groupId>
       <artifactId>gax</artifactId>
-      <version>0.0.24</version>
+      <version>0.0.25</version>
       <exclusions>
         <exclusion>
           <groupId>io.grpc</groupId>

google-cloud-logging/src/main/java/com/google/cloud/logging/spi/v2/ConfigServiceV2Client.java

@@ -39,8 +39,8 @@
 
 // AUTO-GENERATED DOCUMENTATION AND SERVICE
 /**
- * Service Description: Service for configuring sinks used to export log entries outside Stackdriver
- * Logging.
+ * Service Description: Service for configuring sinks used to export log entries outside of
+ * Stackdriver Logging.
  *
  * <p>This class provides the ability to make remote calls to the backing service through method
  * calls that map to API methods. Sample code to get started:
@@ -218,12 +218,11 @@ public final ConfigServiceV2Settings getSettings() {
    * }
    * </code></pre>
    *
-   * @param parent Required. The cloud resource containing the sinks. Example:
-   *     `"projects/my-logging-project"`.
+   * @param parent Required. The resource name where this sink was created:
+   *     <p>"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]"
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final ListSinksPagedResponse listSinks(String parent) {
-    PARENT_PATH_TEMPLATE.validate(parent, "listSinks");
     ListSinksRequest request = ListSinksRequest.newBuilder().setParent(parent).build();
     return listSinks(request);
   }
@@ -321,12 +320,13 @@ public final UnaryCallable<ListSinksRequest, ListSinksResponse> listSinksCallabl
    * }
    * </code></pre>
    *
-   * @param sinkName Required. The resource name of the sink to return. Example:
-   *     `"projects/my-project-id/sinks/my-sink-id"`.
+   * @param sinkName Required. The resource name of the sink to return:
+   *     <p>"projects/[PROJECT_ID]/sinks/[SINK_ID]"
+   *     "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final LogSink getSink(String sinkName) {
-    SINK_PATH_TEMPLATE.validate(sinkName, "getSink");
+
     GetSinkRequest request = GetSinkRequest.newBuilder().setSinkName(sinkName).build();
     return getSink(request);
   }
@@ -390,14 +390,14 @@ public final UnaryCallable<GetSinkRequest, LogSink> getSinkCallable() {
    * }
    * </code></pre>
    *
-   * @param parent Required. The resource in which to create the sink. Example:
-   *     `"projects/my-project-id"`. The new sink must be provided in the request.
+   * @param parent Required. The resource in which to create the sink:
+   *     <p>"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]"
    * @param sink Required. The new sink, whose `name` parameter is a sink identifier that is not
    *     already in use.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final LogSink createSink(String parent, LogSink sink) {
-    PARENT_PATH_TEMPLATE.validate(parent, "createSink");
+
     CreateSinkRequest request =
         CreateSinkRequest.newBuilder().setParent(parent).setSink(sink).build();
     return createSink(request);
@@ -467,14 +467,16 @@ public final UnaryCallable<CreateSinkRequest, LogSink> createSinkCallable() {
    * </code></pre>
    *
    * @param sinkName Required. The resource name of the sink to update, including the parent
-   *     resource and the sink identifier. If the sink does not exist, this method creates the sink.
-   *     Example: `"projects/my-project-id/sinks/my-sink-id"`.
+   *     resource and the sink identifier:
+   *     <p>"projects/[PROJECT_ID]/sinks/[SINK_ID]"
+   *     "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+   *     <p>Example: `"projects/my-project-id/sinks/my-sink-id"`.
    * @param sink Required. The updated sink, whose name is the same identifier that appears as part
    *     of `sinkName`. If `sinkName` does not exist, then this method creates a new sink.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final LogSink updateSink(String sinkName, LogSink sink) {
-    SINK_PATH_TEMPLATE.validate(sinkName, "updateSink");
+
     UpdateSinkRequest request =
         UpdateSinkRequest.newBuilder().setSinkName(sinkName).setSink(sink).build();
     return updateSink(request);
@@ -543,12 +545,14 @@ public final UnaryCallable<UpdateSinkRequest, LogSink> updateSinkCallable() {
    * </code></pre>
    *
    * @param sinkName Required. The resource name of the sink to delete, including the parent
-   *     resource and the sink identifier. Example: `"projects/my-project-id/sinks/my-sink-id"`. It
-   *     is an error if the sink does not exist.
+   *     resource and the sink identifier:
+   *     <p>"projects/[PROJECT_ID]/sinks/[SINK_ID]"
+   *     "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
+   *     <p>It is an error if the sink does not exist.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final void deleteSink(String sinkName) {
-    SINK_PATH_TEMPLATE.validate(sinkName, "deleteSink");
+
     DeleteSinkRequest request = DeleteSinkRequest.newBuilder().setSinkName(sinkName).build();
     deleteSink(request);
   }

google-cloud-logging/src/main/java/com/google/cloud/logging/spi/v2/LoggingServiceV2Client.java

@@ -218,7 +218,7 @@ public final LoggingServiceV2Settings getSettings() {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD
   /**
-   * Deletes a log and all its log entries. The log will reappear if it receives new entries.
+   * Deletes all the log entries in a log. The log reappears if it receives new entries.
    *
    * <p>Sample code:
    *
@@ -229,19 +229,22 @@ public final LoggingServiceV2Settings getSettings() {
    * }
    * </code></pre>
    *
-   * @param logName Required. The resource name of the log to delete. Example:
-   *     `"projects/my-project/logs/syslog"`.
+   * @param logName Required. The resource name of the log to delete:
+   *     <p>"projects/[PROJECT_ID]/logs/[LOG_ID]" "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
+   *     <p>`[LOG_ID]` must be URL-encoded. For example, `"projects/my-project-id/logs/syslog"`,
+   *     `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. For more
+   *     information about log names, see [LogEntry][google.logging.v2.LogEntry].
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final void deleteLog(String logName) {
-    LOG_PATH_TEMPLATE.validate(logName, "deleteLog");
+
     DeleteLogRequest request = DeleteLogRequest.newBuilder().setLogName(logName).build();
     deleteLog(request);
   }
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD
   /**
-   * Deletes a log and all its log entries. The log will reappear if it receives new entries.
+   * Deletes all the log entries in a log. The log reappears if it receives new entries.
    *
    * <p>Sample code:
    *
@@ -264,7 +267,7 @@ private final void deleteLog(DeleteLogRequest request) {
 
   // AUTO-GENERATED DOCUMENTATION AND METHOD
   /**
-   * Deletes a log and all its log entries. The log will reappear if it receives new entries.
+   * Deletes all the log entries in a log. The log reappears if it receives new entries.
    *
    * <p>Sample code:
    *
@@ -301,8 +304,11 @@ public final UnaryCallable<DeleteLogRequest, Empty> deleteLogCallable() {
    * </code></pre>
    *
    * @param logName Optional. A default log resource name that is assigned to all log entries in
-   *     `entries` that do not specify a value for `log_name`. Example:
-   *     `"projects/my-project/logs/syslog"`. See [LogEntry][google.logging.v2.LogEntry].
+   *     `entries` that do not specify a value for `log_name`:
+   *     <p>"projects/[PROJECT_ID]/logs/[LOG_ID]" "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
+   *     <p>`[LOG_ID]` must be URL-encoded. For example, `"projects/my-project-id/logs/syslog"` or
+   *     `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. For more
+   *     information about log names, see [LogEntry][google.logging.v2.LogEntry].
    * @param resource Optional. A default monitored resource object that is assigned to all log
    *     entries in `entries` that do not specify a value for `resource`. Example:
    *     <p>{ "type": "gce_instance", "labels": { "zone": "us-central1-a", "instance_id":
@@ -325,9 +331,7 @@ public final WriteLogEntriesResponse writeLogEntries(
       MonitoredResource resource,
       Map<String, String> labels,
       List<LogEntry> entries) {
-    if (!logName.isEmpty()) {
-      LOG_PATH_TEMPLATE.validate(logName, "writeLogEntries");
-    }
+
     WriteLogEntriesRequest request =
         WriteLogEntriesRequest.newBuilder()
             .setLogName(logName)
@@ -402,12 +406,13 @@ public final WriteLogEntriesResponse writeLogEntries(WriteLogEntriesRequest requ
    * }
    * </code></pre>
    *
-   * @param resourceNames Optional. One or more cloud resources from which to retrieve log entries.
-   *     Example: `"projects/my-project-1A"`, `"projects/1234567890"`. Projects listed in
-   *     `projectIds` are added to this list.
+   * @param resourceNames Required. One or more cloud resources from which to retrieve log entries:
+   *     <p>"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]"
+   *     <p>Projects listed in the `project_ids` field are added to this list.
    * @param filter Optional. A filter that chooses which log entries to return. See [Advanced Logs
    *     Filters](/logging/docs/view/advanced_filters). Only log entries that match the filter are
-   *     returned. An empty filter matches all log entries.
+   *     returned. An empty filter matches all log entries. The maximum length of the filter is
+   *     20000 characters.
    * @param orderBy Optional. How the results should be sorted. Presently, the only permitted values
    *     are `"timestamp asc"` (default) and `"timestamp desc"`. The first option returns entries in
    *     order of increasing values of `LogEntry.timestamp` (oldest first), and the second option

google-cloud-logging/src/main/java/com/google/cloud/logging/spi/v2/MetricsServiceV2Client.java

@@ -220,12 +220,11 @@ public final MetricsServiceV2Settings getSettings() {
    * }
    * </code></pre>
    *
-   * @param parent Required. The resource name containing the metrics. Example:
-   *     `"projects/my-project-id"`.
+   * @param parent Required. The name of the project containing the metrics:
+   *     <p>"projects/[PROJECT_ID]"
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final ListLogMetricsPagedResponse listLogMetrics(String parent) {
-    PARENT_PATH_TEMPLATE.validate(parent, "listLogMetrics");
     ListLogMetricsRequest request = ListLogMetricsRequest.newBuilder().setParent(parent).build();
     return listLogMetrics(request);
   }
@@ -325,8 +324,8 @@ public final ListLogMetricsPagedResponse listLogMetrics(ListLogMetricsRequest re
    * }
    * </code></pre>
    *
-   * @param metricName The resource name of the desired metric. Example:
-   *     `"projects/my-project-id/metrics/my-metric-id"`.
+   * @param metricName The resource name of the desired metric:
+   *     <p>"projects/[PROJECT_ID]/metrics/[METRIC_ID]"
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final LogMetric getLogMetric(String metricName) {
@@ -395,14 +394,14 @@ public final UnaryCallable<GetLogMetricRequest, LogMetric> getLogMetricCallable(
    * }
    * </code></pre>
    *
-   * @param parent The resource name of the project in which to create the metric. Example:
-   *     `"projects/my-project-id"`.
+   * @param parent The resource name of the project in which to create the metric:
+   *     <p>"projects/[PROJECT_ID]"
    *     <p>The new metric must be provided in the request.
    * @param metric The new logs-based metric, which must not have an identifier that already exists.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final LogMetric createLogMetric(String parent, LogMetric metric) {
-    PARENT_PATH_TEMPLATE.validate(parent, "createLogMetric");
+
     CreateLogMetricRequest request =
         CreateLogMetricRequest.newBuilder().setParent(parent).setMetric(metric).build();
     return createLogMetric(request);
@@ -471,12 +470,12 @@ public final UnaryCallable<CreateLogMetricRequest, LogMetric> createLogMetricCal
    * }
    * </code></pre>
    *
-   * @param metricName The resource name of the metric to update. Example:
-   *     `"projects/my-project-id/metrics/my-metric-id"`.
-   *     <p>The updated metric must be provided in the request and have the same identifier that is
-   *     specified in `metricName`. If the metric does not exist, it is created.
-   * @param metric The updated metric, whose name must be the same as the metric identifier in
-   *     `metricName`. If `metricName` does not exist, then a new metric is created.
+   * @param metricName The resource name of the metric to update:
+   *     <p>"projects/[PROJECT_ID]/metrics/[METRIC_ID]"
+   *     <p>The updated metric must be provided in the request and it's `name` field must be the
+   *     same as `[METRIC_ID]` If the metric does not exist in `[PROJECT_ID]`, then a new metric is
+   *     created.
+   * @param metric The updated metric.
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final LogMetric updateLogMetric(String metricName, LogMetric metric) {
@@ -548,8 +547,8 @@ public final UnaryCallable<UpdateLogMetricRequest, LogMetric> updateLogMetricCal
    * }
    * </code></pre>
    *
-   * @param metricName The resource name of the metric to delete. Example:
-   *     `"projects/my-project-id/metrics/my-metric-id"`.
+   * @param metricName The resource name of the metric to delete:
+   *     <p>"projects/[PROJECT_ID]/metrics/[METRIC_ID]"
    * @throws com.google.api.gax.grpc.ApiException if the remote call fails
    */
   public final void deleteLogMetric(String metricName) {

google-cloud-logging/src/main/java/com/google/cloud/logging/spi/v2/package-info.java

@@ -36,7 +36,7 @@
  *
  * ===================== ConfigServiceV2Client =====================
  *
- * <p>Service Description: Service for configuring sinks used to export log entries outside
+ * <p>Service Description: Service for configuring sinks used to export log entries outside of
  * Stackdriver Logging.
  *
  * <p>Sample for ConfigServiceV2Client: