feat: update generated samples to executable format

src/main/java/com/google/api/generator/engine/writer/ImportWriterVisitor.java

@@ -60,7 +60,6 @@
 import com.google.api.generator.engine.ast.VaporReference;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.engine.ast.WhileStatement;
-import com.google.common.base.Preconditions;
 import com.google.common.base.Strings;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -359,11 +358,6 @@ public void visit(TryCatchStatement tryCatchStatement) {
     }
 
     statements(tryCatchStatement.tryBody());
-
-    Preconditions.checkState(
-        !tryCatchStatement.isSampleCode() && !tryCatchStatement.catchVariableExprs().isEmpty(),
-        "Import generation should not be invoked on sample code, but was found when visiting a"
-            + " try-catch block");
     for (int i = 0; i < tryCatchStatement.catchVariableExprs().size(); i++) {
       tryCatchStatement.catchVariableExprs().get(i).accept(this);
       statements(tryCatchStatement.catchBlocks().get(i));

src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceClientClassComposer.java

@@ -55,6 +55,7 @@
 import com.google.api.generator.engine.ast.Variable;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.gapic.composer.comment.ServiceClientCommentComposer;
+import com.google.api.generator.gapic.composer.samplecode.ExecutableSampleComposer;
 import com.google.api.generator.gapic.composer.samplecode.ServiceClientSampleCodeComposer;
 import com.google.api.generator.gapic.composer.store.TypeStore;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
@@ -99,6 +100,8 @@
 import java.util.stream.Collectors;
 import javax.annotation.Generated;
 
+import static com.google.api.generator.gapic.composer.samplecode.ExecutableSampleComposer.createExecutableSample;
+
 public abstract class AbstractServiceClientClassComposer implements ClassComposer {
   private static final String PAGED_RESPONSE_TYPE_NAME_PATTERN = "%sPagedResponse";
   private static final String CALLABLE_NAME_PATTERN = "%sCallable";
@@ -192,11 +195,11 @@ private static List<CommentStatement> createClassHeaderComments(
         ServiceClientSampleCodeComposer.composeClassHeaderMethodSampleCode(
             service, clientType, resourceNames, messageTypes);
     String credentialsSampleCode =
-        ServiceClientSampleCodeComposer.composeClassHeaderCredentialsSampleCode(
-            clientType, settingsType);
+        createExecutableSample(ServiceClientSampleCodeComposer.composeClassHeaderCredentialsSampleCode(
+            clientType, settingsType));
     String endpointSampleCode =
-        ServiceClientSampleCodeComposer.composeClassHeaderEndpointSampleCode(
-            clientType, settingsType);
+        createExecutableSample(ServiceClientSampleCodeComposer.composeClassHeaderEndpointSampleCode(
+            clientType, settingsType));
     return ServiceClientCommentComposer.createClassHeaderComments(
         service, classMethodSampleCode, credentialsSampleCode, endpointSampleCode);
   }
@@ -697,8 +700,8 @@ private static List<MethodDefinition> createMethodVariants(
 
       Optional<String> methodSampleCode =
           Optional.of(
-              ServiceClientSampleCodeComposer.composeRpcMethodHeaderSampleCode(
-                  method, typeStore.get(clientName), signature, resourceNames, messageTypes));
+              createExecutableSample(ServiceClientSampleCodeComposer.composeRpcMethodHeaderSampleCode(
+                  method, typeStore.get(clientName), signature, resourceNames, messageTypes)));
       MethodDefinition.Builder methodVariantBuilder =
           MethodDefinition.builder()
               .setHeaderCommentStatements(
@@ -777,8 +780,8 @@ private static MethodDefinition createMethodDefaultMethod(
 
     Optional<String> defaultMethodSampleCode =
         Optional.of(
-            ServiceClientSampleCodeComposer.composeRpcDefaultMethodHeaderSampleCode(
-                method, typeStore.get(clientName), resourceNames, messageTypes));
+            createExecutableSample(ServiceClientSampleCodeComposer.composeRpcDefaultMethodHeaderSampleCode(
+                method, typeStore.get(clientName), resourceNames, messageTypes)));
 
     MethodInvocationExpr callableMethodExpr =
         MethodInvocationExpr.builder().setMethodName(callableMethodName).build();
@@ -900,36 +903,36 @@ private static MethodDefinition createCallableMethod(
     if (callableMethodKind.equals(CallableMethodKind.LRO)) {
       sampleCodeOpt =
           Optional.of(
-              ServiceClientSampleCodeComposer.composeLroCallableMethodHeaderSampleCode(
+                  createExecutableSample(ServiceClientSampleCodeComposer.composeLroCallableMethodHeaderSampleCode(
                   method,
                   typeStore.get(ClassNames.getServiceClientClassName(service)),
                   resourceNames,
-                  messageTypes));
+                  messageTypes)));
     } else if (callableMethodKind.equals(CallableMethodKind.PAGED)) {
       sampleCodeOpt =
           Optional.of(
-              ServiceClientSampleCodeComposer.composePagedCallableMethodHeaderSampleCode(
+              createExecutableSample(ServiceClientSampleCodeComposer.composePagedCallableMethodHeaderSampleCode(
                   method,
                   typeStore.get(ClassNames.getServiceClientClassName(service)),
                   resourceNames,
-                  messageTypes));
+                  messageTypes)));
     } else if (callableMethodKind.equals(CallableMethodKind.REGULAR)) {
       if (method.stream().equals(Stream.NONE)) {
         sampleCodeOpt =
             Optional.of(
-                ServiceClientSampleCodeComposer.composeRegularCallableMethodHeaderSampleCode(
+                createExecutableSample(ServiceClientSampleCodeComposer.composeRegularCallableMethodHeaderSampleCode(
                     method,
                     typeStore.get(ClassNames.getServiceClientClassName(service)),
                     resourceNames,
-                    messageTypes));
+                    messageTypes)));
       } else {
         sampleCodeOpt =
             Optional.of(
-                ServiceClientSampleCodeComposer.composeStreamCallableMethodHeaderSampleCode(
+                    createExecutableSample(ServiceClientSampleCodeComposer.composeStreamCallableMethodHeaderSampleCode(
                     method,
                     typeStore.get(ClassNames.getServiceClientClassName(service)),
                     resourceNames,
-                    messageTypes));
+                    messageTypes)));
       }
     }
 

