[FLINK-23064][flink-connectors][flink-formats] Expose connector/format config options as @PublicEvolving #16334

Airblader · 2021-06-30T12:09:45Z

What is the purpose of the change

This exposes ConfigOption<>s for connectors and formats by marking them as @PublicEvolving. Where applicable we reduce the exposed API surface by refactoring constants, validation helpers, and utilities into another class (annotated with @Internal).

This is done as part of FLIP-129 to allow users to refer to these options when creating table (and format) descriptors.

(!) Review on a per-commit basis is encouraged. Each commit touches a specific connector/format. Otherwise the changes are fairly technical.

In a follow-up step (separate sub-task) we'll move these classes into a common location (package) for easier discovery.

Verifying this change

This change is a trivial rework / code cleanup without any test coverage.

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

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

Documentation

Does this pull request introduce a new feature? no
If yes, how is the feature documented? not applicable

flinkbot · 2021-06-30T12:13:01Z

Thanks a lot for your contribution to the Apache Flink project. I'm the @flinkbot. I help the community
to review your pull request. We will use this comment to track the progress of the review.

Automated Checks

Last check on commit f202241 (Wed Jun 30 12:13:01 UTC 2021)

Warnings:

No documentation files were touched! Remember to keep the Flink docs up to date!

_{Mention the bot in a comment to re-run the automated checks.}

Review Progress

❓ 1. The [description] looks good.
❓ 2. There is [consensus] that the contribution should go into to Flink.
❓ 3. Needs [attention] from.
❓ 4. The change fits into the overall [architecture].
❓ 5. Overall code [quality] is good.

Please see the Pull Request Review Guide for a full explanation of the review process.

The Bot is tracking the review progress through labels. Labels are applied according to the order of the review items. For consensus, approval by a Flink committer of PMC member is required

Bot commands

The @flinkbot bot supports the following commands:

@flinkbot approve description to approve one or more aspects (aspects: description, consensus, architecture and quality)
@flinkbot approve all to approve all aspects
@flinkbot approve-until architecture to approve everything until architecture
@flinkbot attention @username1 [@username2 ..] to require somebody's attention
@flinkbot disapprove architecture to remove an approval you gave earlier

flinkbot · 2021-06-30T12:31:46Z

CI report:

f202241 UNKNOWN
c484b19 Azure: FAILURE
717632f Azure: PENDING

Bot commands

The @flinkbot bot supports the following commands:

@flinkbot run travis re-run the last Travis build
@flinkbot run azure re-run the last Azure build

twalthr

Thanks for the PR @Airblader. I added a bunch of comments to further ensure consistency. It is very helpful to see all options at once in such a PR to unify them further.

...ain/java/org/apache/flink/streaming/connectors/elasticsearch/table/ElasticsearchOptions.java

twalthr · 2021-07-08T10:07:22Z

...ctor-hbase-base/src/main/java/org/apache/flink/connector/hbase/options/HBaseOptionsUtil.java

