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