Flink1.15 source code reading - Flink annotations

flink-annotations Source code analysis

Flink-annotation Class diagram relation

This article will give a detailed introduction to flink Custom annotation module in , understand flink The role and use of annotations . centered flink In the source flink-annotations modular , And docs The relevant notes are @ConfigGroup and @ConfigGroups , It usually works on configuration classes ;@Documentation.OverrideDefault、@Documentation.Section、@Documentation.TableOption、@Documentation.SuffixOption,@Documentation.ExcludeFromDocumentation Acting on the configuration class ConfigOption Field , Make some changes to the configuration items . in addition , There's more 5 Kind of mark annotation ,@Experimental、@Internal、@Public、@PublicEvolving、@VisibleForTesting.

FlinkVersion

flink Version enumeration class , stay SQL/Table API During the upgrade , It is used for API Version control and migration testing .

docs annotation

@ConfigGroup

Class that specifies a set of configuration options . The name of the group will be generated as the basis html File name of the file , It's defined in {@link ConfigOptionsDocGenerator} in .
Such as @ConfigGroup(name = ExponentialDelayRestartStrategy",keyPrefix = “restart-strategy.exponential-delay”), Generated HTML The file named ExponentialDelayRestartStrategy , The configuration item names are all in restart-strategy.exponential-delay At the beginning .

@Target({
    })
@Internal
public @interface ConfigGroup {
    
    String name();
    String keyPrefix();
}

@ConfigGroups

Comments used on classes that contain configuration options , Allows options to be separated into different tables based on key prefixes . If the option key matches the group prefix , Then the configuration options are assigned to {@link ConfigGroup}. When a key matches multiple prefixes , The prefix with the longest matching time takes precedence . Options are never assigned to multiple groups . Options that do not match any groups are implicitly added to the default group .

The configuration items in a configuration class can be divided into different groups according to the prefix of the configuration item name , Generate multiple HTML file .
Such as ：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Internal
public @interface ConfigGroups {
    
    ConfigGroup[] groups() default {
    };
}

@Documentation

A collection of comments used to modify the behavior of the document generator .

@Documentation.OverrideDefault

/** *  Using this annotation means overwriting the document default  **/
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface OverrideDefault {
    
        String value();
    }

@Documentation.Section

/** *  Comments for configuring option fields , To include them in specific sections . Some option groups aggregated across option classes , Place each group in a private file . *  Parameters {@link Section#position()} Control the position in the generated table , Use a lower value to be placed at the top . The key to alphabetical sorting of fields in the same position . */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface Section {
    
        /** *  The configuration document should contain the part of this option . */
        String[] value() default {
    };

        /** *  The relative position of the option in its section . */
        int position() default Integer.MAX_VALUE;
    }

@Documentation.TableOption

/** *  Comments used to add metadata tags in table configuration options . * <p> * {@link TableOption#execMode()} Parameters indicate the execution mode of configuration work ( The batch 、 Stream processing or both ). */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface TableOption {
    
        ExecMode execMode();
    }

    /** *  The execution mode works according to the configuration  */
    public enum ExecMode {
    
        BATCH("Batch"),
        STREAMING("Streaming"),
        BATCH_STREAMING("Batch and Streaming");

        private final String name;

        ExecMode(String name) {
    
            this.name = name;
        }

        @Override
        public String toString() {
    
            return name;
        }
    }

@Documentation.SuffixOption

    /** *  Comments for configuring option fields or option classes , Mark them as suffix options ; *  for example , A configuration option , Where the key is only the suffix , Prefix is provided dynamically at runtime . */
    @Target({
    ElementType.FIELD, ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface SuffixOption {
    
        String value();
    }

@Documentation.ExcludeFromDocumentation

    /** *  Configure option fields or REST API The comment document on the message header used to exclude it  */
    @Target({
    ElementType.FIELD, ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface ExcludeFromDocumentation {
    
        /** *  Optional reasons to exclude it from the document . */
        String value() default "";
    }

@Experimental

/** *  This annotation is to mark that a class is still in the experimental stage  * * @author DeveloperZJQ * @since 2022-7-19 */
@Documented
@Target({
    ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Public
public @interface Experimental {
    
}

@Internal

/** *  Tags are used as a stable method  ,  Public api As an internal developer api * * @author DeveloperZJQ * @since 2022-7-19 */
@Documented
@Target({
    ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
@Public
public @interface Internal {
    
}

@Public

/** *  Marked class , It means a public and stable interface  * * @author DeveloperZJQ * @since 2022-7-19 */
@Documented
@Target(ElementType.TYPE)
@Public
public @interface Public {
    
}

@PublicEvolving

/** *  Annotations that mark classes and methods for public use , But the interface is constantly changing . * * @author DeveloperZJQ * @since 2022-7-19 */
@Documented
@Target({
    ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Public
public @interface PublicEvolving {
    
}

@VisibleForTesting

/** *  This annotation declares a function 、 Field 、 Constructors or entire types are only visible when testing . * * @author DeveloperZJQ * @since 2022-7-19 */
@Documented
@Target({
    ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Internal
public @interface VisibleForTesting {
    
}