From cfab1b2e1d0c43ac7da804dfd07c0e83da0cfae5 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Sat, 21 Nov 2026 00:11:46 +0000 Subject: [PATCH] docs(bigquery): document Job.isDone network check and immutability semantics --- .../main/java/com/google/cloud/bigquery/Job.java | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java index 503c91dc3209..a276b17164e4 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Job.java @@ -196,8 +196,17 @@ public boolean exists() { } /** - * Checks if this job has completed its execution, either failing or succeeding. If the job does - * not exist this method returns {@code true}. + * Checks if this job has completed its execution, either failing or succeeding. + * + *

If this {@code Job} snapshot is already in {@link JobStatus.State#DONE}, this method returns + * {@code true} without making a network request. Otherwise, it issues a remote status check via + * {@link BigQuery#getJob(JobId, BigQuery.JobOption...)}. Because {@code Job} instances are + * immutable, calling {@code isDone()} does not update this object's status, error, or statistics. + * After {@code isDone()} returns {@code true}, call {@link #reload(JobOption...)} or {@link + * BigQuery#getJob(JobId, BigQuery.JobOption...)} to read the completed job's state. + * + *

If the job no longer exists, this method returns {@code true}. For most blocking waits, + * prefer {@link #waitFor(RetryOption...)}. * *

Example of waiting for a job until it reports that it is done. * @@ -205,6 +214,7 @@ public boolean exists() { * while (!job.isDone()) { * Thread.sleep(1000L); * } + * Job completedJob = bigquery.getJob(job.getJobId()); * } * * @return {@code true} if this job is in {@link JobStatus.State#DONE} state or if it does not