+
+/** Utilities for {@link HBaseOptions}. */
+@Internal
+public class HBaseOptionsUtil {


is default scope possible for these utilities that should always be next to the factory in the same package?

I made it default scope where possible for now, but it isn't possible for all.

twalthr · 2021-07-08T10:09:13Z

...ctor-hbase-base/src/main/java/org/apache/flink/connector/hbase/options/HBaseOptionsUtil.java

+        return hbaseClientConf;
+    }
+
+    private static Properties getHBaseClientProperties(Map<String, String> tableOptions) {


could we add a [hotfix] commit to replace this prefix magic? We can replace this with a map option type nowadays. Also for the Kafka connector and maybe also for the Kinesis connector. Otherwise the new Option classes are not very useful if they are less complete.

...rs/flink-connector-jdbc/src/main/java/org/apache/flink/connector/jdbc/table/JdbcOptions.java

...stry/src/main/java/org/apache/flink/formats/avro/registry/confluent/RegistryAvroOptions.java

twalthr · 2021-07-08T10:24:54Z

...table-api-java-bridge/src/main/java/org/apache/flink/table/factories/DataGenOptionsUtil.java

+
+/** Utilities for {@link DataGenOptions}. */
+@Internal
+public class DataGenOptionsUtil {


Actually, the task of the Factory is to translate options. We could also get rid of most of util classes and move the code to the factory itself.

For DataGen I'm hesitant to do so because the factory is marked as PublicEvolving (and these would have to be visible because they're accessed from other places, too). Most other factories (of "real connectors") are marked Internal, though. I'm not sure if we can just changes this to Internal now? If not I'd probably keep it separate for now.

twalthr · 2021-07-08T10:27:04Z

...k-table/flink-table-runtime/src/main/java/org/apache/flink/table/formats/raw/RawOptions.java

+@PublicEvolving
+public class RawOptions {
+
+    public static final String BIG_ENDIAN = "big-endian";


we should improve our ConfigOption design to allow enums with special characters, it doesn't help if we support enum type but nobody wants to use them and they use string type again

...ctor-kafka/src/main/java/org/apache/flink/streaming/connectors/kafka/table/KafkaOptions.java

Airblader · 2021-07-08T11:56:21Z

Thanks for the review @twalthr. I think all your points are valid, but I'd like to address the rest of them in a separate PR. To summarize:

Use the new map config option type in HBase
Convert string constants to enums where possible
(Remove Utils classes afterwards if possible by moving things into the factory directly)

twalthr

Some last minor feedback. Good to merge in the next iteration. Let me know if you have time otherwise I can also perform them during merging.

twalthr · 2021-07-08T12:51:26Z

...hbase-base/src/main/java/org/apache/flink/connector/hbase/options/HBaseConnectorOptions.java

+                    .defaultValue(3)
+                    .withDescription("the max retry times if lookup database failed.");
+
+    public static final ConfigOption<Integer> SINK_PARALLELISM = FactoryUtil.SINK_PARALLELISM;


private constructor is missing

twalthr · 2021-07-08T12:54:54Z

...src/main/java/org/apache/flink/connector/jdbc/catalog/factory/JdbcCatalogFactoryOptions.java

 import org.apache.flink.configuration.ConfigOption;
 import org.apache.flink.configuration.ConfigOptions;
 import org.apache.flink.connector.jdbc.catalog.JdbcCatalog;
 import org.apache.flink.table.catalog.CommonCatalogOptions;

 /** {@link ConfigOption}s for {@link JdbcCatalog}. */
-@Internal
+@PublicEvolving


rename to JdbcCatalogOptions? or leave it @Internal for now

twalthr · 2021-07-08T12:56:13Z

flink-formats/flink-json/src/main/java/org/apache/flink/formats/json/JsonFormatOptions.java

+        FAIL,
+        DROP,
+        LITERAL
+    }


private constructor missing

twalthr · 2021-07-08T13:04:04Z

...c/main/java/org/apache/flink/streaming/connectors/kafka/table/KafkaConnectorOptionsUtil.java

@@ -741,8 +550,9 @@ private static boolean hasKafkaClientProperties(Map<String, String> tableOptions
     * Creates an array of indices that determine which physical fields of the table schema to
     * include in the value format.
     *
-     * <p>See {@link #VALUE_FORMAT}, {@link #VALUE_FIELDS_INCLUDE}, and {@link #KEY_FIELDS_PREFIX}
-     * for more information.
+     * <p>See {@link KafkaConnectorOptions#VALUE_FORMAT}, {@link


We could have avoided these changes with static imports.

…ving This closes apache#16334.

…volving

…fig options as PublicEvolving

…volving

…Evolving

… PublicEvolving

…ving This closes apache#16334.

rmetzger added the review=description? label Jun 30, 2021

Airblader force-pushed the FLINK-23064 branch 2 times, most recently from 9b27c8b to 8088724 Compare June 30, 2021 12:22

rmetzger added the component=TableSQL/API label Jun 30, 2021

Airblader force-pushed the FLINK-23064 branch 4 times, most recently from 34987c6 to 5a7928b Compare July 7, 2021 06:22

Airblader marked this pull request as ready for review July 8, 2021 08:50

twalthr reviewed Jul 8, 2021

View reviewed changes

Airblader force-pushed the FLINK-23064 branch from 5a7928b to e7dd800 Compare July 8, 2021 11:55

Airblader requested a review from twalthr July 8, 2021 11:55

twalthr requested changes Jul 8, 2021

View reviewed changes

twalthr pushed a commit to Airblader/flink that referenced this pull request Jul 9, 2021

[FLINK-23064][connector-kafka] Expose connector options as PublicEvol…

c484b19

…ving This closes apache#16334.

twalthr force-pushed the FLINK-23064 branch from e7dd800 to c484b19 Compare July 9, 2021 09:49

Airblader added 11 commits July 12, 2021 08:19

[FLINK-23064][connector-elasticsearch] Make connector options PublicE…

1cf8515

…volving

[FLINK-23064][connector-hbase] Make connector options PublicEvolving

9349c6f

[FLINK-23064][connector-kinesis] Make connector options PublicEvolving

1ea28fc

[FLINK-23064][connector-jdbc] Create PublicEvolving JdbcOptions

73b6fc0

[FLINK-23064][format-json] Make JsonOptions PublicEvolving

5d945b4

[FLINK-23064][format-avro][format-avro-confluent-registry] Expose con…

7e64abc

…fig options as PublicEvolving

[FLINK-23064][format-csv] Expose CsvOptions as PublicEvolving

21330bb

[FLINK-23064][table-api-java-bridge] Expose DataGenOptions as PublicE…

865e71f

…volving

[FLINK-23064][table-runtime-blink] Expose FileSystemOptions as Public…

fbd98ea

…Evolving

[FLINK-23064][table-runtime-blink] Expose options for "raw" format as…

d52a12d

… PublicEvolving

[FLINK-23064][connector-kafka] Expose connector options as PublicEvol…

717632f

…ving This closes apache#16334.

twalthr force-pushed the FLINK-23064 branch from c484b19 to 717632f Compare July 12, 2021 06:22

twalthr closed this in 5703e2f Jul 12, 2021

jnh5y pushed a commit to jnh5y/flink that referenced this pull request Dec 18, 2023

[FLINK-23064][connector-kafka] Expose connector options as PublicEvol…

4735aca

…ving This closes apache#16334.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[FLINK-23064][flink-connectors][flink-formats] Expose connector/format config options as @PublicEvolving #16334

[FLINK-23064][flink-connectors][flink-formats] Expose connector/format config options as @PublicEvolving #16334

Airblader commented Jun 30, 2021 •

edited

flinkbot commented Jun 30, 2021

flinkbot commented Jun 30, 2021 •

edited

twalthr left a comment

twalthr Jul 8, 2021

Airblader Jul 8, 2021

twalthr Jul 8, 2021

twalthr Jul 8, 2021

Airblader Jul 8, 2021

twalthr Jul 8, 2021

Airblader commented Jul 8, 2021

twalthr left a comment

twalthr Jul 8, 2021

twalthr Jul 8, 2021

twalthr Jul 8, 2021

twalthr Jul 8, 2021

[FLINK-23064][flink-connectors][flink-formats] Expose connector/format config options as @PublicEvolving #16334

[FLINK-23064][flink-connectors][flink-formats] Expose connector/format config options as @PublicEvolving #16334

Conversation

Airblader commented Jun 30, 2021 • edited

What is the purpose of the change

Verifying this change

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

Documentation

flinkbot commented Jun 30, 2021

Automated Checks

Review Progress

flinkbot commented Jun 30, 2021 • edited

CI report:

twalthr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Airblader commented Jul 8, 2021

twalthr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Airblader commented Jun 30, 2021 •

edited

flinkbot commented Jun 30, 2021 •

edited