Merge branch 'main' into bigtable-admin-client

Author: jinseopkim0

.agents/skills/api-lifecycle/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: api-lifecycle
+description: Guidelines and playbooks for managing the API lifecycle (BetaApi, GA, ObsoleteApi, Deprecated, and Removal) in the Google Cloud Java SDK. Use this skill when modifying, deprecating, or introducing new public API surfaces.
+---
+
+# API Lifecycle & Stability Guide
+
+This guide defines the lifecycle phases and stability annotations of public APIs inside the Google Cloud Java SDK. Use this to ensure all public methods, classes, and fields correctly adhere to Semantic Versioning (Semver) and safely transition through deprecation phases.
+
+> [!IMPORTANT]
+> **Scope & Visibility Rule**
+> This guideline applies **ONLY to public API surfaces** (e.g., `public` classes, interfaces, methods, and fields) that are exposed to external/downstream consumers. It does **NOT** apply to private, package-private, or internal implementation details.
+
+---
+
+## Design Principle: Minimize Public API Surface
+
+To reduce maintenance overhead and ensure long-term flexibility, developers should actively avoid creating public APIs unless absolutely necessary.
+
+*   **Default to Restrictive Visibility**: Always default to the most restrictive access modifier (`private`, `package-private`, or `@InternalApi`) for new classes, methods, and fields. Only expose an API as `public` if there is a clear, justified requirement for external consumers.
+*   **Exposing Public APIs Commits Us**: Every public class, method, or field represents a strict compatibility contract under Semantic Versioning. Once public, modifying or removing it requires a long, multi-phase deprecation cycle.
+*   Prefer Internal Utilities: If functionality is only needed within the same package or module, keep it private or package-private. Do not make it public "just in case".
+
+---
+
+## The API Lifecycle Flow
+
+An API does **not** have to start with `@BetaApi`. Stable, well-designed features can be introduced directly as General Availability (GA). The `@BetaApi` annotation is reserved for experimental, preview, or unstable APIs.
+
+Below is the transition flow for public APIs:
+
+**Standard Lifecycle (Direct to GA):**
+`General Availability (GA) ──> @ObsoleteApi (Staged Deprecation) ──> @Deprecated (Official) ──> Removed`
+
+**Experimental Lifecycle (Beta first):**
+`@BetaApi (Experimental) ──> General Availability (GA) ──> @ObsoleteApi (Staged Deprecation) ──> @Deprecated (Official) ──> Removed`
+
+---
+
+## API Lifecycle Stages
+
+### 1. `@BetaApi` (Experimental Phase)
+*   **Purpose**: Used for experimental, preview, or unstable API surfaces.
+*   **Semver Policy**: Treated as a **"0.x" feature inside a "1.x" library**. Subject to incompatible changes or removal between minor and patch releases at any time.
+*   **Graduation Policy**: Not all APIs start here. Many APIs go directly to GA. If an API does start as `@BetaApi`, it is intended to eventually graduate to a GA feature by removing the `@BetaApi` annotation.
+*   **Usage Rule**: Do **NOT** depend on `@BetaApi` features inside a public library `B` that has downstream consumers, *unless* the consuming components of library `B` are also marked with `@BetaApi`.
+*   **Exception**: `google-cloud-java` is allowed to depend on `@BetaApi` features in `gax-java` without declaring the consuming code `@BetaApi`, as they move in lockstep.
+
+### 2. General Availability (GA)
+*   **Purpose**: Stable API surfaces intended for production use.
+*   Policy: Deprecation or breaking changes to GA APIs are considered breaking changes and should generally not be performed under a minor version release using standard @Deprecated.
+
+### 3. `@ObsoleteApi` (Staged Deprecation)
+*   **Purpose**: Signals to users that an API will be deprecated in a future version, allowing them to transition to alternative methods before official deprecation.
+*   **Policy**: Used during minor version releases.
+*   **Usage Guidelines**:
+    *   **Annotation**: Apply `@ObsoleteApi("Reason or alternative instructions")`. A descriptive reason is required.
+    *   **Javadoc**: Detail the replacement or migration path, referencing alternative methods via `{@link}`.
+    *   **IDE Impact**: Does not trigger IDE compilation/strike-through warnings, keeping downstream builds warning-free.
+
+### 4. `@Deprecated` (Official Deprecation)
+*   **Purpose**: Officially deprecates the API in the editor/IDE, producing compiler warnings and strike-throughs.
+*   **Policy**: Strongly recommended to be applied during **Major Version Releases** (e.g., `v2.0.0`), or in rare emergency cases to fix critical security vulnerabilities. However, it can be acceptable in minor version releases if the library owners explicitly review and determine that the deprecation is low-risk for downstream consumers.
+*   **Usage Guidelines**:
+    *   **Annotation**: Apply Java's standard `@Deprecated` annotation to the code element.
+    *   **Javadoc**: Add the standard `@deprecated` Javadoc tag describing alternative APIs or transition steps.
+
+### 5. Removal
+*   **Purpose**: Complete removal of the API from the codebase.
+*   **Policy**: Performed in a subsequent major version release following official deprecation.
+*   **Usage Guidelines**:
+    *   **Action**: Completely delete the class, interface, method, or field, along with its Javadoc and annotations.
+    *   **Validation**: Verify that all internal usages, references, and tests within the monorepo are fully cleaned up or migrated.
+
+---
+
+## API Stability & Visibility Annotations
+
+While the standard **API Lifecycle Stages** section above defines how public APIs transition over time, the SDK also utilizes specialized stability annotations. These annotations serve as "exceptions" or "special contracts" that dictate how Semantic Versioning applies to public elements:
+
+### 1. `@InternalApi`
+*   **Definition**: Technically `public` because of Java's access modifier limitations, but intended **only** for internal use.
+*   **Semver Policy**: For the purposes of semver, these are considered **private**. They can be modified or deleted in any minor or patch release without breaking compatibility.
+
+### 2. `@InternalExtensionOnly`
+*   **Definition**: A `public` interface that is only intended to be implemented by internal SDK classes, though it can be consumed publicly.
+*   **Semver Policy**: We reserve the right to add new methods to these interfaces without providing default implementations in minor/patch releases. Downstream consumers should **not** write custom implementations of these interfaces.
+
+*(Note: For experimental public APIs, see the `@BetaApi` stage in the Lifecycle Stages section above.)*
+
+---
+
+## Checklist for API Modifiers & Code Reviewers
+
+- [ ] **Is the API GA?** If so, do **NOT** apply `@Deprecated` directly in a minor release. Apply `@ObsoleteApi` first.
+- [ ] **Is it intended only for internal use?** If so, mark it `@InternalApi` so downstream users don't rely on it.
+- [ ] **Is it an interface meant only for internal implementation?** Mark it `@InternalExtensionOnly` to protect future extensions.
+- [ ] **Does `@ObsoleteApi` or `@Deprecated` have a `value` parameter?** The string must explain *why* and *what* the user should do instead.
+- [ ] **Does the Javadoc link to alternatives?** Use `{@link #alternativeMethod()}` so the user can easily navigate in their IDE.

