feat(gapic-generator): Add Nullable annotation to generated classes by nnicolee · Pull Request #13558 · googleapis/google-cloud-java

nnicolee · 2026-06-25T17:27:29Z

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

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

gemini-code-assist

Code Review

This pull request introduces @Nullable annotations to various generated classes and generator code in the Java GAPIC generator. Specifically, it updates the composer classes to annotate settings fields, getter methods, non-required resource name helper arguments, parse methods, toStringList generic types, and equals method arguments, with corresponding updates to the golden files. A review comment highlights a fragile workaround in ResourceNameHelperClassComposer.java where the @Nullable annotation is hacked into the VaporReference name string, warning that this could lead to issues with type comparisons, fully qualified names, AST manipulation, and missing imports, and suggests extending the AST classes to properly support type-use annotations.

lqiu96 · 2026-06-29T14:54:06Z

  public final Room getRoom(RoomName name) {
-    GetRoomRequest request =
-        GetRoomRequest.newBuilder().setName(name == null ? null : name.toString()).build();
+    GetRoomRequest request = GetRoomRequest.newBuilder().setName(name.toString()).build();


qq, I don't think we should change this. Perhaps better to mark the param as nullable?

+1 the new logic may affect this, which is a good way to catch additional cases where @Nullable is needed.

Discussed with @nnicolee, looks like setName is a proto class, which we don't have control over, and is being marked by NullAway with:

[ERROR] /usr/local/google/home/nicolejlee/google-cloud-java/java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/MessagingClient.java:[1822,64] error: [NullAway] passing @Nullable parameter 'parent == null ? null : parent.toString()' where @NonNull is required

If it was possible to configure ErrorProne to ignore proto classes in these cases that would be great. That could be a good first step.
On the other hand, looks like Proto classes actually can take nulls (since the code's been like this), which can be worked around by adding a warning suppression as Nicole suggested.

Yes, currently we're ignoring this error

…-cloud-java into feat/jspecify-nullable

sonarqubecloud · 2026-07-10T04:55:04Z

Quality Gate passed for 'gapic-generator-java-root'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
96.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

sonarqubecloud · 2026-07-10T04:55:59Z

Quality Gate passed for 'gapic-generator-java-root'

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

…-cloud-java into feat/jspecify-nullable

…ullable

…-cloud-java into feat/jspecify-nullable

The `check-version` job in showcase is not running in PRs that do not modify the specific paths. Update the job to use a filter job to skip the job on non-relevant PRs. Example: #13558

🤖 I have created a release *beep* *boop* --- <details><summary>1.89.0</summary> ## [1.89.0](v1.88.0...v1.89.0) (2026-07-29) ### Features * **agentidentity:** onboard v1 and v1beta API versions ([#13796](#13796)) ([1b1300d](1b1300d)) * **auth:** add JSpecify Null annotations to Auth ([#13842](#13842)) ([f6f24d4](f6f24d4)) * **bigquery-jdbc:** add `SSLTrustStoreType` and `SSLTrustStoreProvider` connection properties ([#13858](#13858)) ([9449be1](9449be1)) * **bigquery-jdbc:** add otel trace and span IDs to local logs ([#13935](#13935)) ([2801fbd](2801fbd)) * **bigquery-jdbc:** implement BigQueryParameterMetaData and dynamic type mappings ([#13812](#13812)) ([3d67dba](3d67dba)) * **bigquery-jdbc:** implement parameter setters in PreparedStatement ([#13792](#13792)) ([94f7404](94f7404)) * **bigquery-jdbc:** Migrate `getImportedKeys` and `getCrossReference` to BQ API ([#13692](#13692)) ([082b046](082b046)) * **bigquery-jdbc:** migrate `getPrimaryKeys` to use BQ API ([#13691](#13691)) ([1951f49](1951f49)) * **bigquery-jdbc:** OpenTelemetry integration in BQ JDBC ([#12902](#12902)) ([af18f65](af18f65)) * **bigquery-jdbc:** optimize memory footprint for JSON result set streaming ([#13660](#13660)) ([11f26d3](11f26d3)) * **bigquery-jdbc:** standardize parameter handling and calendar defensive copying across statement interfaces ([#13805](#13805)) ([ccd13eb](ccd13eb)) * **bigtable:** add view_parameters support to BoundStatement ([#13673](#13673)) ([d5cc437](d5cc437)) * **bigtable:** BigtableDataClientFactory session support ([#13829](#13829)) ([284ce13](284ce13)) * **commerceproducer:** onboard v1beta API ([#13814](#13814)) ([61b89b3](61b89b3)) * Default to least-in-flight balancing for Bigtable unary clients ([#13802](#13802)) ([ac9ccd1](ac9ccd1)) * **firestore:** Add support for 16MB documents ([#13478](#13478)) ([1b7c2e0](1b7c2e0)) * **gapic-generator:** add JSpecify Null annotations to the generator classes ([#13769](#13769)) ([843bd7c](843bd7c)) * **gapic-generator:** Add Nullable annotation to generated classes ([#13558](#13558)) ([e3e9d0b](e3e9d0b)) * **gapic-generator:** Add NullMarked annotation to generated classes ([#13584](#13584)) ([b7a8504](b7a8504)) * **gax-httpjson:** Add Post Quantum Cryptography (PQC) Support by default via Conscrypt ([#13853](#13853)) ([550df81](550df81)) * **gax-java:** add JSpecify Null annotations to gax ([#13799](#13799)) ([65aee08](65aee08)) * **google/cloud/sql:** onboard a new library ([#13864](#13864)) ([38e272e](38e272e)) * **google/maps/navconnect/v1:** onboard a new library ([#13927](#13927)) ([2256394](2256394)) * **maps-isochrones:** onboard v1 API ([#13817](#13817)) ([3037ab3](3037ab3)) * port secure_context testing support to executor proxy ([#13522](#13522)) ([0f81bf0](0f81bf0)) * **productregistry:** onboard v1 API ([#13816](#13816)) ([9517313](9517313)) * **storage:** allow checksum on appendable upload finalization ([#13833](#13833)) ([ddf9add](ddf9add)) * **storage:** enable App-Centric Observability (ACO) support in Otel ([#13248](#13248)) ([4329896](4329896)) ### Bug Fixes * **bigquery-jdbc:** Add PerConnectionHandler to list of excempted logging classes ([#13888](#13888)) ([50b3c24](50b3c24)) * **bigquery-jdbc:** add preferIPv4Stack to argLine for Kokoro reliability ([#13923](#13923)) ([d5e33d6](d5e33d6)) * **bigquery-jdbc:** add service resource transformer for standalone IT ([#13893](#13893)) ([dc80fe8](dc80fe8)) * **bigquery-jdbc:** align metadata methods error handling with spec ([#13793](#13793)) ([d85fb10](d85fb10)) * **bigquery-jdbc:** fix WriteAPI when running in restricted environment ([#13856](#13856)) ([66ba925](66ba925)) * **bigquery-jdbc:** refine temporal timezone coercion and PreparedStatement parameter setters ([#13813](#13813)) ([6f68c4d](6f68c4d)) * **bigquery-jdbc:** resolve `ITOpenTelemetryTest` pipeline and trace validation failures ([#13898](#13898)) ([c18141d](c18141d)) * **bigquery-jdbc:** resolve failing otel IT in nightly ([#13915](#13915)) ([ac79713](ac79713)) * **bigquery:** resultSet.getLong() does not truncate for large int64 values ([#13718](#13718)) ([bc19822](bc19822)) * **bigquery:** support optional fields in BigLakeConfiguration to prevent NPE on Iceberg/Lakehouse tables ([#13733](#13733)) ([e2cca4d](e2cca4d)) * **bigtable:** add materialized view routing param to ReadRows and Sa… ([#13918](#13918)) ([4ddf250](4ddf250)) * **bigtable:** bound SessionPoolImpl lock to prevent pod-wide wedge ([#13890](#13890)) ([ed87a68](ed87a68)) * **bigtable:** fix session creation leaks ([#13887](#13887)) ([d586d07](d586d07)) * **bigtable:** prevent ClientConfigurationManagerTest from wedging on… ([#13907](#13907)) ([725086d](725086d)) * **bigtable:** stop installing DirectpathEnforcer on the directpath pool ([#13880](#13880)) ([5f2e056](5f2e056)) * **bom:** make release-note-generation Java 8 compatible ([#13837](#13837)) ([bc18390](bc18390)) * **ci:** fix java-cloud-bom release-notes workflow errors ([#13682](#13682)) ([b679835](b679835)) * deprecate resource detector ([#13844](#13844)) ([aba4f01](aba4f01)) * **deps:** align logback versions and add java8 profile in storage ([#13678](#13678)) ([7e57092](7e57092)) * do not start stream with direct executor ([#13945](#13945)) ([630e790](630e790)) * fix java-cloud-bom README update workflow after monorepo migration ([#13892](#13892)) ([5b8e295](5b8e295)) * **oauth2_http:** Avoid retrying on 4xx errors during GCE metadata ping ([#13715](#13715)) ([537c16c](537c16c)) * regenerate ([#13714](#13714)) ([8a72860](8a72860)) * regenerate libraries ([#13703](#13703)) ([a29ea79](a29ea79)), refs [#13690](#13690) * **release:** handle missing release tags gracefully in release-note-generation ([#13795](#13795)) ([43005fb](43005fb)) * **release:** resolve first-party-dependencies SNAPSHOT in libraries-bom ([#13790](#13790)) ([d5bfe21](d5bfe21)) * **spanner:** avoid data race on DIRECTPATH_CHANNEL_CREATED by using volatile ([#13727](#13727)) ([1e05ea5](1e05ea5)) * **spanner:** prevent fastpath tablet routing flaps ([#13803](#13803)) ([4dabdac](4dabdac)) * **storage:** BidiAppendableUpload Takeover operation fixes ([#13776](#13776)) ([f2d0474](f2d0474)) * **storage:** correctly insert explicit nulls for json patch updates ([#13716](#13716)) ([4fb3f4b](4fb3f4b)) * update group id mapping ([#13698](#13698)) ([50a72e1](50a72e1)) * use a new managed channel builder when creating channels ([#13684](#13684)) ([a049999](a049999)) ### Performance Improvements * **bigquery-jdbc:** optimize getExportedKeys performance using hybrid metadata lookup ([#13734](#13734)) ([c9738ea](c9738ea)) ### Dependencies * Add Conscrypt to shared-deps ([#13838](#13838)) ([05ce6ce](05ce6ce)) * move conscrypt from third-party-dependencies POM to gax-java POM ([#13948](#13948)) ([1e634ec](1e634ec)) * **shared-deps:** migrate awaitility to shared-dependencies ([#13671](#13671)) ([abb91ef](abb91ef)) * **shared-deps:** switch conscrypt shared dependency to conscrypt-openjdk-uber ([#13845](#13845)) ([2e3f208](2e3f208)) * Update gRPC-Java to v1.82.2 ([#13877](#13877)) ([da228d8](da228d8)) * Update http-client to v2.2.0 ([#13854](#13854)) ([334a2c5](334a2c5)) * Update Protobuf-Java to v4.33.6 ([#13876](#13876)) ([5c6478c](5c6478c)) * Upgrade Guava to v33.6.0-jre ([#13875](#13875)) ([41a7a52](41a7a52)) ### Documentation * add ErrorProne and NullAway integration guide and JSpecify migration playbook ([#13882](#13882)) ([d5ea739](d5ea739)) * add JSpecify nullness guidelines to AGENTS.md ([#13881](#13881)) ([54b846b](54b846b)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>

nnicolee requested a review from lqiu96 June 25, 2026 17:27

nnicolee added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Jun 25, 2026

gemini-code-assist Bot reviewed Jun 25, 2026

View reviewed changes

Comment thread ...va/com/google/api/generator/gapic/composer/resourcename/ResourceNameHelperClassComposer.java Outdated

nnicolee added the kokoro:run Add this label to force Kokoro to re-run the tests. label Jun 25, 2026

yoshi-kokoro removed the kokoro:run Add this label to force Kokoro to re-run the tests. label Jun 25, 2026

nnicolee added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 25, 2026

yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 25, 2026

nnicolee marked this pull request as ready for review June 26, 2026 23:07

nnicolee requested review from a team as code owners June 26, 2026 23:07

lqiu96 reviewed Jun 29, 2026

View reviewed changes

Comment thread java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/ComplianceClient.java Outdated

lqiu96 reviewed Jun 29, 2026

View reviewed changes

Comment thread java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/ComplianceClient.java Outdated

lqiu96 reviewed Jun 29, 2026

View reviewed changes

Comment thread java-showcase/gapic-showcase/src/main/java/com/google/showcase/v1beta1/ComplianceClient.java

lqiu96 reviewed Jun 29, 2026

View reviewed changes

Comment thread ...owcase/proto-gapic-showcase-v1beta1/src/main/java/com/google/showcase/v1beta1/BlurbName.java Outdated

nnicolee force-pushed the feat/jspecify-nullable branch from 96dffb8 to 30ce14a Compare June 30, 2026 19:03

nnicolee requested review from a team as code owners June 30, 2026 19:03

nnicolee force-pushed the feat/jspecify-nullable branch 2 times, most recently from 96dffb8 to 0a438e0 Compare July 6, 2026 16:10

nnicolee changed the base branch from main to feat/jspecify-add-nullmarked July 6, 2026 16:17

lqiu96 reviewed Jul 7, 2026

View reviewed changes

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

lqiu96 reviewed Jul 7, 2026

View reviewed changes

Comment thread ...c-generator-java/src/main/java/com/google/api/generator/engine/writer/JavaWriterVisitor.java Outdated

nnicolee changed the base branch from feat/jspecify-add-nullmarked to main July 8, 2026 05:05

nnicolee added 2 commits July 8, 2026 17:34

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

2394424

feat: revert generator pom.xml and temp compiler dump files

0a6de10

nnicolee force-pushed the feat/jspecify-nullable branch 2 times, most recently from c245fbc to 8084981 Compare July 8, 2026 22:10

nnicolee added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jul 9, 2026

yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jul 9, 2026

nnicolee added 3 commits July 9, 2026 15:36

Merge branch 'main' into feat/jspecify-nullable

0f4837f

fix: reset name in VaporReference.toBuilder()

8655411

Merge branch 'feat/jspecify-nullable' of github.com:googleapis/google…

84e5843

…-cloud-java into feat/jspecify-nullable

cloud-java-bot and others added 9 commits July 10, 2026 06:18

chore: regenerate libraries

d9b3431

fix linting on comment

9725012

Merge branch 'feat/jspecify-nullable' of github.com:googleapis/google…

991c89c

…-cloud-java into feat/jspecify-nullable

fix: add support for nested class in VaporReference in JavaWriterVisitor

3783406

chore: regenerate libraries

60320e7

chore(owlbot): update toStringList removal signatures for JSpecify @n…

cf6f6a0

…ullable

Merge branch 'feat/jspecify-nullable' of github.com:googleapis/google…

ee95114

…-cloud-java into feat/jspecify-nullable

Merge branch 'main' into feat/jspecify-nullable

0ec839d

chore: regenerate libraries

d528f65

nnicolee closed this Jul 13, 2026

nnicolee reopened this Jul 13, 2026

lqiu96 approved these changes Jul 13, 2026

View reviewed changes

Merge branch 'main' into feat/jspecify-nullable

9abcbd5

nnicolee removed the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Jul 14, 2026

nnicolee enabled auto-merge (squash) July 14, 2026 16:01

lqiu96 mentioned this pull request Jul 14, 2026

ci(showcase): use separate filter job for version check #13770

Merged

nnicolee merged commit e3e9d0b into main Jul 14, 2026
228 of 233 checks passed

nnicolee deleted the feat/jspecify-nullable branch July 14, 2026 19:29

release-please Bot mentioned this pull request Jul 28, 2026

chore(main): release 1.89.0 #13934

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

feat(gapic-generator): Add Nullable annotation to generated classes#13558
nnicolee merged 23 commits into
mainfrom
feat/jspecify-nullable

nnicolee commented Jun 25, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lqiu96 Jun 29, 2026

Uh oh!

diegomarquezp Jun 29, 2026

Uh oh!

diegomarquezp Jun 29, 2026

Uh oh!

nnicolee Jul 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

nnicolee commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lqiu96 Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegomarquezp Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

diegomarquezp Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

nnicolee Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Quality Gate passed for 'gapic-generator-java-root'

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Quality Gate passed for 'gapic-generator-java-root'

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nnicolee commented Jun 25, 2026 •

edited

Loading