[FLINK-39764] Support dynamic table options in Table API

[HundalTaran]

What is the purpose of the change

Currently, dynamic table options (e.g., overriding scan.startup.mode at query time) are only available through the SQL API via OPTIONS hints:
sql: SELECT id, name FROM kafka_table1 /*+ OPTIONS('scan.startup.mode'='earliest-offset') */;
Table API users who want to override table options dynamically have no equivalent mechanism. They are forced to drop into tEnv.executeSql() with raw SQL strings, which negates the purpose of using the type-safe Table API.

Brief change log

Add a new overloaded method from(String path, Map<String, String> dynamicOptions) to the TableEnvironment interface. This provides Table API users with the same dynamic option override capability that SQL users have via OPTIONS hints.

Verifying this change

Added 6 test methods: testFromWithDynamicOptions : Verifies dynamic options are merged with existing table options testFromWithDynamicOptionsOverridesExisting : Verifies dynamic options override static options on key conflict | testFromWithEmptyDynamicOptions : Verifies empty map is a no-op, original options preserved | testFromWithDynamicOptionsOnViewThrows : Verifies ValidationException when applied to a view testFromWithDynamicOptionsDisabledThrows : Verifies ValidationException when config is disabled testFromWithDynamicOptionsTableNotFound : Verifies ValidationException for non-existent table

Does this pull request potentially affect one of the following parts:

• Dependencies (does it add or upgrade a dependency): (yes / no) - no
• The public API, i.e., is any changed class annotated with @Public(Evolving): (yes / no) - yes
• The serializers: (yes / no / don't know) - no
• The runtime per-record code paths (performance sensitive): (yes / no / don't know) - no
• Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (yes / no / don't know) - no
• The S3 file system connector: (yes / no / don't know) - no

Documentation

• Does this pull request introduce a new feature? (yes / no) - no
• If yes, how is the feature documented? (not applicable / docs / JavaDocs / not documented) - no

---

Was generative AI tooling used to co-author this PR?

Yes, had taken help from kiro.

[flinkbot]

CI report:

• 8b90b99 Azure: SUCCESS

Bot commands

The @flinkbot bot supports the following commands:

• @flinkbot run azure re-run the last Azure build

[HundalTaran]

Thanks for the review @davidradl! I've updated the Javadoc to address all your points:

1. Materialized tables – clarified that the method supports both regular catalog tables and materialized tables (the implementation in ContextResolvedTable.copy() already handles this case). Only views are rejected.

2. Invalid options – added a paragraph explaining that option validation is lazy (happens at planning/execution time, not at from() call time), consistent with how SQL OPTIONS hints work.

3. Why Map<String, String> – added an explanation that this is consistent with the entire Table/SQL ecosystem (CatalogTable.getOptions(), DDL WITH clauses, SQL OPTIONS hints all use string key-value pairs). Typed values are parsed by the connector factory.

4. Documentation – added a section to the Table API docs (common.md) with examples showing why and how to use this feature.