.github/CODEOWNERS

@@ -9,6 +9,8 @@
 /java-vertexai/   @googleapis/vertexai-team @googleapis/cloud-sdk-java-team
 /java-bigquerystorage/ @googleapis/bigquery-team @googleapis/cloud-sdk-java-team
 /java-bigquery/ @googleapis/bigquery-team @googleapis/cloud-sdk-java-team
+/java-bigquery-jdbc/ @googleapis/bigquery-developer-tools-team @googleapis/bigquery-team @googleapis/cloud-sdk-java-team
+/grpc-gcp-java/ @googleapis/spanner-team @googleapis/cloud-sdk-java-team
 /java-spanner/ @googleapis/spanner-team @googleapis/cloud-sdk-java-team
 /java-spanner-jdbc/ @googleapis/spanner-team @googleapis/cloud-sdk-java-team
 /google-auth-library-java/ @googleapis/cloud-sdk-auth-team @googleapis/cloud-sdk-java-team @googleapis/aion-team

.github/requirements.txt

@@ -100,9 +100,9 @@ charset-normalizer==3.3.2 \
     --hash=sha256:fd1abc0d89e30cc4e02e4064dc67fcc51bd941eb395c502aac3ec19fab46b519 \
     --hash=sha256:ff8fa367d09b717b2a17a052544193ad76cd49979c805768879cb63d9ca50561
     # via requests
-idna==3.7 \
-    --hash=sha256:028ff3aadf0609c1fd278d8ea3089299412a7a8b9bd005dd08b9f8285bcb5cfc \
-    --hash=sha256:82fee1fc78add43492d3a1898bfa6d8a904cc97d8427f683ed8e798d07761aa0
+idna==3.15 \
+    --hash=sha256:048adeaf8c2d788c40fee287673ccaa74c24ffd8dcf09ffa555a2fbb59f10ac8 \
+    --hash=sha256:ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc
     # via requests
 requests==2.33.0 \
     --hash=sha256:3324635456fa185245e24865e810cecec7b4caf933d7eb133dcde67d48cee69b \

