Repository navigation
Conversation
There was a problem hiding this comment.
Code Review
This pull request updates the Javadocs across several classes, including BigQuery, Job, JobException, and JobStatus, to clarify job failure handling, retry behaviors, and exception throwing. Specifically, it explains that failed jobs are terminal, transient errors require a new job with a new JobId, and JobException is no longer thrown by current implementations in favor of BigQueryException. The review feedback recommends updating the documentation links to use the canonical domain cloud.google.com instead of docs.cloud.google.com to prevent unnecessary redirects.
| * polling the failed job again or reusing its {@link JobId}. See <a | ||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||
| * error codes</a> for guidance on retryable job errors. |
There was a problem hiding this comment.
Use the canonical domain cloud.google.com instead of docs.cloud.google.com for Google Cloud documentation links to avoid unnecessary redirects and ensure long-term link stability.
| * polling the failed job again or reusing its {@link JobId}. See <a | |
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a> for guidance on retryable job errors. | |
| * polling the failed job again or reusing its {@link JobId}. See <a | |
| * href="https://cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a> for guidance on retryable job errors. |
There was a problem hiding this comment.
Keeping docs.cloud.google.com here because it is now the canonical Google Cloud documentation domain: https://docs.cloud.google.com/bigquery/docs/managing-jobs and https://docs.cloud.google.com/bigquery/docs/errors return HTTP 200 with zero redirects and declare <link rel="canonical"> on docs.cloud.google.com, whereas the cloud.google.com equivalents return HTTP 301 redirecting to docs.cloud.google.com (consistent with #15110, #15116, and #15123).
| * failed query, invoke this method again so a new job is submitted. See <a | ||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||
| * error codes</a>. |
There was a problem hiding this comment.
Use the canonical domain cloud.google.com instead of docs.cloud.google.com for Google Cloud documentation links to avoid unnecessary redirects and ensure long-term link stability.
| * failed query, invoke this method again so a new job is submitted. See <a | |
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a>. | |
| * failed query, invoke this method again so a new job is submitted. See <a | |
| * href="https://cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a>. |
There was a problem hiding this comment.
Keeping docs.cloud.google.com here because it is now the canonical Google Cloud documentation domain: https://docs.cloud.google.com/bigquery/docs/managing-jobs and https://docs.cloud.google.com/bigquery/docs/errors return HTTP 200 with zero redirects and declare <link rel="canonical"> on docs.cloud.google.com, whereas the cloud.google.com equivalents return HTTP 301 redirecting to docs.cloud.google.com (consistent with #15110, #15116, and #15123).
| * new {@link JobId} when retrying a transient failure. See <a | ||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||
| * error codes</a>. |
There was a problem hiding this comment.
Use the canonical domain cloud.google.com instead of docs.cloud.google.com for Google Cloud documentation links to avoid unnecessary redirects and ensure long-term link stability.
| * new {@link JobId} when retrying a transient failure. See <a | |
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a>. | |
| * new {@link JobId} when retrying a transient failure. See <a | |
| * href="https://cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a>. |
There was a problem hiding this comment.
Keeping docs.cloud.google.com here because it is now the canonical Google Cloud documentation domain: https://docs.cloud.google.com/bigquery/docs/managing-jobs and https://docs.cloud.google.com/bigquery/docs/errors return HTTP 200 with zero redirects and declare <link rel="canonical"> on docs.cloud.google.com, whereas the cloud.google.com equivalents return HTTP 301 redirecting to docs.cloud.google.com (consistent with #15110, #15116, and #15123).
| * new {@link JobId} when retrying a transient failure. See <a | ||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | ||
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | ||
| * error codes</a>. |
There was a problem hiding this comment.
Use the canonical domain cloud.google.com instead of docs.cloud.google.com for Google Cloud documentation links to avoid unnecessary redirects and ensure long-term link stability.
| * new {@link JobId} when retrying a transient failure. See <a | |
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://docs.cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a>. | |
| * new {@link JobId} when retrying a transient failure. See <a | |
| * href="https://cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating jobs</a> | |
| * and <a href="https://cloud.google.com/bigquery/docs/errors">BigQuery API HTTP status and | |
| * error codes</a>. |
There was a problem hiding this comment.
Keeping docs.cloud.google.com here because it is now the canonical Google Cloud documentation domain: https://docs.cloud.google.com/bigquery/docs/managing-jobs and https://docs.cloud.google.com/bigquery/docs/errors return HTTP 200 with zero redirects and declare <link rel="canonical"> on docs.cloud.google.com, whereas the cloud.google.com equivalents return HTTP 301 redirecting to docs.cloud.google.com (consistent with #15110, #15116, and #15123).
| * {@link BigQueryError#getReason()} and submit a new job with a new {@link JobId}. See <a | ||
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating | ||
| * jobs</a>. |
There was a problem hiding this comment.
Use the canonical domain cloud.google.com instead of docs.cloud.google.com for Google Cloud documentation links to avoid unnecessary redirects and ensure long-term link stability.
| * {@link BigQueryError#getReason()} and submit a new job with a new {@link JobId}. See <a | |
| * href="https://docs.cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating | |
| * jobs</a>. | |
| * {@link BigQueryError#getReason()} and submit a new job with a new {@link JobId}. See <a | |
| * href="https://cloud.google.com/bigquery/docs/managing-jobs#repeat_jobs">Repeating | |
| * jobs</a>. |
There was a problem hiding this comment.
Keeping docs.cloud.google.com here because it is now the canonical Google Cloud documentation domain: https://docs.cloud.google.com/bigquery/docs/managing-jobs and https://docs.cloud.google.com/bigquery/docs/errors return HTTP 200 with zero redirects and declare <link rel="canonical"> on docs.cloud.google.com, whereas the cloud.google.com equivalents return HTTP 301 redirecting to docs.cloud.google.com (consistent with #15110, #15116, and #15123).
Documents asynchronous job retry semantics and clarifies the declared
JobExceptionexception type:BigQuery.create(JobInfo),BigQuery.query(...),BigQuery.queryArrow(..., JobId, ...),BigQuery.queryWithTimeout(...), andJobStatus.getError()that a failed job'sJobIdis terminal and transient job failures must be retried by submitting a new job with a newJobId, linking BigQuery's officialRepeating jobsandHTTP status and error codesdocumentation.JobExceptionand the six methods declaringthrows InterruptedException, JobException(BigQuery.queryx2,BigQuery.queryArrowx2,BigQuery.queryWithTimeout, andJob.getQueryResults) thatJobExceptionis declared for backwards compatibility only and is never thrown by current client implementations, which report failed jobs by throwingBigQueryExceptioninstead.Verified with
mvn fmt:check,checkstyle:check@checkstyle,test-compile, andjavadoc -Xdoclint:syntax,html,reference(zero warnings).