src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceSettingsClassComposer.java

@@ -50,6 +50,8 @@
 import com.google.api.generator.engine.ast.Variable;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.gapic.composer.comment.SettingsCommentComposer;
+import com.google.api.generator.gapic.composer.samplecode.ExecutableSample;
+import com.google.api.generator.gapic.composer.samplecode.ExecutableSampleComposer;
 import com.google.api.generator.gapic.composer.samplecode.SettingsSampleCodeComposer;
 import com.google.api.generator.gapic.composer.store.TypeStore;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
@@ -140,8 +142,8 @@ private static List<CommentStatement> createClassHeaderComments(
     Optional<String> methodNameOpt =
         methodOpt.isPresent() ? Optional.of(methodOpt.get().name()) : Optional.empty();
     Optional<String> sampleCodeOpt =
-        SettingsSampleCodeComposer.composeSampleCode(
-            methodNameOpt, ClassNames.getServiceSettingsClassName(service), classType);
+            ExecutableSampleComposer.createExecutableSample(SettingsSampleCodeComposer.composeSampleCode(
+            methodNameOpt, ClassNames.getServiceSettingsClassName(service), classType));
     return SettingsCommentComposer.createClassHeaderComments(
         ClassNames.getServiceClientClassName(service),
         service.defaultHost(),

src/main/java/com/google/api/generator/gapic/composer/common/AbstractServiceStubSettingsClassComposer.java

@@ -79,6 +79,8 @@
 import com.google.api.generator.engine.ast.Variable;
 import com.google.api.generator.engine.ast.VariableExpr;
 import com.google.api.generator.gapic.composer.comment.SettingsCommentComposer;
+import com.google.api.generator.gapic.composer.samplecode.ExecutableSample;
+import com.google.api.generator.gapic.composer.samplecode.ExecutableSampleComposer;
 import com.google.api.generator.gapic.composer.samplecode.SettingsSampleCodeComposer;
 import com.google.api.generator.gapic.composer.store.TypeStore;
 import com.google.api.generator.gapic.composer.utils.ClassNames;
@@ -390,8 +392,8 @@ private static List<CommentStatement> createClassHeaderComments(
     Optional<String> methodNameOpt =
         methodOpt.isPresent() ? Optional.of(methodOpt.get().name()) : Optional.empty();
     Optional<String> sampleCodeOpt =
-        SettingsSampleCodeComposer.composeSampleCode(
-            methodNameOpt, ClassNames.getServiceSettingsClassName(service), classType);
+            ExecutableSampleComposer.createExecutableSample(SettingsSampleCodeComposer.composeSampleCode(
+            methodNameOpt, ClassNames.getServiceSettingsClassName(service), classType));
 
     return SettingsCommentComposer.createClassHeaderComments(
         ClassNames.getServiceStubClassName(service),

src/main/java/com/google/api/generator/gapic/composer/samplecode/ExecutableSample.java

@@ -0,0 +1,46 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.api.generator.gapic.composer.samplecode;
+
+import com.google.api.generator.engine.ast.AssignmentExpr;
+import com.google.api.generator.engine.ast.Statement;
+import java.util.List;
+
+public class ExecutableSample {
+  private final String sampleName;
+  private final List<AssignmentExpr> sampleVariableAssignments;
+  private final List<Statement> sampleBody;
+
+  public ExecutableSample(
+      String sampleName,
+      List<AssignmentExpr> sampleVariableAssignments,
+      List<Statement> sampleBody) {
+    this.sampleName = sampleName;
+    this.sampleVariableAssignments = sampleVariableAssignments;
+    this.sampleBody = sampleBody;
+  }
+
+  public String getSampleName() {
+    return sampleName;
+  }
+
+  public List<AssignmentExpr> getSampleVariableAssignments() {
+    return sampleVariableAssignments;
+  }
+
+  public List<Statement> getSampleBody() {
+    return sampleBody;
+  }
+}

src/main/java/com/google/api/generator/gapic/composer/samplecode/ExecutableSampleComposer.java

@@ -0,0 +1,142 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.api.generator.gapic.composer.samplecode;
+
+import com.google.api.generator.engine.ast.AssignmentExpr;
+import com.google.api.generator.engine.ast.ClassDefinition;
+import com.google.api.generator.engine.ast.Expr;
+import com.google.api.generator.engine.ast.ExprStatement;
+import com.google.api.generator.engine.ast.MethodDefinition;
+import com.google.api.generator.engine.ast.MethodInvocationExpr;
+import com.google.api.generator.engine.ast.ScopeNode;
+import com.google.api.generator.engine.ast.Statement;
+import com.google.api.generator.engine.ast.TypeNode;
+import com.google.api.generator.engine.ast.Variable;
+import com.google.api.generator.engine.ast.VariableExpr;
+import com.google.api.generator.gapic.utils.JavaStyle;
+import com.google.common.collect.ImmutableList;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Optional;
+import java.util.stream.Collectors;
+
+public class ExecutableSampleComposer {
+  public static Optional<String> createExecutableSample(
+      Optional<ExecutableSample> executableSample) {
+    if (executableSample.isPresent()) {
+      return Optional.of(createExecutableSample(executableSample.get()));
+    }
+    return Optional.empty();
+  }
+
+  public static String createExecutableSample(ExecutableSample executableSample) {
+    String sampleMethodName = JavaStyle.toLowerCamelCase(executableSample.getSampleName());
+    return SampleCodeWriter.write(
+        composeExecutableSample(
+            sampleMethodName,
+            executableSample.getSampleVariableAssignments(),
+            executableSample.getSampleBody()));
+  }
+
+  private static ClassDefinition composeExecutableSample(
+      String sampleMethodName,
+      List<AssignmentExpr> sampleVariableAssignments,
+      List<Statement> sampleBody) {
+    String sampleClassName = JavaStyle.toUpperCamelCase(sampleMethodName);
+    List<VariableExpr> sampleMethodArgs = composeSampleMethodArgs(sampleVariableAssignments);
+    MethodDefinition mainMethod =
+        composeMainMethod(
+            composeMainBody(
+                sampleVariableAssignments,
+                composeInvokeMethodStatement(sampleMethodName, sampleMethodArgs)));
+    MethodDefinition sampleMethod =
+        composeSampleMethod(sampleMethodName, sampleMethodArgs, sampleBody);
+    return composeSampleClass(sampleClassName, mainMethod, sampleMethod);
+  }
+
+  private static List<VariableExpr> composeSampleMethodArgs(
+      List<AssignmentExpr> sampleVariableAssignments) {
+    return sampleVariableAssignments.stream()
+        .map(v -> v.variableExpr().toBuilder().setIsDecl(true).build())
+        .collect(Collectors.toList());
+  }
+
+  private static Statement composeInvokeMethodStatement(
+      String sampleMethodName, List<VariableExpr> sampleMethodArgs) {
+    List<Expr> invokeArgs =
+        sampleMethodArgs.stream()
+            .map(arg -> arg.toBuilder().setIsDecl(false).build())
+            .collect(Collectors.toList());
+    return ExprStatement.withExpr(
+        MethodInvocationExpr.builder()
+            .setMethodName(sampleMethodName)
+            .setArguments(invokeArgs)
+            .build());
+  }
+
+  private static List<Statement> composeMainBody(
+      List<AssignmentExpr> sampleVariableAssignments, Statement invokeMethod) {
+    List<ExprStatement> setVariables =
+        sampleVariableAssignments.stream()
+            .map(var -> ExprStatement.withExpr(var))
+            .collect(Collectors.toList());
+    List<Statement> body = new ArrayList<>(setVariables);
+    body.add(invokeMethod);
+    return body;
+  }
+
+  private static ClassDefinition composeSampleClass(
+      String sampleClassName, MethodDefinition mainMethod, MethodDefinition sampleMethod) {
+    return ClassDefinition.builder()
+        .setScope(ScopeNode.PUBLIC)
+        .setPackageString("com.google.example")
+        .setName(sampleClassName)
+        .setMethods(ImmutableList.of(mainMethod, sampleMethod))
+        .build();
+  }
+
+  private static MethodDefinition composeMainMethod(List<Statement> mainBody) {
+    return MethodDefinition.builder()
+        .setScope(ScopeNode.PUBLIC)
+        .setIsStatic(true)
+        .setReturnType(TypeNode.VOID)
+        .setName("main")
+        .setArguments(
+            VariableExpr.builder()
+                .setVariable(
+                    Variable.builder().setType(TypeNode.STRING_ARRAY).setName("args").build())
+                .setIsDecl(true)
+                .build())
+        .setThrowsExceptions(Arrays.asList(TypeNode.withExceptionClazz(Exception.class)))
+        .setBody(mainBody)
+        .build();
+  }
+
+  private static MethodDefinition composeSampleMethod(
+      String sampleMethodName,
+      List<VariableExpr> sampleMethodArgs,
+      List<Statement> sampleMethodBody) {
+    return MethodDefinition.builder()
+        .setScope(ScopeNode.PUBLIC)
+        .setIsStatic(true)
+        .setReturnType(TypeNode.VOID)
+        .setName(sampleMethodName)
+        .setArguments(sampleMethodArgs)
+        .setThrowsExceptions(Arrays.asList(TypeNode.withExceptionClazz(Exception.class)))
+        .setBody(sampleMethodBody)
+        .build();
+  }
+}

src/main/java/com/google/api/generator/gapic/composer/samplecode/SampleCodeWriter.java

@@ -14,6 +14,8 @@
 
 package com.google.api.generator.gapic.composer.samplecode;
 
+import com.google.api.generator.engine.ast.ClassDefinition;
+import com.google.api.generator.engine.ast.MethodInvocationExpr;
 import com.google.api.generator.engine.ast.Statement;
 import com.google.api.generator.engine.writer.JavaWriterVisitor;
 import java.util.Arrays;
@@ -34,4 +36,18 @@ public static String write(List<Statement> statements) {
     // Escape character "@" in the markdown code block <pre>{@code...} tags.
     return formattedSampleCode.replaceAll("@", "{@literal @}");
   }
+
+  public static String write(ClassDefinition classDefinition) {
+    JavaWriterVisitor visitor = new JavaWriterVisitor();
+    classDefinition.accept(visitor);
+    // Escape character "@" in the markdown code block <pre>{@code...} tags.
+    return visitor.write().replaceAll("@", "{@literal @}");
+  }
+
+  public static String write(MethodInvocationExpr methodInvocationExpr) {
+    JavaWriterVisitor visitor = new JavaWriterVisitor();
+    methodInvocationExpr.accept(visitor);
+    // Escape character "@" in the markdown code block <pre>{@code...} tags.
+    return visitor.write();
+  }
 }