.github/workflows/ci.yaml

@@ -36,8 +36,8 @@ jobs:
       with:
         filters: |
           src:
-            - '!(google-auth-library-java|java-bigquery|java-bigquerystorage|java-bigtable|java-datastore|java-firestore|java-logging|java-logging-logback|java-pubsub|java-spanner|java-storage)/**/*.java'
-            - '!(google-auth-library-java|java-bigquery|java-bigquerystorage|java-bigtable|java-datastore|java-firestore|java-logging|java-logging-logback|java-pubsub|java-spanner|java-storage)/**/pom.xml'
+            - '!(google-auth-library-java|grpc-gcp-java|java-bigquery|java-bigquery-jdbc|java-bigquerystorage|java-bigtable|java-datastore|java-firestore|java-logging|java-logging-logback|java-pubsub|java-spanner|java-storage)/**/*.java'
+            - '!(google-auth-library-java|grpc-gcp-java|java-bigquery|java-bigquery-jdbc|java-bigquerystorage|java-bigtable|java-datastore|java-firestore|java-logging|java-logging-logback|java-pubsub|java-spanner|java-storage)/**/pom.xml'
             - 'pom.xml'
           ci:
             - '.github/workflows/ci.yaml'
@@ -123,6 +123,8 @@ jobs:
         filters: |
           google-auth-library-java:
             - 'google-auth-library-java/**'
+          grpc-gcp-java:
+            - 'grpc-gcp-java/**'
           java-bigquery:
             - 'java-bigquery/**'
             - 'google-auth-library-java/**/*.java'
@@ -160,6 +162,7 @@ jobs:
             - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
           java-spanner:
             - 'java-spanner/**'
+            - 'grpc-gcp-java/**'
             - 'google-auth-library-java/**/*.java'
             - 'google-auth-library-java/**/pom.xml'
             - 'sdk-platform-java/**/*.java'

.github/workflows/java-bigquery-jdbc-ci.yaml

