[backport camel-4.18.x] CAMEL-24574: camel-google-bigquery - document ${name} substitution and warn on non-identifier values

[oscerd]

Backport of #26007 to camel-4.18.x.

This one is not a straight cherry-pick — it needed manual conflict resolution, so it is not claiming the backport review exemption. The Java is a mechanical port; the documentation needed adapting to this branch. Details below.

What it does

The google-bigquery-sql endpoint accepts two placeholder forms that behave differently: @name is bound as a BigQuery named query parameter, while ${name} is spliced into the query text verbatim. Both are needed, because BigQuery named parameters can bind values but cannot bind identifiers, so a dataset or table name can only be supplied through ${name}.

The documentation described ${name} only as "extracted from message headers and formed the translated query", which does not convey that the substitution is literal text rather than parameter binding, and gave no guidance to use @name for values.

This adds a Query Placeholders section documenting the split, and reports at WARN level when a ${name} substitution does not have the shape of a BigQuery identifier. Only the placeholder name is logged, never the substituted value.

The substitution behaviour itself is unchanged, so no upgrade-guide entry is needed (and per project convention upgrade guides live on main regardless).

Divergences from the main commit

1. The catalog doc mirror is dropped. catalog/camel-catalog/src/generated/resources/org/apache/camel/catalog/docs/google-bigquery-sql-component.adoc does not exist on camel-4.18.x — this branch carries 1 file under that directory versus 702 on camel-4.22.x, so the per-component catalog doc mirror is not maintained here. Adding it would introduce a file the branch does not otherwise ship.
2. AsciiDoc fence style adapted. This branch uses long-dash delimiters throughout that file (12 of them, zero ----). The cherry-pick would have introduced three ---- fences; they were converted so the file stays internally consistent. Purely cosmetic — both forms are valid AsciiDoc.

All three Java files are byte-identical to main. Verified by direct comparison against origin/main: SqlHelper.java, SqlHelperIdentifierTest.java, SqlHelperTest.java. No behavioural difference from the change reviewed on #26007.

Verification

• Resulting changeset: 4 files, +142 −4. No conflict markers, no ---- fences remaining.
• Module build green: 9 unit tests, 0 failures.

Claude Code on behalf of oscerd

[gnodet]

Straight cherry-pick backport of #26007 to camel-4.18.x. Source-file diffs are identical to the original (only context line-numbers and pre-existing AsciiDoc delimiter style differ between branches). The missing catalog/ generated file is expected — that mirror doesn't exist on camel-4.18.x. Approving without fresh review per backport policy.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

Claude Code on behalf of Guillaume Nodet