Skip to content

Commit 0c6fe23

Browse files
garrettjonesgooglegarrettjonesgoogle
committed
SPI updates: logging docs, LRO support
* Logging API: updating docs from proto * Speech API: introducing OperationFuture and OperationCallable to make handling of long-running operations easier
1 parent 00add6e commit 0c6fe23

8 files changed

Lines changed: 148 additions & 66 deletions

File tree

‎google-cloud-core/pom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@
111111
<dependency>
112112
<groupId>com.google.api</groupId>
113113
<artifactId>gax</artifactId>
114-
<version>0.0.24</version>
114+
<version>0.0.25</version>
115115
<exclusions>
116116
<exclusion>
117117
<groupId>io.grpc</groupId>

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

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@
3939

4040
// AUTO-GENERATED DOCUMENTATION AND SERVICE
4141
/**
42-
* Service Description: Service for configuring sinks used to export log entries outside Stackdriver
43-
* Logging.
42+
* Service Description: Service for configuring sinks used to export log entries outside of
43+
* Stackdriver Logging.
4444
*
4545
* <p>This class provides the ability to make remote calls to the backing service through method
4646
* calls that map to API methods. Sample code to get started:
@@ -218,8 +218,8 @@ public final ConfigServiceV2Settings getSettings() {
218218
* }
219219
* </code></pre>
220220
*
221-
* @param parent Required. The cloud resource containing the sinks. Example:
222-
* `"projects/my-logging-project"`.
221+
* @param parent Required. The resource name where this sink was created:
222+
* <p>"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]"
223223
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
224224
*/
225225
public final ListSinksPagedResponse listSinks(String parent) {
@@ -321,8 +321,9 @@ public final UnaryCallable<ListSinksRequest, ListSinksResponse> listSinksCallabl
321321
* }
322322
* </code></pre>
323323
*
324-
* @param sinkName Required. The resource name of the sink to return. Example:
325-
* `"projects/my-project-id/sinks/my-sink-id"`.
324+
* @param sinkName Required. The resource name of the sink to return:
325+
* <p>"projects/[PROJECT_ID]/sinks/[SINK_ID]"
326+
* "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
326327
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
327328
*/
328329
public final LogSink getSink(String sinkName) {
@@ -390,8 +391,8 @@ public final UnaryCallable<GetSinkRequest, LogSink> getSinkCallable() {
390391
* }
391392
* </code></pre>
392393
*
393-
* @param parent Required. The resource in which to create the sink. Example:
394-
* `"projects/my-project-id"`. The new sink must be provided in the request.
394+
* @param parent Required. The resource in which to create the sink:
395+
* <p>"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]"
395396
* @param sink Required. The new sink, whose `name` parameter is a sink identifier that is not
396397
* already in use.
397398
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
@@ -467,8 +468,10 @@ public final UnaryCallable<CreateSinkRequest, LogSink> createSinkCallable() {
467468
* </code></pre>
468469
*
469470
* @param sinkName Required. The resource name of the sink to update, including the parent
470-
* resource and the sink identifier. If the sink does not exist, this method creates the sink.
471-
* Example: `"projects/my-project-id/sinks/my-sink-id"`.
471+
* resource and the sink identifier:
472+
* <p>"projects/[PROJECT_ID]/sinks/[SINK_ID]"
473+
* "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
474+
* <p>Example: `"projects/my-project-id/sinks/my-sink-id"`.
472475
* @param sink Required. The updated sink, whose name is the same identifier that appears as part
473476
* of `sinkName`. If `sinkName` does not exist, then this method creates a new sink.
474477
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
@@ -543,8 +546,10 @@ public final UnaryCallable<UpdateSinkRequest, LogSink> updateSinkCallable() {
543546
* </code></pre>
544547
*
545548
* @param sinkName Required. The resource name of the sink to delete, including the parent
546-
* resource and the sink identifier. Example: `"projects/my-project-id/sinks/my-sink-id"`. It
547-
* is an error if the sink does not exist.
549+
* resource and the sink identifier:
550+
* <p>"projects/[PROJECT_ID]/sinks/[SINK_ID]"
551+
* "organizations/[ORGANIZATION_ID]/sinks/[SINK_ID]"
552+
* <p>It is an error if the sink does not exist.
548553
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
549554
*/
550555
public final void deleteSink(String sinkName) {

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

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ public final LoggingServiceV2Settings getSettings() {
218218

219219
// AUTO-GENERATED DOCUMENTATION AND METHOD
220220
/**
221-
* Deletes a log and all its log entries. The log will reappear if it receives new entries.
221+
* Deletes all the log entries in a log. The log reappears if it receives new entries.
222222
*
223223
* <p>Sample code:
224224
*
@@ -229,8 +229,11 @@ public final LoggingServiceV2Settings getSettings() {
229229
* }
230230
* </code></pre>
231231
*
232-
* @param logName Required. The resource name of the log to delete. Example:
233-
* `"projects/my-project/logs/syslog"`.
232+
* @param logName Required. The resource name of the log to delete:
233+
* <p>"projects/[PROJECT_ID]/logs/[LOG_ID]" "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
234+
* <p>`[LOG_ID]` must be URL-encoded. For example, `"projects/my-project-id/logs/syslog"`,
235+
* `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. For more
236+
* information about log names, see [LogEntry][google.logging.v2.LogEntry].
234237
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
235238
*/
236239
public final void deleteLog(String logName) {
@@ -241,7 +244,7 @@ public final void deleteLog(String logName) {
241244

242245
// AUTO-GENERATED DOCUMENTATION AND METHOD
243246
/**
244-
* Deletes a log and all its log entries. The log will reappear if it receives new entries.
247+
* Deletes all the log entries in a log. The log reappears if it receives new entries.
245248
*
246249
* <p>Sample code:
247250
*
@@ -264,7 +267,7 @@ private final void deleteLog(DeleteLogRequest request) {
264267

265268
// AUTO-GENERATED DOCUMENTATION AND METHOD
266269
/**
267-
* Deletes a log and all its log entries. The log will reappear if it receives new entries.
270+
* Deletes all the log entries in a log. The log reappears if it receives new entries.
268271
*
269272
* <p>Sample code:
270273
*
@@ -301,8 +304,11 @@ public final UnaryCallable<DeleteLogRequest, Empty> deleteLogCallable() {
301304
* </code></pre>
302305
*
303306
* @param logName Optional. A default log resource name that is assigned to all log entries in
304-
* `entries` that do not specify a value for `log_name`. Example:
305-
* `"projects/my-project/logs/syslog"`. See [LogEntry][google.logging.v2.LogEntry].
307+
* `entries` that do not specify a value for `log_name`:
308+
* <p>"projects/[PROJECT_ID]/logs/[LOG_ID]" "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
309+
* <p>`[LOG_ID]` must be URL-encoded. For example, `"projects/my-project-id/logs/syslog"` or
310+
* `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`. For more
311+
* information about log names, see [LogEntry][google.logging.v2.LogEntry].
306312
* @param resource Optional. A default monitored resource object that is assigned to all log
307313
* entries in `entries` that do not specify a value for `resource`. Example:
308314
* <p>{ "type": "gce_instance", "labels": { "zone": "us-central1-a", "instance_id":
@@ -402,12 +408,13 @@ public final WriteLogEntriesResponse writeLogEntries(WriteLogEntriesRequest requ
402408
* }
403409
* </code></pre>
404410
*
405-
* @param resourceNames Optional. One or more cloud resources from which to retrieve log entries.
406-
* Example: `"projects/my-project-1A"`, `"projects/1234567890"`. Projects listed in
407-
* `projectIds` are added to this list.
411+
* @param resourceNames Required. One or more cloud resources from which to retrieve log entries:
412+
* <p>"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]"
413+
* <p>Projects listed in the `project_ids` field are added to this list.
408414
* @param filter Optional. A filter that chooses which log entries to return. See [Advanced Logs
409415
* Filters](/logging/docs/view/advanced_filters). Only log entries that match the filter are
410-
* returned. An empty filter matches all log entries.
416+
* returned. An empty filter matches all log entries. The maximum length of the filter is
417+
* 20000 characters.
411418
* @param orderBy Optional. How the results should be sorted. Presently, the only permitted values
412419
* are `"timestamp asc"` (default) and `"timestamp desc"`. The first option returns entries in
413420
* 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‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -220,8 +220,8 @@ public final MetricsServiceV2Settings getSettings() {
220220
* }
221221
* </code></pre>
222222
*
223-
* @param parent Required. The resource name containing the metrics. Example:
224-
* `"projects/my-project-id"`.
223+
* @param parent Required. The name of the project containing the metrics:
224+
* <p>"projects/[PROJECT_ID]"
225225
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
226226
*/
227227
public final ListLogMetricsPagedResponse listLogMetrics(String parent) {
@@ -325,8 +325,8 @@ public final ListLogMetricsPagedResponse listLogMetrics(ListLogMetricsRequest re
325325
* }
326326
* </code></pre>
327327
*
328-
* @param metricName The resource name of the desired metric. Example:
329-
* `"projects/my-project-id/metrics/my-metric-id"`.
328+
* @param metricName The resource name of the desired metric:
329+
* <p>"projects/[PROJECT_ID]/metrics/[METRIC_ID]"
330330
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
331331
*/
332332
public final LogMetric getLogMetric(String metricName) {
@@ -395,8 +395,8 @@ public final UnaryCallable<GetLogMetricRequest, LogMetric> getLogMetricCallable(
395395
* }
396396
* </code></pre>
397397
*
398-
* @param parent The resource name of the project in which to create the metric. Example:
399-
* `"projects/my-project-id"`.
398+
* @param parent The resource name of the project in which to create the metric:
399+
* <p>"projects/[PROJECT_ID]"
400400
* <p>The new metric must be provided in the request.
401401
* @param metric The new logs-based metric, which must not have an identifier that already exists.
402402
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
@@ -471,12 +471,12 @@ public final UnaryCallable<CreateLogMetricRequest, LogMetric> createLogMetricCal
471471
* }
472472
* </code></pre>
473473
*
474-
* @param metricName The resource name of the metric to update. Example:
475-
* `"projects/my-project-id/metrics/my-metric-id"`.
476-
* <p>The updated metric must be provided in the request and have the same identifier that is
477-
* specified in `metricName`. If the metric does not exist, it is created.
478-
* @param metric The updated metric, whose name must be the same as the metric identifier in
479-
* `metricName`. If `metricName` does not exist, then a new metric is created.
474+
* @param metricName The resource name of the metric to update:
475+
* <p>"projects/[PROJECT_ID]/metrics/[METRIC_ID]"
476+
* <p>The updated metric must be provided in the request and it's `name` field must be the
477+
* same as `[METRIC_ID]` If the metric does not exist in `[PROJECT_ID]`, then a new metric is
478+
* created.
479+
* @param metric The updated metric.
480480
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
481481
*/
482482
public final LogMetric updateLogMetric(String metricName, LogMetric metric) {
@@ -548,8 +548,8 @@ public final UnaryCallable<UpdateLogMetricRequest, LogMetric> updateLogMetricCal
548548
* }
549549
* </code></pre>
550550
*
551-
* @param metricName The resource name of the metric to delete. Example:
552-
* `"projects/my-project-id/metrics/my-metric-id"`.
551+
* @param metricName The resource name of the metric to delete:
552+
* <p>"projects/[PROJECT_ID]/metrics/[METRIC_ID]"
553553
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
554554
*/
555555
public final void deleteLogMetric(String metricName) {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@
3636
*
3737
* ===================== ConfigServiceV2Client =====================
3838
*
39-
* <p>Service Description: Service for configuring sinks used to export log entries outside
39+
* <p>Service Description: Service for configuring sinks used to export log entries outside of
4040
* Stackdriver Logging.
4141
*
4242
* <p>Sample for ConfigServiceV2Client:

‎google-cloud-speech/src/main/java/com/google/cloud/speech/spi/v1beta1/SpeechClient.java‎

Lines changed: 65 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,16 +16,23 @@
1616
package com.google.cloud.speech.spi.v1beta1;
1717

1818
import com.google.api.gax.grpc.ChannelAndExecutor;
19+
import com.google.api.gax.grpc.FixedChannelProvider;
20+
import com.google.api.gax.grpc.FixedExecutorProvider;
21+
import com.google.api.gax.grpc.OperationCallable;
22+
import com.google.api.gax.grpc.OperationFuture;
1923
import com.google.api.gax.grpc.StreamingCallable;
2024
import com.google.api.gax.grpc.UnaryCallable;
2125
import com.google.cloud.speech.v1beta1.AsyncRecognizeRequest;
26+
import com.google.cloud.speech.v1beta1.AsyncRecognizeResponse;
2227
import com.google.cloud.speech.v1beta1.RecognitionAudio;
2328
import com.google.cloud.speech.v1beta1.RecognitionConfig;
2429
import com.google.cloud.speech.v1beta1.StreamingRecognizeRequest;
2530
import com.google.cloud.speech.v1beta1.StreamingRecognizeResponse;
2631
import com.google.cloud.speech.v1beta1.SyncRecognizeRequest;
2732
import com.google.cloud.speech.v1beta1.SyncRecognizeResponse;
2833
import com.google.longrunning.Operation;
34+
import com.google.longrunning.OperationsClient;
35+
import com.google.longrunning.OperationsSettings;
2936
import com.google.protobuf.ExperimentalApi;
3037
import io.grpc.ManagedChannel;
3138
import java.io.Closeable;
@@ -97,10 +104,13 @@ public class SpeechClient implements AutoCloseable {
97104
private final SpeechSettings settings;
98105
private final ScheduledExecutorService executor;
99106
private final ManagedChannel channel;
107+
private final OperationsClient operationsClient;
100108
private final List<AutoCloseable> closeables = new ArrayList<>();
101109

102110
private final UnaryCallable<SyncRecognizeRequest, SyncRecognizeResponse> syncRecognizeCallable;
103111
private final UnaryCallable<AsyncRecognizeRequest, Operation> asyncRecognizeCallable;
112+
private final OperationCallable<AsyncRecognizeRequest, AsyncRecognizeResponse>
113+
asyncRecognizeOperationCallable;
104114
private final StreamingCallable<StreamingRecognizeRequest, StreamingRecognizeResponse>
105115
streamingRecognizeCallable;
106116

@@ -127,10 +137,25 @@ protected SpeechClient(SpeechSettings settings) throws IOException {
127137
this.executor = channelAndExecutor.getExecutor();
128138
this.channel = channelAndExecutor.getChannel();
129139

140+
FixedExecutorProvider executorProvider = FixedExecutorProvider.create(this.executor);
141+
FixedChannelProvider channelProvider = FixedChannelProvider.create(this.channel);
142+
OperationsSettings operationsSettings =
143+
OperationsSettings.defaultBuilder()
144+
.setExecutorProvider(executorProvider)
145+
.setChannelProvider(channelProvider)
146+
.build();
147+
this.operationsClient = OperationsClient.create(operationsSettings);
148+
130149
this.syncRecognizeCallable =
131150
UnaryCallable.create(settings.syncRecognizeSettings(), this.channel, this.executor);
132151
this.asyncRecognizeCallable =
133-
UnaryCallable.create(settings.asyncRecognizeSettings(), this.channel, this.executor);
152+
UnaryCallable.create(
153+
settings.asyncRecognizeSettings().getInitialCallSettings(),
154+
this.channel,
155+
this.executor);
156+
this.asyncRecognizeOperationCallable =
157+
OperationCallable.create(
158+
settings.asyncRecognizeSettings(), this.channel, this.executor, this.operationsClient);
134159
this.streamingRecognizeCallable =
135160
StreamingCallable.create(settings.streamingRecognizeSettings(), this.channel);
136161

@@ -158,6 +183,10 @@ public final SpeechSettings getSettings() {
158183
return settings;
159184
}
160185

186+
public final OperationsClient getOperationsClient() {
187+
return operationsClient;
188+
}
189+
161190
// AUTO-GENERATED DOCUMENTATION AND METHOD
162191
/**
163192
* Perform synchronous speech-recognition: receive results after all audio has been sent and
@@ -249,7 +278,7 @@ public final UnaryCallable<SyncRecognizeRequest, SyncRecognizeResponse> syncReco
249278
* try (SpeechClient speechClient = SpeechClient.create()) {
250279
* RecognitionConfig config = RecognitionConfig.newBuilder().build();
251280
* RecognitionAudio audio = RecognitionAudio.newBuilder().build();
252-
* Operation response = speechClient.asyncRecognize(config, audio);
281+
* AsyncRecognizeResponse response = speechClient.asyncRecognizeAsync(config, audio).get();
253282
* }
254283
* </code></pre>
255284
*
@@ -258,11 +287,12 @@ public final UnaryCallable<SyncRecognizeRequest, SyncRecognizeResponse> syncReco
258287
* @param audio [Required] The audio data to be recognized.
259288
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
260289
*/
261-
public final Operation asyncRecognize(RecognitionConfig config, RecognitionAudio audio) {
290+
public final OperationFuture<AsyncRecognizeResponse> asyncRecognizeAsync(
291+
RecognitionConfig config, RecognitionAudio audio) {
262292

263293
AsyncRecognizeRequest request =
264294
AsyncRecognizeRequest.newBuilder().setConfig(config).setAudio(audio).build();
265-
return asyncRecognize(request);
295+
return asyncRecognizeAsync(request);
266296
}
267297

268298
// AUTO-GENERATED DOCUMENTATION AND METHOD
@@ -281,15 +311,43 @@ public final Operation asyncRecognize(RecognitionConfig config, RecognitionAudio
281311
* .setConfig(config)
282312
* .setAudio(audio)
283313
* .build();
284-
* Operation response = speechClient.asyncRecognize(request);
314+
* AsyncRecognizeResponse response = speechClient.asyncRecognizeAsync(request).get();
285315
* }
286316
* </code></pre>
287317
*
288318
* @param request The request object containing all of the parameters for the API call.
289319
* @throws com.google.api.gax.grpc.ApiException if the remote call fails
290320
*/
291-
public final Operation asyncRecognize(AsyncRecognizeRequest request) {
292-
return asyncRecognizeCallable().call(request);
321+
public final OperationFuture<AsyncRecognizeResponse> asyncRecognizeAsync(
322+
AsyncRecognizeRequest request) {
323+
return asyncRecognizeOperationCallable().futureCall(request);
324+
}
325+
326+
// AUTO-GENERATED DOCUMENTATION AND METHOD
327+
/**
328+
* Perform asynchronous speech-recognition: receive results via the google.longrunning.Operations
329+
* interface. Returns either an `Operation.error` or an `Operation.response` which contains an
330+
* `AsyncRecognizeResponse` message.
331+
*
332+
* <p>Sample code:
333+
*
334+
* <pre><code>
335+
* try (SpeechClient speechClient = SpeechClient.create()) {
336+
* RecognitionConfig config = RecognitionConfig.newBuilder().build();
337+
* RecognitionAudio audio = RecognitionAudio.newBuilder().build();
338+
* AsyncRecognizeRequest request = AsyncRecognizeRequest.newBuilder()
339+
* .setConfig(config)
340+
* .setAudio(audio)
341+
* .build();
342+
* OperationFuture&lt;Operation&gt; future = speechClient.asyncRecognizeOperationCallable().futureCall(request);
343+
* // Do something
344+
* AsyncRecognizeResponse response = future.get();
345+
* }
346+
* </code></pre>
347+
*/
348+
public final OperationCallable<AsyncRecognizeRequest, AsyncRecognizeResponse>
349+
asyncRecognizeOperationCallable() {
350+
return asyncRecognizeOperationCallable;
293351
}
294352

295353
// AUTO-GENERATED DOCUMENTATION AND METHOD

0 commit comments

Comments
 (0)