diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java index 97982a32c4..35dff2c4d7 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientClassComposer.java @@ -566,13 +566,13 @@ private static List createMethodVariants( .build(); Optional methodSampleCode = Optional.empty(); - if (!method.isPaged() && !method.hasLro()) { - // TODO(summerji): Remove the condition check once finished the implementation on paged - // sample code and lro sample code. + if (!method.hasLro()) { + // TODO(summerji): Remove the condition check once finished the implementation on lro sample + // code. methodSampleCode = Optional.of( ServiceClientSampleCodeComposer.composeRpcMethodHeaderSampleCode( - method, types.get(clientName), signature, resourceNames)); + method, types.get(clientName), signature, resourceNames, messageTypes)); } MethodDefinition.Builder methodVariantBuilder = MethodDefinition.builder() diff --git a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposer.java b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposer.java index b009d079c4..7211ae8ce6 100644 --- a/src/main/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposer.java +++ b/src/main/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposer.java @@ -16,26 +16,32 @@ import com.google.api.gax.core.FixedCredentialsProvider; import com.google.api.generator.engine.ast.AssignmentExpr; +import com.google.api.generator.engine.ast.CommentStatement; import com.google.api.generator.engine.ast.ConcreteReference; import com.google.api.generator.engine.ast.Expr; import com.google.api.generator.engine.ast.ExprStatement; +import com.google.api.generator.engine.ast.ForStatement; +import com.google.api.generator.engine.ast.LineComment; import com.google.api.generator.engine.ast.MethodInvocationExpr; +import com.google.api.generator.engine.ast.Statement; import com.google.api.generator.engine.ast.TryCatchStatement; import com.google.api.generator.engine.ast.TypeNode; import com.google.api.generator.engine.ast.VaporReference; import com.google.api.generator.engine.ast.Variable; import com.google.api.generator.engine.ast.VariableExpr; import com.google.api.generator.gapic.composer.samplecode.SampleCodeWriter; +import com.google.api.generator.gapic.model.Field; +import com.google.api.generator.gapic.model.Message; import com.google.api.generator.gapic.model.Method; import com.google.api.generator.gapic.model.MethodArgument; import com.google.api.generator.gapic.model.ResourceName; import com.google.api.generator.gapic.utils.JavaStyle; import com.google.common.annotations.VisibleForTesting; import com.google.common.base.Preconditions; -import java.util.ArrayList; import java.util.Arrays; import java.util.List; import java.util.Map; +import java.util.function.Function; import java.util.stream.Collectors; import java.util.stream.IntStream; @@ -186,8 +192,24 @@ public static String composeRpcMethodHeaderSampleCode( Method method, TypeNode clientType, List arguments, - Map resourceNames) { + Map resourceNames, + Map messageTypes) { // TODO(summerji): Add other types RPC methods' sample code. + if (method.isPaged()) { + // Find the repeated field. + Message methodOutputMessage = messageTypes.get(method.outputType().reference().simpleName()); + Field repeatedPagedResultsField = methodOutputMessage.findAndUnwrapFirstRepeatedField(); + Preconditions.checkNotNull( + repeatedPagedResultsField, + String.format( + "No repeated field found on message %s for method %s", + methodOutputMessage.name(), method.name())); + + TypeNode repeatedResponseType = repeatedPagedResultsField.type(); + return SampleCodeWriter.write( + composeUnaryPagedRpcMethodSampleCode( + method, clientType, repeatedResponseType, arguments, resourceNames)); + } return SampleCodeWriter.write( composeUnaryRpcMethodSampleCode(method, clientType, arguments, resourceNames)); } @@ -204,52 +226,12 @@ static TryCatchStatement composeUnaryRpcMethodSampleCode( .setName(JavaStyle.toLowerCamelCase(clientType.reference().name())) .setType(clientType) .build()); - // List of rpc method arguments' variable expressions. - List rpcMethodArgVarExprs = - arguments.stream() - .map( - arg -> - VariableExpr.withVariable( - Variable.builder() - .setName(JavaStyle.toLowerCamelCase(arg.name())) - .setType(arg.type()) - .build())) - .collect(Collectors.toList()); - // List of rpc method arguments' default value expression. - List resourceNameList = - resourceNames.values().stream().collect(Collectors.toList()); + List rpcMethodArgVarExprs = createRpcMethodArgumentVariableExprs(arguments); List rpcMethodArgDefaultValueExprs = - arguments.stream() - .map( - arg -> - !isStringTypedResourceName(arg, resourceNames) - ? DefaultValueComposer.createDefaultValue(arg, resourceNames) - : MethodInvocationExpr.builder() - .setExprReferenceExpr( - DefaultValueComposer.createDefaultValue( - resourceNames.get( - arg.field().resourceReference().resourceTypeString()), - resourceNameList, - arg.field().name())) - .setMethodName("toString") - .setReturnType(TypeNode.STRING) - .build()) - .collect(Collectors.toList()); - - List bodyExprs = new ArrayList<>(); - Preconditions.checkState( - rpcMethodArgVarExprs.size() == rpcMethodArgDefaultValueExprs.size(), - "Expected the number of method arguments to match the number of default values."); - bodyExprs.addAll( - IntStream.range(0, rpcMethodArgVarExprs.size()) - .mapToObj( - i -> - AssignmentExpr.builder() - .setVariableExpr( - (rpcMethodArgVarExprs.get(i)).toBuilder().setIsDecl(true).build()) - .setValueExpr(rpcMethodArgDefaultValueExprs.get(i)) - .build()) - .collect(Collectors.toList())); + createRpcMethodArgumentDefaultValueExprs(arguments, resourceNames); + List bodyExprs = + createAssignmentsForVarExprsWithValueExprs( + rpcMethodArgVarExprs, rpcMethodArgDefaultValueExprs); // Invoke current method based on return type. // e.g. if return void, echoClient.echo(..); or, // e.g. if return other type, EchoResponse response = echoClient.echo(...); @@ -290,8 +272,125 @@ static TryCatchStatement composeUnaryRpcMethodSampleCode( .build(); } + @VisibleForTesting + static TryCatchStatement composeUnaryPagedRpcMethodSampleCode( + Method method, + TypeNode clientType, + TypeNode repeatedResponseType, + List arguments, + Map resourceNames) { + VariableExpr clientVarExpr = + VariableExpr.withVariable( + Variable.builder() + .setName(JavaStyle.toLowerCamelCase(clientType.reference().name())) + .setType(clientType) + .build()); + List rpcMethodArgVarExprs = createRpcMethodArgumentVariableExprs(arguments); + List rpcMethodArgDefaultValueExprs = + createRpcMethodArgumentDefaultValueExprs(arguments, resourceNames); + List bodyExprs = + createAssignmentsForVarExprsWithValueExprs( + rpcMethodArgVarExprs, rpcMethodArgDefaultValueExprs); + // For loop paged response item on iterateAll method. + // e.g. for (LogEntry element : loggingServiceV2Client.ListLogs(parent).iterateAll()) { + // //doThingsWith(element); + // } + MethodInvocationExpr clientMethodExpr = + MethodInvocationExpr.builder() + .setExprReferenceExpr(clientVarExpr) + .setMethodName(JavaStyle.toLowerCamelCase(method.name())) + .setArguments( + rpcMethodArgVarExprs.stream().map(e -> (Expr) e).collect(Collectors.toList())) + .build(); + Expr clientMethodIteratorAllExpr = + MethodInvocationExpr.builder() + .setExprReferenceExpr(clientMethodExpr) + .setMethodName("iterateAll") + .setReturnType(repeatedResponseType) + .build(); + ForStatement loopIteratorStatement = + ForStatement.builder() + .setLocalVariableExpr( + VariableExpr.builder() + .setVariable( + Variable.builder().setName("element").setType(repeatedResponseType).build()) + .setIsDecl(true) + .build()) + .setCollectionExpr(clientMethodIteratorAllExpr) + .setBody( + Arrays.asList( + CommentStatement.withComment( + LineComment.withComment("doThingsWith(element);")))) + .build(); + + List bodyStatements = + bodyExprs.stream().map(e -> ExprStatement.withExpr(e)).collect(Collectors.toList()); + bodyStatements.add(loopIteratorStatement); + + return TryCatchStatement.builder() + .setTryResourceExpr(assignClientVariableWithCreateMethodExpr(clientVarExpr)) + .setTryBody(bodyStatements) + .setIsSampleCode(true) + .build(); + } + // ==================================Helpers===================================================// + // Create a list of RPC method arguments' variable expressions. + private static List createRpcMethodArgumentVariableExprs( + List arguments) { + return arguments.stream() + .map( + arg -> + VariableExpr.withVariable( + Variable.builder() + .setName(JavaStyle.toLowerCamelCase(arg.name())) + .setType(arg.type()) + .build())) + .collect(Collectors.toList()); + } + + // Create a list of RPC method arguments' default value expression. + private static List createRpcMethodArgumentDefaultValueExprs( + List arguments, Map resourceNames) { + List resourceNameList = + resourceNames.values().stream().collect(Collectors.toList()); + Function stringResourceNameDefaultValueExpr = + arg -> + MethodInvocationExpr.builder() + .setExprReferenceExpr( + DefaultValueComposer.createDefaultValue( + resourceNames.get(arg.field().resourceReference().resourceTypeString()), + resourceNameList, + arg.field().name())) + .setMethodName("toString") + .setReturnType(TypeNode.STRING) + .build(); + return arguments.stream() + .map( + arg -> + !isStringTypedResourceName(arg, resourceNames) + ? DefaultValueComposer.createDefaultValue(arg, resourceNames) + : stringResourceNameDefaultValueExpr.apply(arg)) + .collect(Collectors.toList()); + } + + // Create a list of assignment expressions for variable expr with value expr. + private static List createAssignmentsForVarExprsWithValueExprs( + List variableExprs, List valueExprs) { + Preconditions.checkState( + variableExprs.size() == valueExprs.size(), + "Expected the number of method arguments to match the number of default values."); + return IntStream.range(0, variableExprs.size()) + .mapToObj( + i -> + AssignmentExpr.builder() + .setVariableExpr(variableExprs.get(i).toBuilder().setIsDecl(true).build()) + .setValueExpr(valueExprs.get(i)) + .build()) + .collect(Collectors.toList()); + } + // Assign client variable expr with create client. // e.g EchoClient echoClient = EchoClient.create() private static AssignmentExpr assignClientVariableWithCreateMethodExpr( diff --git a/src/test/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposerTest.java b/src/test/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposerTest.java index 384f2d97c1..e902ef0177 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposerTest.java +++ b/src/test/java/com/google/api/generator/gapic/composer/ServiceClientSampleCodeComposerTest.java @@ -15,6 +15,7 @@ package com.google.api.generator.gapic.composer; import static junit.framework.Assert.assertEquals; +import static org.junit.Assert.assertThrows; import com.google.api.generator.engine.ast.ConcreteReference; import com.google.api.generator.engine.ast.Reference; @@ -22,6 +23,7 @@ import com.google.api.generator.engine.ast.VaporReference; import com.google.api.generator.gapic.composer.samplecode.SampleCodeWriter; import com.google.api.generator.gapic.model.Field; +import com.google.api.generator.gapic.model.Message; import com.google.api.generator.gapic.model.Method; import com.google.api.generator.gapic.model.MethodArgument; import com.google.api.generator.gapic.model.ResourceName; @@ -34,16 +36,17 @@ import java.util.Collections; import java.util.List; import java.util.Map; -import org.junit.Assert; import org.junit.Test; public class ServiceClientSampleCodeComposerTest { private static final String SHOWCASE_PACKAGE_NAME = "com.google.showcase.v1beta1"; + // =======================================RPC Method Header Sample Code=======================// @Test public void validComposeRpcMethodHeaderSampleCode_pureUnaryRpc() { FileDescriptor echoFileDescriptor = EchoOuterClass.getDescriptor(); Map resourceNames = Parser.parseResourceNames(echoFileDescriptor); + Map messageTypes = Parser.parseMessages(echoFileDescriptor); TypeNode clientType = TypeNode.withReference( VaporReference.builder() @@ -72,7 +75,7 @@ public void validComposeRpcMethodHeaderSampleCode_pureUnaryRpc() { .build(); String results = ServiceClientSampleCodeComposer.composeRpcMethodHeaderSampleCode( - method, clientType, methodArguments, resourceNames); + method, clientType, methodArguments, resourceNames, messageTypes); String expected = LineFormatter.lines( "try (EchoClient echoClient = EchoClient.create()) {\n", @@ -81,6 +84,150 @@ public void validComposeRpcMethodHeaderSampleCode_pureUnaryRpc() { assertEquals(expected, results); } + @Test + public void validComposeRpcMethodHeaderSampleCode_pagedUnaryRpc() { + FileDescriptor echoFileDescriptor = EchoOuterClass.getDescriptor(); + Map resourceNames = Parser.parseResourceNames(echoFileDescriptor); + Map messageTypes = Parser.parseMessages(echoFileDescriptor); + TypeNode clientType = + TypeNode.withReference( + VaporReference.builder() + .setName("EchoClient") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode inputType = + TypeNode.withReference( + VaporReference.builder() + .setName("PagedExpandRequest") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode outputType = + TypeNode.withReference( + VaporReference.builder() + .setName("PagedExpandResponse") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + Method method = + Method.builder() + .setName("SimplePagedExpand") + .setMethodSignatures(Collections.emptyList()) + .setInputType(inputType) + .setOutputType(outputType) + .setIsPaged(true) + .build(); + String results = + ServiceClientSampleCodeComposer.composeRpcMethodHeaderSampleCode( + method, clientType, Collections.emptyList(), resourceNames, messageTypes); + String expected = + LineFormatter.lines( + "try (EchoClient echoClient = EchoClient.create()) {\n", + " for (EchoResponse element : echoClient.simplePagedExpand().iterateAll()) {\n", + " // doThingsWith(element);\n", + " }\n", + "}"); + assertEquals(expected, results); + } + + @Test + public void invalidComposeRpcMethodHeaderSampleCode_noMatchedRepeatedResponseTypeInPagedMethod() { + FileDescriptor echoFileDescriptor = EchoOuterClass.getDescriptor(); + Map resourceNames = Parser.parseResourceNames(echoFileDescriptor); + Map messageTypes = Parser.parseMessages(echoFileDescriptor); + TypeNode clientType = + TypeNode.withReference( + VaporReference.builder() + .setName("EchoClient") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode inputType = + TypeNode.withReference( + VaporReference.builder() + .setName("EchoRequest") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode outputType = + TypeNode.withReference( + VaporReference.builder() + .setName("PagedResponse") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + List methodArguments = Collections.emptyList(); + Method method = + Method.builder() + .setName("simplePagedMethod") + .setMethodSignatures(Arrays.asList(methodArguments)) + .setInputType(inputType) + .setOutputType(outputType) + .setIsPaged(true) + .build(); + assertThrows( + NullPointerException.class, + () -> + ServiceClientSampleCodeComposer.composeRpcMethodHeaderSampleCode( + method, clientType, methodArguments, resourceNames, messageTypes)); + } + + @Test + public void invalidComposeRpcMethodHeaderSampleCode_noRepeatedResponseTypeInPagedMethod() { + FileDescriptor echoFileDescriptor = EchoOuterClass.getDescriptor(); + Map resourceNames = Parser.parseResourceNames(echoFileDescriptor); + Map messageTypes = Parser.parseMessages(echoFileDescriptor); + TypeNode clientType = + TypeNode.withReference( + VaporReference.builder() + .setName("EchoClient") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode inputType = + TypeNode.withReference( + VaporReference.builder() + .setName("EchoRequest") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode outputType = + TypeNode.withReference( + VaporReference.builder() + .setName("PagedResponse") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + List methodArguments = Collections.emptyList(); + Method method = + Method.builder() + .setName("simplePagedMethod") + .setMethodSignatures(Arrays.asList(methodArguments)) + .setInputType(inputType) + .setOutputType(outputType) + .setIsPaged(true) + .build(); + Field responseField = + Field.builder() + .setName("response") + .setType( + TypeNode.withReference( + ConcreteReference.builder() + .setClazz(List.class) + .setGenerics(ConcreteReference.withClazz(String.class)) + .build())) + .setIsMessage(true) + .setIsRepeated(false) + .build(); + Field nextPageToken = + Field.builder().setName("next_page_token").setType(TypeNode.STRING).build(); + Message noRepeatedFieldMessage = + Message.builder() + .setName("PagedResponse") + .setType(outputType) + .setFields(Arrays.asList(responseField, nextPageToken)) + .build(); + messageTypes.put("PagedResponse", noRepeatedFieldMessage); + assertThrows( + NullPointerException.class, + () -> + ServiceClientSampleCodeComposer.composeRpcMethodHeaderSampleCode( + method, clientType, methodArguments, resourceNames, messageTypes)); + } + + // =======================================Unary RPC Method Sample Code=======================// @Test public void composeUnaryRpcMethodSampleCode_resourceNameMethodArgument() { FileDescriptor echoFileDescriptor = EchoOuterClass.getDescriptor(); @@ -649,6 +796,129 @@ public void composeUnaryRpcMethodSampleCode_methodReturnVoid() { " String name = \"name3373707\";\n", " echoClient.delete(name);\n", "}"); - Assert.assertEquals(results, expected); + assertEquals(results, expected); + } + + // ===================================Unary Paged RPC Method Sample Code ======================// + @Test + public void composeUnaryPagedRpcMethodSampleCode_multipleMethodArguments() { + FileDescriptor echoFileDescriptor = EchoOuterClass.getDescriptor(); + Map resourceNames = Parser.parseResourceNames(echoFileDescriptor); + TypeNode clientType = + TypeNode.withReference( + VaporReference.builder() + .setName("EchoClient") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode inputType = + TypeNode.withReference( + VaporReference.builder() + .setName("ListContentRequest") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode outputType = + TypeNode.withReference( + VaporReference.builder() + .setName("ListContentResponse") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode resourceNameType = + TypeNode.withReference( + ConcreteReference.builder() + .setClazz(List.class) + .setGenerics(ConcreteReference.withClazz(String.class)) + .build()); + List arguments = + Arrays.asList( + MethodArgument.builder() + .setName("resourceName") + .setType(resourceNameType) + .setField( + Field.builder() + .setName("resourceName") + .setType(resourceNameType) + .setIsRepeated(true) + .build()) + .build(), + MethodArgument.builder() + .setName("filter") + .setType(TypeNode.STRING) + .setField(Field.builder().setName("filter").setType(TypeNode.STRING).build()) + .build()); + Method method = + Method.builder() + .setName("ListContent") + .setMethodSignatures(Arrays.asList(arguments)) + .setInputType(inputType) + .setOutputType(outputType) + .setIsPaged(true) + .build(); + TypeNode repeatedResponseType = + TypeNode.withReference( + VaporReference.builder().setName("Content").setPakkage(SHOWCASE_PACKAGE_NAME).build()); + + String results = + SampleCodeWriter.write( + ServiceClientSampleCodeComposer.composeUnaryPagedRpcMethodSampleCode( + method, clientType, repeatedResponseType, arguments, resourceNames)); + String expected = + LineFormatter.lines( + "try (EchoClient echoClient = EchoClient.create()) {\n", + " List resourceName = new ArrayList<>();\n", + " String filter = \"filter-1274492040\";\n", + " for (Content element : echoClient.listContent(resourceName, filter).iterateAll()) {\n", + " // doThingsWith(element);\n", + " }\n", + "}"); + assertEquals(results, expected); + } + + @Test + public void composeUnaryPagedRpcMethodSampleCode_noMethodArguments() { + FileDescriptor echoFileDescriptor = EchoOuterClass.getDescriptor(); + Map resourceNames = Parser.parseResourceNames(echoFileDescriptor); + TypeNode clientType = + TypeNode.withReference( + VaporReference.builder() + .setName("EchoClient") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode inputType = + TypeNode.withReference( + VaporReference.builder() + .setName("ListContentRequest") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + TypeNode outputType = + TypeNode.withReference( + VaporReference.builder() + .setName("ListContentResponse") + .setPakkage(SHOWCASE_PACKAGE_NAME) + .build()); + List arguments = Collections.emptyList(); + Method method = + Method.builder() + .setName("ListContent") + .setMethodSignatures(Arrays.asList(arguments)) + .setInputType(inputType) + .setOutputType(outputType) + .setIsPaged(true) + .build(); + TypeNode repeatedResponseType = + TypeNode.withReference( + VaporReference.builder().setName("Content").setPakkage(SHOWCASE_PACKAGE_NAME).build()); + + String results = + SampleCodeWriter.write( + ServiceClientSampleCodeComposer.composeUnaryPagedRpcMethodSampleCode( + method, clientType, repeatedResponseType, arguments, resourceNames)); + String expected = + LineFormatter.lines( + "try (EchoClient echoClient = EchoClient.create()) {\n", + " for (Content element : echoClient.listContent().iterateAll()) {\n", + " // doThingsWith(element);\n", + " }\n", + "}"); + assertEquals(results, expected); } } diff --git a/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden b/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden index d0557f887a..69a21d3a3d 100644 --- a/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden +++ b/src/test/java/com/google/api/generator/gapic/composer/goldens/EchoClient.golden @@ -361,6 +361,16 @@ public class EchoClient implements BackgroundResource { // AUTO-GENERATED DOCUMENTATION AND METHOD. /** + * Sample code: + * + *
{@code
+   * try (EchoClient echoClient = EchoClient.create()) {
+   *   for (EchoResponse element : echoClient.simplePagedExpand().iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param request The request object containing all of the parameters for the API call. * @throws com.google.api.gax.rpc.ApiException if the remote call fails */ diff --git a/test/integration/goldens/asset/AssetServiceClient.java b/test/integration/goldens/asset/AssetServiceClient.java index bbe91cd308..ce97a13c41 100644 --- a/test/integration/goldens/asset/AssetServiceClient.java +++ b/test/integration/goldens/asset/AssetServiceClient.java @@ -516,6 +516,20 @@ public final UnaryCallable deleteFeedCallable() { * organization. The caller must be granted the `cloudasset.assets.searchAllResources` permission * on the desired scope, otherwise the request will be rejected. * + *

Sample code: + * + *

{@code
+   * try (AssetServiceClient assetServiceClient = AssetServiceClient.create()) {
+   *   String scope = "scope109264468";
+   *   String query = "query107944136";
+   *   List assetTypes = new ArrayList<>();
+   *   for (ResourceSearchResult element :
+   *       assetServiceClient.searchAllResources(scope, query, assetTypes).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param scope Required. A scope can be a project, a folder, or an organization. The search is * limited to the resources within the `scope`. The caller must be granted the * [`cloudasset.assets.searchAllResources`](http://cloud.google.com/asset-inventory/docs/access-control#required_permissions) @@ -622,6 +636,19 @@ public final SearchAllResourcesPagedResponse searchAllResources( * organization. The caller must be granted the `cloudasset.assets.searchAllIamPolicies` * permission on the desired scope, otherwise the request will be rejected. * + *

Sample code: + * + *

{@code
+   * try (AssetServiceClient assetServiceClient = AssetServiceClient.create()) {
+   *   String scope = "scope109264468";
+   *   String query = "query107944136";
+   *   for (IamPolicySearchResult element :
+   *       assetServiceClient.searchAllIamPolicies(scope, query).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param scope Required. A scope can be a project, a folder, or an organization. The search is * limited to the IAM policies within the `scope`. The caller must be granted the * [`cloudasset.assets.searchAllIamPolicies`](http://cloud.google.com/asset-inventory/docs/access-control#required_permissions) diff --git a/test/integration/goldens/library/LibraryServiceClient.java b/test/integration/goldens/library/LibraryServiceClient.java index 786c7324a7..ea2d0df8b3 100644 --- a/test/integration/goldens/library/LibraryServiceClient.java +++ b/test/integration/goldens/library/LibraryServiceClient.java @@ -668,6 +668,17 @@ public final UnaryCallable getBookCallable() { * not necessarily be added to the end of this list. Returns NOT_FOUND if the shelf does not * exist. * + *

Sample code: + * + *

{@code
+   * try (LibraryServiceClient libraryServiceClient = LibraryServiceClient.create()) {
+   *   ShelfName name = ShelfName.of("[SHELF_ID]");
+   *   for (Book element : libraryServiceClient.listBooks(name).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param name The name of the shelf whose books we'd like to list. * @throws com.google.api.gax.rpc.ApiException if the remote call fails */ @@ -683,6 +694,17 @@ public final ListBooksPagedResponse listBooks(ShelfName name) { * not necessarily be added to the end of this list. Returns NOT_FOUND if the shelf does not * exist. * + *

Sample code: + * + *

{@code
+   * try (LibraryServiceClient libraryServiceClient = LibraryServiceClient.create()) {
+   *   String name = "name3373707";
+   *   for (Book element : libraryServiceClient.listBooks(name).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param name The name of the shelf whose books we'd like to list. * @throws com.google.api.gax.rpc.ApiException if the remote call fails */ diff --git a/test/integration/goldens/logging/ConfigClient.java b/test/integration/goldens/logging/ConfigClient.java index f213970602..75930c33de 100644 --- a/test/integration/goldens/logging/ConfigClient.java +++ b/test/integration/goldens/logging/ConfigClient.java @@ -176,6 +176,18 @@ public ConfigServiceV2Stub getStub() { /** * Lists buckets (Beta). * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   BillingAccountLocationName parent =
+   *       BillingAccountLocationName.of("[BILLING_ACCOUNT]", "[LOCATION]");
+   *   for (LogBucket element : configClient.listBuckets(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose buckets are to be listed: *

"projects/[PROJECT_ID]/locations/[LOCATION_ID]" * "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]" @@ -197,6 +209,17 @@ public final ListBucketsPagedResponse listBuckets(BillingAccountLocationName par /** * Lists buckets (Beta). * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   FolderLocationName parent = FolderLocationName.of("[FOLDER]", "[LOCATION]");
+   *   for (LogBucket element : configClient.listBuckets(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose buckets are to be listed: *

"projects/[PROJECT_ID]/locations/[LOCATION_ID]" * "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]" @@ -218,6 +241,17 @@ public final ListBucketsPagedResponse listBuckets(FolderLocationName parent) { /** * Lists buckets (Beta). * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   LocationName parent = LocationName.of("[PROJECT]", "[LOCATION]");
+   *   for (LogBucket element : configClient.listBuckets(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose buckets are to be listed: *

"projects/[PROJECT_ID]/locations/[LOCATION_ID]" * "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]" @@ -239,6 +273,17 @@ public final ListBucketsPagedResponse listBuckets(LocationName parent) { /** * Lists buckets (Beta). * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   OrganizationLocationName parent = OrganizationLocationName.of("[ORGANIZATION]", "[LOCATION]");
+   *   for (LogBucket element : configClient.listBuckets(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose buckets are to be listed: *

"projects/[PROJECT_ID]/locations/[LOCATION_ID]" * "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]" @@ -260,6 +305,19 @@ public final ListBucketsPagedResponse listBuckets(OrganizationLocationName paren /** * Lists buckets (Beta). * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   String parent =
+   *       LogBucketName.ofProjectLocationBucketName("[PROJECT]", "[LOCATION]", "[BUCKET]")
+   *           .toString();
+   *   for (LogBucket element : configClient.listBuckets(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose buckets are to be listed: *

"projects/[PROJECT_ID]/locations/[LOCATION_ID]" * "organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]" @@ -370,6 +428,17 @@ public final UnaryCallable updateBucketCallable( /** * Lists sinks. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   BillingAccountName parent = BillingAccountName.of("[BILLING_ACCOUNT]");
+   *   for (LogSink element : configClient.listSinks(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose sinks are to be listed: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -385,6 +454,17 @@ public final ListSinksPagedResponse listSinks(BillingAccountName parent) { /** * Lists sinks. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   FolderName parent = FolderName.of("[FOLDER]");
+   *   for (LogSink element : configClient.listSinks(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose sinks are to be listed: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -400,6 +480,17 @@ public final ListSinksPagedResponse listSinks(FolderName parent) { /** * Lists sinks. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   OrganizationName parent = OrganizationName.of("[ORGANIZATION]");
+   *   for (LogSink element : configClient.listSinks(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose sinks are to be listed: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -415,6 +506,17 @@ public final ListSinksPagedResponse listSinks(OrganizationName parent) { /** * Lists sinks. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   ProjectName parent = ProjectName.of("[PROJECT]");
+   *   for (LogSink element : configClient.listSinks(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose sinks are to be listed: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -430,6 +532,17 @@ public final ListSinksPagedResponse listSinks(ProjectName parent) { /** * Lists sinks. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   String parent = LogSinkName.ofProjectSinkName("[PROJECT]", "[SINK]").toString();
+   *   for (LogSink element : configClient.listSinks(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose sinks are to be listed: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -1027,6 +1140,17 @@ public final UnaryCallable deleteSinkCallable() { /** * Lists all the exclusions in a parent resource. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   BillingAccountName parent = BillingAccountName.of("[BILLING_ACCOUNT]");
+   *   for (LogExclusion element : configClient.listExclusions(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose exclusions are to be listed. *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -1044,6 +1168,17 @@ public final ListExclusionsPagedResponse listExclusions(BillingAccountName paren /** * Lists all the exclusions in a parent resource. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   FolderName parent = FolderName.of("[FOLDER]");
+   *   for (LogExclusion element : configClient.listExclusions(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose exclusions are to be listed. *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -1061,6 +1196,17 @@ public final ListExclusionsPagedResponse listExclusions(FolderName parent) { /** * Lists all the exclusions in a parent resource. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   OrganizationName parent = OrganizationName.of("[ORGANIZATION]");
+   *   for (LogExclusion element : configClient.listExclusions(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose exclusions are to be listed. *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -1078,6 +1224,17 @@ public final ListExclusionsPagedResponse listExclusions(OrganizationName parent) /** * Lists all the exclusions in a parent resource. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   ProjectName parent = ProjectName.of("[PROJECT]");
+   *   for (LogExclusion element : configClient.listExclusions(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose exclusions are to be listed. *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -1095,6 +1252,18 @@ public final ListExclusionsPagedResponse listExclusions(ProjectName parent) { /** * Lists all the exclusions in a parent resource. * + *

Sample code: + * + *

{@code
+   * try (ConfigClient configClient = ConfigClient.create()) {
+   *   String parent =
+   *       LogExclusionName.ofProjectExclusionName("[PROJECT]", "[EXCLUSION]").toString();
+   *   for (LogExclusion element : configClient.listExclusions(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The parent resource whose exclusions are to be listed. *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" diff --git a/test/integration/goldens/logging/LoggingClient.java b/test/integration/goldens/logging/LoggingClient.java index ba60b27852..c893af954a 100644 --- a/test/integration/goldens/logging/LoggingClient.java +++ b/test/integration/goldens/logging/LoggingClient.java @@ -425,6 +425,20 @@ public final WriteLogEntriesResponse writeLogEntries(WriteLogEntriesRequest requ * project/folder/organization/billing account. For ways to export log entries, see [Exporting * Logs](https://cloud.google.com/logging/docs/export). * + *

Sample code: + * + *

{@code
+   * try (LoggingClient loggingClient = LoggingClient.create()) {
+   *   List resourceNames = new ArrayList<>();
+   *   String filter = "filter-1274492040";
+   *   String orderBy = "orderBy-1207110587";
+   *   for (LogEntry element :
+   *       loggingClient.listLogEntries(resourceNames, filter, orderBy).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param resourceNames Required. Names of one or more parent resources from which to retrieve log * entries: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" @@ -534,6 +548,17 @@ public final ListMonitoredResourceDescriptorsPagedResponse listMonitoredResource * Lists the logs in projects, organizations, folders, or billing accounts. Only logs that have * entries are listed. * + *

Sample code: + * + *

{@code
+   * try (LoggingClient loggingClient = LoggingClient.create()) {
+   *   BillingAccountName parent = BillingAccountName.of("[BILLING_ACCOUNT]");
+   *   for (String element : loggingClient.listLogs(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The resource name that owns the logs: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -550,6 +575,17 @@ public final ListLogsPagedResponse listLogs(BillingAccountName parent) { * Lists the logs in projects, organizations, folders, or billing accounts. Only logs that have * entries are listed. * + *

Sample code: + * + *

{@code
+   * try (LoggingClient loggingClient = LoggingClient.create()) {
+   *   FolderName parent = FolderName.of("[FOLDER]");
+   *   for (String element : loggingClient.listLogs(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The resource name that owns the logs: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -566,6 +602,17 @@ public final ListLogsPagedResponse listLogs(FolderName parent) { * Lists the logs in projects, organizations, folders, or billing accounts. Only logs that have * entries are listed. * + *

Sample code: + * + *

{@code
+   * try (LoggingClient loggingClient = LoggingClient.create()) {
+   *   OrganizationName parent = OrganizationName.of("[ORGANIZATION]");
+   *   for (String element : loggingClient.listLogs(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The resource name that owns the logs: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -582,6 +629,17 @@ public final ListLogsPagedResponse listLogs(OrganizationName parent) { * Lists the logs in projects, organizations, folders, or billing accounts. Only logs that have * entries are listed. * + *

Sample code: + * + *

{@code
+   * try (LoggingClient loggingClient = LoggingClient.create()) {
+   *   ProjectName parent = ProjectName.of("[PROJECT]");
+   *   for (String element : loggingClient.listLogs(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The resource name that owns the logs: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" @@ -598,6 +656,17 @@ public final ListLogsPagedResponse listLogs(ProjectName parent) { * Lists the logs in projects, organizations, folders, or billing accounts. Only logs that have * entries are listed. * + *

Sample code: + * + *

{@code
+   * try (LoggingClient loggingClient = LoggingClient.create()) {
+   *   String parent = LogName.ofProjectLogName("[PROJECT]", "[LOG]").toString();
+   *   for (String element : loggingClient.listLogs(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The resource name that owns the logs: *

"projects/[PROJECT_ID]" "organizations/[ORGANIZATION_ID]" * "billingAccounts/[BILLING_ACCOUNT_ID]" "folders/[FOLDER_ID]" diff --git a/test/integration/goldens/logging/MetricsClient.java b/test/integration/goldens/logging/MetricsClient.java index 283f4d1d5b..e63a29ac2e 100644 --- a/test/integration/goldens/logging/MetricsClient.java +++ b/test/integration/goldens/logging/MetricsClient.java @@ -152,6 +152,17 @@ public MetricsServiceV2Stub getStub() { /** * Lists logs-based metrics. * + *

Sample code: + * + *

{@code
+   * try (MetricsClient metricsClient = MetricsClient.create()) {
+   *   ProjectName parent = ProjectName.of("[PROJECT]");
+   *   for (LogMetric element : metricsClient.listLogMetrics(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The name of the project containing the metrics: *

"projects/[PROJECT_ID]" * @throws com.google.api.gax.rpc.ApiException if the remote call fails @@ -168,6 +179,17 @@ public final ListLogMetricsPagedResponse listLogMetrics(ProjectName parent) { /** * Lists logs-based metrics. * + *

Sample code: + * + *

{@code
+   * try (MetricsClient metricsClient = MetricsClient.create()) {
+   *   String parent = ProjectName.of("[PROJECT]").toString();
+   *   for (LogMetric element : metricsClient.listLogMetrics(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The name of the project containing the metrics: *

"projects/[PROJECT_ID]" * @throws com.google.api.gax.rpc.ApiException if the remote call fails diff --git a/test/integration/goldens/redis/CloudRedisClient.java b/test/integration/goldens/redis/CloudRedisClient.java index 2acd1c94f5..b128a022e0 100644 --- a/test/integration/goldens/redis/CloudRedisClient.java +++ b/test/integration/goldens/redis/CloudRedisClient.java @@ -189,6 +189,17 @@ public final OperationsClient getOperationsClient() { *

If `location_id` is specified as `-` (wildcard), then all regions available to the project * are queried, and the results are aggregated. * + *

Sample code: + * + *

{@code
+   * try (CloudRedisClient cloudRedisClient = CloudRedisClient.create()) {
+   *   LocationName parent = LocationName.of("[PROJECT]", "[LOCATION]");
+   *   for (Instance element : cloudRedisClient.listInstances(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The resource name of the instance location using the form: * `projects/{project_id}/locations/{location_id}` where `location_id` refers to a GCP region. * @throws com.google.api.gax.rpc.ApiException if the remote call fails @@ -215,6 +226,17 @@ public final ListInstancesPagedResponse listInstances(LocationName parent) { *

If `location_id` is specified as `-` (wildcard), then all regions available to the project * are queried, and the results are aggregated. * + *

Sample code: + * + *

{@code
+   * try (CloudRedisClient cloudRedisClient = CloudRedisClient.create()) {
+   *   String parent = LocationName.of("[PROJECT]", "[LOCATION]").toString();
+   *   for (Instance element : cloudRedisClient.listInstances(parent).iterateAll()) {
+   *     // doThingsWith(element);
+   *   }
+   * }
+   * }
+ * * @param parent Required. The resource name of the instance location using the form: * `projects/{project_id}/locations/{location_id}` where `location_id` refers to a GCP region. * @throws com.google.api.gax.rpc.ApiException if the remote call fails