Flink Factory接口源码解析

Flink Table源码中的Factory接口

1. 源码加上中文注释

package org.apache.flink.table.factories;

import org.apache.flink.annotation.PublicEvolving;
import org.apache.flink.configuration.ConfigOption;

import java.util.Set;

/**
 * Flink Table & SQL API中从键值对列表中创建对象实例的各种工厂的基本接口。
 *
 * 一个工厂通过Class和factoryIdentifier()来唯一标识。

 * 可用工厂的列表是通过Java的Service Provider Interfaces (SPI)来发现的。实现这个接口的类可以添加到JAR文件的META_INF/services/org.apache.flink.table.factories.Factory中。

 * 每个工厂都声明了一组必需的和可选的选项。此信息在发现过程中不会被使用，但在生成文档和执行验证时非常有用。一个工厂可能会发现更多的（嵌套的）工厂，嵌套工厂的选项不能在该工厂的选项集中声明。

 * 每个工厂在返回实例之前进行验证是其责任。

 * 为了保持一致性，建议使用以下风格的ConfigOption键名：

 * 尽量重用键名。可以参考其他工厂实现。
 * 键名应以小写字母声明。使用"-"来分隔单词，而不是点号或驼峰命名法。
 * 适当时，键名应具有层次结构。考虑如何在JSON或YAML文件中定义这样的层次结构（例如sink.bulk-flush.max-actions）。
 * 在层次结构的情况下，尽量不要再次使用高级别作为键名（例如，使用sink.partitioner而不是sink.sink-partitioner），以保持键的长度。
 * 可以模板化的键名，例如引用特定列的键名，应使用"#"作为占位符。例如，使用fields.#.min。
 */
@PublicEvolving
public interface Factory {

    /**
     * 在相同工厂接口中返回一个唯一的标识符。

     * 为了保持一致性，标识符应声明为一个小写字母单词（例如kafka）。如果存在多个不同版本的工厂，则应使用"-"附加一个版本（例如elasticsearch-7）。
     */
    String factoryIdentifier();

    /**
     * 返回该工厂实现所需的ConfigOption集合，除了optionalOptions()。

     * 更多信息请参见Factory的文档。
     */
    Set<ConfigOption<?>> requiredOptions();

    /**
     * 返回该工厂实现所需的ConfigOption集合，除了requiredOptions()。

     * 更多信息请参见Factory的文档。
     */
    Set<ConfigOption<?>> optionalOptions();
}

2. 接口中方法用法及其代码示例

factoryIdentifier()

该方法返回一个在相同工厂接口中唯一的标识符。

用法示例：

public class MyFactory implements Factory {
    @Override
    public String factoryIdentifier() {
        return "my-factory";
    }
}

requiredOptions()

该方法返回一个Set<ConfigOption<?>>，表示该工厂实现需要的配置选项集合，这些选项是必需的。

用法示例：

public class MyFactory implements Factory {
    @Override
    public Set<ConfigOption<?>> requiredOptions() {
        Set<ConfigOption<?>> options = new HashSet<>();
        options.add(ConfigOptions.key("option1").stringType().defaultValue("value1"));
        options.add(ConfigOptions.key("option2").intType().defaultValue(10));
        return options;
    }
}

optionalOptions()

该方法返回一个Set<ConfigOption<?>>，表示该工厂实现可以使用的配置选项集合，这些选项是可选的。

用法示例：

public class MyFactory implements Factory {
    @Override
    public Set<ConfigOption<?>> optionalOptions() {
        Set<ConfigOption<?>> options = new HashSet<>();
        options.add(ConfigOptions.key("option3").booleanType().defaultValue(true));
        options.add(ConfigOptions.key("option4").doubleType().defaultValue(3.14));
        return options;
    }
}

3. 源码适用场景

Flink Table中的Factory接口用于创建对象实例。该接口适用于以下场景：

• 当需要根据一组键值对配置参数来创建对象实例时，可以使用Factory接口。
• Factory接口提供了必需和可选的配置选项集合，可以通过这些选项指定对象创建过程中所需的参数。
• 使用Factory接口可以在不修改代码的情况下添加新的工厂实现，并且可以通过SPI机制自动发现。

4. 官方链接

官方文档：https://nightlies.apache.org/flink/flink-docs-stable/api/java/org/apache/flink/table/factories/Factory.html