feat(gapic-generator): Add Nullable annotation to generated classes (#13558)

This PR updates the gapic-generator-java to add the JSpecify @nullable
annotation to all generated class declarations. This is the second phase
in onboarding the generated client libraries to compile-time safety
validation, see design doc for more details:
[go/sdk:java-jspecify-null-annotations-gapic](http://goto.google.com/sdk:java-jspecify-null-annotations-gapic)

Classes Annotated:

- Client Classes: AbstractServiceClientClassComposer
- Stub Classes: AbstractServiceStubClassComposer and
ServiceStubClassComposer
- Resource Names: ResourceNameHelperClassComposer

Implementation Changes:

- Built the parameter variable expression in equals(Object o) as a
reference initially, and attached the @nullable annotation during its
method argument declaration (with isDecl = true). This prevents
IllegalStateException crashes in the generator's strict AST validation
engine.
- Leveraged a VaporReference type name-hacking trick to render generic
type-use annotations (such as List<@nullable ResourceName>) without
needing disruptive changes to the core AST reference rendering engine.
- Modified two owlbot.py scripts to reflect the signature changes:
‎java-bigquerydatatransfer/owlbot.py &
java-bigquerydatatransfer/owlbot.py

Verification/Testing:
- Please refer to this doc:
https://docs.google.com/document/d/1h126pbTGqSwtJyl35E2_vQjM9gNtmWETYCM7PObcvmQ/edit?tab=t.0#heading=h.s4q06jxocx8b

---------

Co-authored-by: cloud-java-bot <cloud-java-bot@google.com>

Author: nnicolee

java-accessapproval/google-cloud-accessapproval/src/main/java/com/google/cloud/accessapproval/v1/AccessApprovalAdminClient.java

@@ -34,6 +34,7 @@
 import java.util.concurrent.TimeUnit;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 /**
@@ -318,7 +319,7 @@
 @NullMarked
 @Generated("by gapic-generator-java")
 public class AccessApprovalAdminClient implements BackgroundResource {
-  private final AccessApprovalAdminSettings settings;
+  private final @Nullable AccessApprovalAdminSettings settings;
   private final AccessApprovalStub stub;
 
   /** Constructs an instance of AccessApprovalAdminClient with default settings. */
@@ -358,7 +359,7 @@ protected AccessApprovalAdminClient(AccessApprovalStub stub) {
     this.stub = stub;
   }
 
-  public final AccessApprovalAdminSettings getSettings() {
+  public final @Nullable AccessApprovalAdminSettings getSettings() {
     return settings;
   }
 
@@ -392,7 +393,7 @@ public AccessApprovalStub getStub() {
    *     "organizations/{organization}".
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
-  public final ListApprovalRequestsPagedResponse listApprovalRequests(FolderName parent) {
+  public final ListApprovalRequestsPagedResponse listApprovalRequests(@Nullable FolderName parent) {
     ListApprovalRequestsMessage request =
         ListApprovalRequestsMessage.newBuilder()
             .setParent(parent == null ? null : parent.toString())
@@ -426,7 +427,8 @@ public final ListApprovalRequestsPagedResponse listApprovalRequests(FolderName p
    *     "organizations/{organization}".
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
-  public final ListApprovalRequestsPagedResponse listApprovalRequests(OrganizationName parent) {
+  public final ListApprovalRequestsPagedResponse listApprovalRequests(
+      @Nullable OrganizationName parent) {
     ListApprovalRequestsMessage request =
         ListApprovalRequestsMessage.newBuilder()
             .setParent(parent == null ? null : parent.toString())
@@ -460,7 +462,8 @@ public final ListApprovalRequestsPagedResponse listApprovalRequests(Organization
    *     "organizations/{organization}".
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
-  public final ListApprovalRequestsPagedResponse listApprovalRequests(ProjectName parent) {
+  public final ListApprovalRequestsPagedResponse listApprovalRequests(
+      @Nullable ProjectName parent) {
     ListApprovalRequestsMessage request =
         ListApprovalRequestsMessage.newBuilder()
             .setParent(parent == null ? null : parent.toString())
@@ -636,7 +639,7 @@ public final ListApprovalRequestsPagedResponse listApprovalRequests(
    *     "{projects|folders|organizations}/{id}/approvalRequests/{approval_request}"
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
-  public final ApprovalRequest getApprovalRequest(ApprovalRequestName name) {
+  public final ApprovalRequest getApprovalRequest(@Nullable ApprovalRequestName name) {
     GetApprovalRequestMessage request =
         GetApprovalRequestMessage.newBuilder()
             .setName(name == null ? null : name.toString())
@@ -980,7 +983,8 @@ public final ApprovalRequest invalidateApprovalRequest(InvalidateApprovalRequest
    *     "{projects|folders|organizations}/{id}/accessApprovalSettings"
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
-  public final AccessApprovalSettings getAccessApprovalSettings(AccessApprovalSettingsName name) {
+  public final AccessApprovalSettings getAccessApprovalSettings(
+      @Nullable AccessApprovalSettingsName name) {
     GetAccessApprovalSettingsMessage request =
         GetAccessApprovalSettingsMessage.newBuilder()
             .setName(name == null ? null : name.toString())
@@ -1204,7 +1208,7 @@ public final AccessApprovalSettings updateAccessApprovalSettings(
    * @param name Name of the AccessApprovalSettings to delete.
    * @throws com.google.api.gax.rpc.ApiException if the remote call fails
    */
-  public final void deleteAccessApprovalSettings(AccessApprovalSettingsName name) {
+  public final void deleteAccessApprovalSettings(@Nullable AccessApprovalSettingsName name) {
     DeleteAccessApprovalSettingsMessage request =
         DeleteAccessApprovalSettingsMessage.newBuilder()
             .setName(name == null ? null : name.toString())
@@ -1457,9 +1461,10 @@ public static class ListApprovalRequestsPage
           ListApprovalRequestsPage> {
 
     private ListApprovalRequestsPage(
-        PageContext<ListApprovalRequestsMessage, ListApprovalRequestsResponse, ApprovalRequest>
+        @Nullable
+            PageContext<ListApprovalRequestsMessage, ListApprovalRequestsResponse, ApprovalRequest>
             context,
-        ListApprovalRequestsResponse response) {
+        @Nullable ListApprovalRequestsResponse response) {
       super(context, response);
     }
 
@@ -1469,15 +1474,17 @@ private static ListApprovalRequestsPage createEmptyPage() {
 
     @Override
     protected ListApprovalRequestsPage createPage(
-        PageContext<ListApprovalRequestsMessage, ListApprovalRequestsResponse, ApprovalRequest>
+        @Nullable
+            PageContext<ListApprovalRequestsMessage, ListApprovalRequestsResponse, ApprovalRequest>
             context,
-        ListApprovalRequestsResponse response) {
+        @Nullable ListApprovalRequestsResponse response) {
       return new ListApprovalRequestsPage(context, response);
     }
 
     @Override
     public ApiFuture<ListApprovalRequestsPage> createPageAsync(
-        PageContext<ListApprovalRequestsMessage, ListApprovalRequestsResponse, ApprovalRequest>
+        @Nullable
+            PageContext<ListApprovalRequestsMessage, ListApprovalRequestsResponse, ApprovalRequest>
             context,
         ApiFuture<ListApprovalRequestsResponse> futureResponse) {
       return super.createPageAsync(context, futureResponse);
@@ -1493,7 +1500,7 @@ public static class ListApprovalRequestsFixedSizeCollection
           ListApprovalRequestsFixedSizeCollection> {
 
     private ListApprovalRequestsFixedSizeCollection(
-        List<ListApprovalRequestsPage> pages, int collectionSize) {
+        @Nullable List<ListApprovalRequestsPage> pages, int collectionSize) {
       super(pages, collectionSize);
     }
 
@@ -1503,7 +1510,7 @@ private static ListApprovalRequestsFixedSizeCollection createEmptyCollection() {
 
     @Override
     protected ListApprovalRequestsFixedSizeCollection createCollection(
-        List<ListApprovalRequestsPage> pages, int collectionSize) {
+        @Nullable List<ListApprovalRequestsPage> pages, int collectionSize) {
       return new ListApprovalRequestsFixedSizeCollection(pages, collectionSize);
     }
   }

java-accessapproval/google-cloud-accessapproval/src/main/java/com/google/cloud/accessapproval/v1/AccessApprovalAdminSettings.java

@@ -36,6 +36,7 @@
 import java.util.List;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 /**
@@ -207,7 +208,7 @@ public static Builder newHttpJsonBuilder() {
   }
 
   /** Returns a new builder for this class. */
-  public static Builder newBuilder(ClientContext clientContext) {
+  public static Builder newBuilder(@Nullable ClientContext clientContext) {
     return new Builder(clientContext);
   }
 
@@ -227,7 +228,7 @@ protected Builder() throws IOException {
       this(((ClientContext) null));
     }
 
-    protected Builder(ClientContext clientContext) {
+    protected Builder(@Nullable ClientContext clientContext) {
       super(AccessApprovalStubSettings.newBuilder(clientContext));
     }
 

java-accessapproval/google-cloud-accessapproval/src/main/java/com/google/cloud/accessapproval/v1/stub/AccessApprovalStubSettings.java

@@ -68,6 +68,7 @@
 import java.util.List;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 /**
@@ -371,7 +372,7 @@ public static Builder newHttpJsonBuilder() {
   }
 
   /** Returns a new builder for this class. */
-  public static Builder newBuilder(ClientContext clientContext) {
+  public static Builder newBuilder(@Nullable ClientContext clientContext) {
     return new Builder(clientContext);
   }
 
@@ -481,7 +482,7 @@ protected Builder() {
       this(((ClientContext) null));
     }
 
-    protected Builder(ClientContext clientContext) {
+    protected Builder(@Nullable ClientContext clientContext) {
       super(clientContext);
 
       listApprovalRequestsSettings =

java-accessapproval/proto-google-cloud-accessapproval-v1/src/main/java/com/google/cloud/accessapproval/v1/AccessApprovalSettingsName.java

@@ -27,6 +27,7 @@
 import java.util.Objects;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 @NullMarked
@@ -137,7 +138,7 @@ public static String formatOrganizationName(String organization) {
     return newOrganizationBuilder().setOrganization(organization).build().toString();
   }
 
-  public static AccessApprovalSettingsName parse(String formattedString) {
+  public static @Nullable AccessApprovalSettingsName parse(String formattedString) {
     if (formattedString.isEmpty()) {
       return null;
     }
@@ -163,7 +164,7 @@ public static List<AccessApprovalSettingsName> parseList(List<String> formattedS
     return list;
   }
 
-  public static List<String> toStringList(List<AccessApprovalSettingsName> values) {
+  public static List<String> toStringList(List<@Nullable AccessApprovalSettingsName> values) {
     List<String> list = new ArrayList<>(values.size());
     for (AccessApprovalSettingsName value : values) {
       if (value == null) {
@@ -213,7 +214,7 @@ public String toString() {
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (o == this) {
       return true;
     }

java-accessapproval/proto-google-cloud-accessapproval-v1/src/main/java/com/google/cloud/accessapproval/v1/ApprovalRequestName.java

@@ -27,6 +27,7 @@
 import java.util.Objects;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 @NullMarked
@@ -166,7 +167,7 @@ public static String formatOrganizationApprovalRequestName(
         .toString();
   }
 
-  public static ApprovalRequestName parse(String formattedString) {
+  public static @Nullable ApprovalRequestName parse(String formattedString) {
     if (formattedString.isEmpty()) {
       return null;
     }
@@ -193,7 +194,7 @@ public static List<ApprovalRequestName> parseList(List<String> formattedStrings)
     return list;
   }
 
-  public static List<String> toStringList(List<ApprovalRequestName> values) {
+  public static List<String> toStringList(List<@Nullable ApprovalRequestName> values) {
     List<String> list = new ArrayList<>(values.size());
     for (ApprovalRequestName value : values) {
       if (value == null) {
@@ -246,7 +247,7 @@ public String toString() {
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (o == this) {
       return true;
     }

java-accessapproval/proto-google-cloud-accessapproval-v1/src/main/java/com/google/cloud/accessapproval/v1/FolderName.java

@@ -26,6 +26,7 @@
 import java.util.Objects;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 @NullMarked
@@ -65,7 +66,7 @@ public static String format(String folder) {
     return newBuilder().setFolder(folder).build().toString();
   }
 
-  public static FolderName parse(String formattedString) {
+  public static @Nullable FolderName parse(String formattedString) {
     if (formattedString.isEmpty()) {
       return null;
     }
@@ -83,7 +84,7 @@ public static List<FolderName> parseList(List<String> formattedStrings) {
     return list;
   }
 
-  public static List<String> toStringList(List<FolderName> values) {
+  public static List<String> toStringList(List<@Nullable FolderName> values) {
     List<String> list = new ArrayList<>(values.size());
     for (FolderName value : values) {
       if (value == null) {
@@ -125,7 +126,7 @@ public String toString() {
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (o == this) {
       return true;
     }

java-accessapproval/proto-google-cloud-accessapproval-v1/src/main/java/com/google/cloud/accessapproval/v1/OrganizationName.java

@@ -26,6 +26,7 @@
 import java.util.Objects;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 @NullMarked
@@ -65,7 +66,7 @@ public static String format(String organization) {
     return newBuilder().setOrganization(organization).build().toString();
   }
 
-  public static OrganizationName parse(String formattedString) {
+  public static @Nullable OrganizationName parse(String formattedString) {
     if (formattedString.isEmpty()) {
       return null;
     }
@@ -83,7 +84,7 @@ public static List<OrganizationName> parseList(List<String> formattedStrings) {
     return list;
   }
 
-  public static List<String> toStringList(List<OrganizationName> values) {
+  public static List<String> toStringList(List<@Nullable OrganizationName> values) {
     List<String> list = new ArrayList<>(values.size());
     for (OrganizationName value : values) {
       if (value == null) {
@@ -125,7 +126,7 @@ public String toString() {
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (o == this) {
       return true;
     }

java-accessapproval/proto-google-cloud-accessapproval-v1/src/main/java/com/google/cloud/accessapproval/v1/ProjectName.java

@@ -26,6 +26,7 @@
 import java.util.Objects;
 import javax.annotation.Generated;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 // AUTO-GENERATED DOCUMENTATION AND CLASS.
 @NullMarked
@@ -65,7 +66,7 @@ public static String format(String project) {
     return newBuilder().setProject(project).build().toString();
   }
 
-  public static ProjectName parse(String formattedString) {
+  public static @Nullable ProjectName parse(String formattedString) {
     if (formattedString.isEmpty()) {
       return null;
     }
@@ -83,7 +84,7 @@ public static List<ProjectName> parseList(List<String> formattedStrings) {
     return list;
   }
 
-  public static List<String> toStringList(List<ProjectName> values) {
+  public static List<String> toStringList(List<@Nullable ProjectName> values) {
     List<String> list = new ArrayList<>(values.size());
     for (ProjectName value : values) {
       if (value == null) {
@@ -125,7 +126,7 @@ public String toString() {
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (o == this) {
       return true;
     }