Skip to content

docs(bigquery): document Job.isDone network check and immutability semantics - #15127

Open
lqiu96 wants to merge 1 commit into
googleapis:mainfrom
lqiu96:docs/bq-2d-document-job-isdone
Open

lqiu96 wants to merge 1 commit into
googleapis:mainfrom
lqiu96:docs/bq-2d-document-job-isdone

Conversation

@lqiu96

@lqiu96 lqiu96 commented Nov 21, 2026

Copy link
Copy Markdown
Member

Clarifies Job.isDone() Javadoc so callers do not assume it is a local getter or mutates the Job instance in place:

  • Explains that isDone() returns true locally only when the snapshot is already in JobStatus.State.DONE, and otherwise issues a remote BigQuery.getJob(...) status check.
  • Notes that Job is immutable, so callers must call reload() or BigQuery.getJob(job.getJobId()) after isDone() returns true to read final status, errors, or statistics.
  • Updates the while (!job.isDone()) example to capture the completed job snapshot and points callers to waitFor() for typical blocking waits.

Verified with mvn fmt:check, checkstyle:check@checkstyle, test-compile, and javadoc -Xdoclint:syntax,html,reference (zero warnings).

@lqiu96
lqiu96 requested review from a team as code owners November 21, 2026 00:12

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request updates the Javadoc for the isDone() method in Job.java to clarify its behavior regarding immutability and remote status checks, and updates the accompanying code example. The reviewer suggested using job.reload() instead of bigquery.getJob(job.getJobId()) in the example code to make it more idiomatic and self-contained.

* while (!job.isDone()) {
* Thread.sleep(1000L);
* }
* Job completedJob = bigquery.getJob(job.getJobId());

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

In the Javadoc example, using job.reload() is more idiomatic and self-contained than bigquery.getJob(job.getJobId()) because the job instance already has access to the underlying service and does not require an external bigquery variable to be defined in the example context.

Suggested change
* Job completedJob = bigquery.getJob(job.getJobId());
* Job completedJob = job.reload();
References
  1. Update stale Javadoc comments to reflect new method behavior for improved clarity, rather than removing them.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant