feat(generator): introduce HttpJsonDescriptorComposer and add path prefix support

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/ServiceClientCommentComposer.java

@@ -33,13 +33,19 @@
 import java.util.Optional;
 import java.util.stream.Collectors;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 @NullMarked
 public class ServiceClientCommentComposer {
   // Tokens.
   private static final String EMPTY_STRING = "";
   private static final String API_EXCEPTION_TYPE_NAME = "com.google.api.gax.rpc.ApiException";
   private static final String EXCEPTION_CONDITION = "if the remote call fails";
+  private static final String REQUEST_PARAM_NAME = "request";
+  private static final String REQUEST_PARAM_DESCRIPTION =
+      "The request object containing all of the parameters for the API call.";
+  private static final String PAYLOAD_PARAM_NAME = "payload";
+  private static final String PAYLOAD_PARAM_DESCRIPTION = "The payload data stream to upload.";
 
   // Constants.
   private static final String SERVICE_DESCRIPTION_INTRO_STRING =
@@ -93,6 +99,11 @@ public class ServiceClientCommentComposer {
           + " that it is easy to make a subclass, but otherwise, the static factory methods"
           + " should be preferred.";
 
+  private static final String RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING =
+      "Call context overrides (such as withTimeout, withRetrySettings, or credentials) apply"
+          + " strictly to the start request (session initiation). Per-chunk PUT calls rely on"
+          + " the configured timeout and retry settings from ResumableUploadCallSettings.";
+
   // Comments.
   public static final CommentStatement GET_OPERATIONS_CLIENT_METHOD_COMMENT =
       toSimpleComment(
@@ -105,9 +116,9 @@ public static List<CommentStatement> createClassHeaderComments(
       String classMethodSampleCode,
       String credentialsSampleCode,
       String endpointSampleCode,
-      String transportSampleCode,
-      String primaryTransport,
-      String secondaryTransport) {
+      @Nullable String transportSampleCode,
+      @Nullable String primaryTransport,
+      @Nullable String secondaryTransport) {
     JavaDocComment.Builder classHeaderJavadocBuilder = JavaDocComment.builder();
     if (service.hasDescription()) {
       String descriptionComment =
@@ -187,14 +198,17 @@ public static List<CommentStatement> createRpcMethodHeaderComment(
       methodJavadocBuilder = methodJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
-    if (sampleCodeOpt.isPresent()) {
+    if (method.isResumableUpload()) {
+      methodJavadocBuilder.addParagraph(RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING);
+    }
+
+    if (sampleCodeOpt.isPresent() && !method.isResumableUpload()) {
       methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
       methodJavadocBuilder.addSampleCode(sampleCodeOpt.get());
     }
 
     if (methodArguments.isEmpty()) {
-      methodJavadocBuilder.addParam(
-          "request", "The request object containing all of the parameters for the API call.");
+      methodJavadocBuilder.addParam(REQUEST_PARAM_NAME, REQUEST_PARAM_DESCRIPTION);
     } else {
       for (MethodArgument argument : methodArguments) {
         // TODO(miraleung): Remove the newline replacement when we support CommonMark.
@@ -204,6 +218,10 @@ public static List<CommentStatement> createRpcMethodHeaderComment(
       }
     }
 
+    if (method.isResumableUpload()) {
+      methodJavadocBuilder.addParam(PAYLOAD_PARAM_NAME, PAYLOAD_PARAM_DESCRIPTION);
+    }
+
     methodJavadocBuilder.setThrows(API_EXCEPTION_TYPE_NAME, EXCEPTION_CONDITION);
 
     if (method.isDeprecated()) {
@@ -348,8 +366,12 @@ public static List<CommentStatement> createRpcCallableMethodHeaderComment(
       methodJavadocBuilder = methodJavadocBuilder.addUnescapedComment(descriptionComment);
     }
 
-    methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
-    if (sampleCodeOpt.isPresent()) {
+    if (method.isResumableUpload()) {
+      methodJavadocBuilder.addParagraph(RESUMABLE_UPLOAD_CALL_CONTEXT_WARNING);
+    }
+
+    if (sampleCodeOpt.isPresent() && !method.isResumableUpload()) {
+      methodJavadocBuilder.addParagraph(METHOD_DESCRIPTION_SAMPLE_CODE_SUMMARY_STRING);
       methodJavadocBuilder.addSampleCode(sampleCodeOpt.get());
     }
 

sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/composer/comment/SettingsCommentComposer.java

@@ -130,6 +130,16 @@ public static CommentStatement createCallSettingsGetterComment(
         isMethodInternal);
   }
 
+  private static final String RESUMABLE_UPLOAD_CALL_SETTINGS_DOC_NOTE =
+      "Note that custom retry settings and headers configured via ApiCallContext"
+          + " apply strictly to the initial session initiation request.";
+
+  public static CommentStatement createResumableUploadCallSettingsGetterComment(
+      String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
+    return createResumableUploadCallSettingsComment(
+        CALL_SETTINGS_METHOD_DOC_PATTERN, javaMethodName, isMethodDeprecated, isMethodInternal);
+  }
+
   public static CommentStatement createBuilderClassComment(String outerClassName) {
     return toCommentStatement(String.format(BUILDER_CLASS_DOC_PATTERN, outerClassName));
   }
@@ -140,6 +150,30 @@ public static CommentStatement createCallSettingsBuilderGetterComment(
     return toCommentStatement(methodComment, isMethodDeprecated, isMethodInternal);
   }
 
+  public static CommentStatement createResumableUploadCallSettingsBuilderGetterComment(
+      String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
+    return createResumableUploadCallSettingsComment(
+        CALL_SETTINGS_BUILDER_METHOD_DOC_PATTERN,
+        javaMethodName,
+        isMethodDeprecated,
+        isMethodInternal);
+  }
+
+  private static CommentStatement createResumableUploadCallSettingsComment(
+      String pattern, String javaMethodName, boolean isMethodDeprecated, boolean isMethodInternal) {
+    JavaDocComment.Builder docBuilder =
+        JavaDocComment.builder()
+            .addComment(String.format(pattern, javaMethodName))
+            .addParagraph(RESUMABLE_UPLOAD_CALL_SETTINGS_DOC_NOTE);
+    if (isMethodDeprecated) {
+      docBuilder.setDeprecated(CommentComposer.DEPRECATED_METHOD_STRING);
+    }
+    if (isMethodInternal) {
+      docBuilder.setInternalOnly(CommentComposer.INTERNAL_ONLY_METHOD_STRING);
+    }
+    return CommentStatement.withComment(docBuilder.build());
+  }
+
   public static List<CommentStatement> createClassHeaderComments(
       String configuredClassName,
       String defaultHost,