@@ -0,0 +1,158 @@
+# Copyright 2026 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.
+# Github action job to test core java library features on
+# downstream client libraries before they are released.
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+name: java-bigquery-jdbc ci
+env:
+  BUILD_SUBDIR: java-bigquery-jdbc
+jobs:
+  filter:
+    runs-on: ubuntu-latest
+    outputs:
+      library: ${{ steps.filter.outputs.library }}
+    steps:
+    - uses: actions/checkout@v4
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+      id: filter
+      with:
+        filters: |
+          library:
+            - 'java-bigquery/**'
+            - 'java-bigquery-jdbc/**'
+            - 'java-bigquerystorage/**'
+            - '.github/workflows/java-bigquery-jdbc-ci.yaml'
+            - 'google-auth-library-java/**/*.java'
+            - 'google-auth-library-java/**/pom.xml'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
+  units:
+    needs: filter
+    if: ${{ needs.filter.outputs.library == 'true' }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        java: [11, 17, 21, 25]
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-java@v4
+      with:
+        distribution: temurin
+        java-version: ${{matrix.java}}
+    - run: java -version
+    - run: .kokoro/build.sh
+      env:
+        JOB_TYPE: test
+  units-java8:
+    needs: filter
+    if: ${{ needs.filter.outputs.library == 'true' }}
+    # Building using Java 17 and run the tests with Java 8 runtime
+    name: "units (8)"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 8
+          distribution: temurin
+      - name: "Set jvm system property environment variable for surefire plugin (unit tests)"
+        # Maven surefire plugin (unit tests) allows us to specify JVM to run the tests.
+        # https://maven.apache.org/surefire/maven-surefire-plugin/test-mojo.html#jvm
+        run: echo "SUREFIRE_JVM_OPT=-Djvm=${JAVA_HOME}/bin/java -P !java17" >> $GITHUB_ENV
+        shell: bash
+      - uses: actions/setup-java@v4
+        with:
+          java-version: 17
+          distribution: temurin
+      - run: .kokoro/build.sh
+        env:
+          JOB_TYPE: test
+  windows:
+    needs: filter
+    if: ${{ needs.filter.outputs.library == 'true' }}
+    runs-on: windows-latest
+    steps:
+    - name: Support longpaths
+      run: git config --system core.longpaths true
+    - name: Support longpaths
+      run: git config --system core.longpaths true
+    - uses: actions/checkout@v4
+    - uses: actions/setup-java@v4
+      with:
+        distribution: temurin
+        java-version: 8
+    - run: java -version
+    - run: .kokoro/build.sh
+      env:
+        JOB_TYPE: test
+  dependencies:
+    needs: filter
+    if: ${{ needs.filter.outputs.library == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-java@v4
+      with:
+        distribution: temurin
+        java-version: 17
+    - run: .kokoro/dependencies.sh
+  javadoc:
+    needs: filter
+    if: ${{ needs.filter.outputs.library == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-java@v4
+      with:
+        distribution: temurin
+        java-version: 17
+    - run: java -version
+    - run: .kokoro/build.sh
+      env:
+        JOB_TYPE: javadoc
+  lint:
+    needs: filter
+    if: ${{ needs.filter.outputs.library == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: actions/setup-java@v4
+      with:
+        distribution: temurin
+        java-version: 17
+    - run: java -version
+    - run: .kokoro/build.sh
+      env:
+        JOB_TYPE: lint
+        HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+        BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+  required:
+    needs: [ units, units-java8, windows, dependencies, javadoc, lint ]
+    name: conditional-required-check
+    if: ${{ always() }} # Always run even if any "needs" jobs fail
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Fail if any previous failure
+        if: ${{ contains(needs.*.result, 'failure') }}
+        run: exit 1
+      - name: Success otherwise
+        run: echo "Success!"

.github/workflows/sdk-platform-java-shared_dependencies.yaml

@@ -40,4 +40,4 @@ jobs:
         mvn install -B -ntp -DskipTests -Pquick-build
     - name: Check the BOM content satisfies the upper-bound-check test case
       run: mvn -B -V -ntp verify -Pquick-build
-      working-directory: sdk-plaform-java/java-shared-dependencies/upper-bound-check
+      working-directory: sdk-platform-java/java-shared-dependencies/upper-bound-check

.github/workflows/sdk-platform-java-sonar.yaml

@@ -79,8 +79,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_FOR_GENERATOR }}
         run: |
-          mvn -B verify -Pquick-build \
-              -DenableFullTestCoverage \
+          mvn -B verify -Pquick-build -Djacoco.skip=false \
               -Penable-integration-tests \
               org.sonarsource.scanner.maven:sonar-maven-plugin:sonar \
               -Dsonar.projectKey=googleapis_google-cloud-java_generator \
@@ -92,7 +91,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN_FOR_SHOWCASE }}
         run: |
-          mvn -B clean verify -Pquick-build \
+          mvn -B clean verify -Pquick-build -Djacoco.skip=false \
               -DskipUnitTests \
               -Penable-integration-tests \
               -DenableShowcaseTestCoverage \

.kokoro/bigtable-conformance.sh

@@ -37,6 +37,7 @@ retry_with_backoff 3 10 \
     -DskipTests=true \
     -Dclirr.skip=true \
     -Denforcer.skip=true \
+    -Dcheckstyle.skip=true \
     -Dmaven.javadoc.skip=true \
     -Dgcloud.download.skip=true \
     -T 1C
@@ -48,7 +49,7 @@ set +e
 # Build the proxy
 pushd .
 cd java-bigtable/test-proxy
-mvn clean install -U -DskipTests
+mvn clean install -U -DskipTests -Dcheckstyle.skip=true
 popd
 
 declare -a configs=("default" "enable_all")

.kokoro/common.sh

@@ -21,6 +21,7 @@ excluded_modules=(
   'java-vertexai'
   'java-logging'
   'java-bigquery'
+  'java-bigquery-jdbc'
   'java-bigquerystorage'
   'java-datastore'
   'java-logging-logback'
@@ -39,6 +40,8 @@ excluded_modules=(
   'java-firestore'
   'java-bigtable'
   'java-pubsub'
+  'java-common-protos'
+  'java-iam'
 )
 
 function retry_with_backoff {

.kokoro/presubmit/bigquery-graalvm-native-presubmit.cfg

@@ -41,7 +41,4 @@ env_vars: {
   value: "java-bigquery"
 }
 
-env_vars: {
-  key: "INTEGRATION_TEST_ARGS"
-  value: "-pl !google-cloud-bigquery-jdbc"
-}
+