【Flink源码分析】： Flink-annotation注解分析

文章目录

flink-annotations源码分析

Flink-annotation类图关系

flink annotations下包含了docs相关的三种注解：ConfigGroup，ConfigGroups和Documentation。然后还有其他5种注解：Experimental，Internal， Public，PublicEnvolving和VisableForTesting。下面分别简单地介绍下这些注解的作用。

docs下的三个注解

• ConfigGroup
• ConfigGroups
• Documentation

ConfigGroup

package org.apache.flink.annotation.docs;

import org.apache.flink.annotation.Internal;

import java.lang.annotation.Target;

/**
 * A class that specifies a group of config options. The name of the group will be used as the basis for the
 * filename of the generated html file, as defined in {@link ConfigOptionsDocGenerator}.
 *
 * @see ConfigGroups
 */
@Target({})
@Internal
//注解的作用是指定一组配置选项的类。该组的name将被用作生成的HTML文件的文件名。
public @interface ConfigGroup {
  String name();
  String keyPrefix();
}

COnfigGroups

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

会按照key的前缀进行区分，分成不同的组，按照最长匹配前缀规则进行匹配

Documentation

主要用于生成文档

public final class Documentation {

  /**
   * Annotation used on config option fields to override the documented default.
   */
  @Target(ElementType.FIELD)
  @Retention(RetentionPolicy.RUNTIME)
  @Internal
  public @interface OverrideDefault {
    String value();
  }

  /**
   * Annotation used on config option fields to include them in the "Common Options" section.
   *
   * <p>The {@link CommonOption#position()} argument controls the position in the generated table, with lower values
   * being placed at the top. Fields with the same position are sorted alphabetically by key.
   */
  @Target(ElementType.FIELD)
  @Retention(RetentionPolicy.RUNTIME)
  @Internal
  public @interface CommonOption {
    int POSITION_MEMORY = 10;
    int POSITION_PARALLELISM_SLOTS = 20;
    int POSITION_FAULT_TOLERANCE = 30;
    int POSITION_HIGH_AVAILABILITY = 40;
    int POSITION_SECURITY = 50;

    int position() default Integer.MAX_VALUE;
  }

  /**
   * Annotation used on config option fields to exclude the config option from documentation.
   */
  @Target(ElementType.FIELD)
  @Retention(RetentionPolicy.RUNTIME)
  @Internal
  public @interface ExcludeFromDocumentation {
    /**
     * The optional reason why the config option is excluded from documentation.
     */
    String value() default "";
  }

  private Documentation(){
  }
}

annotation下的注解

• Experimental
• Internal
• Public
• PublicEvolving
• VisibleForTesting

Experimental

标注这个类只是试验阶段使用的，不是稳定版本，也没有battle-test(久经沙场的测试) ,后面还有可能会移除掉

@Documented
@Target(ElementType.TYPE)
@Public
public @interface Experimental {
}

Internal

将稳定的公共API中的方法标记为内部开发人员API的接口。
开发者api是稳定的，但内部的Flink，可能会改变不同的版本。

@Documented
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR })
@Public
public @interface Internal {
}

Public

@Documented
@Target(ElementType.TYPE)
@Public
public @interface Public {}

标注类为开放和稳定的。类，方法或者属性被这个这个注解修饰时，表示在小版本迭代中，都维持稳定。

PublicEvolving
@Documented
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR })
@Public
public @interface PublicEvolving {
}

该注解用来标注公共的但有不断发展的接口依赖的类或者方法。带有此注释的类和方法用于公共使用，并且具有稳定的行为。但是，它们的接口和签名不被认为是稳定的，并且当跨版本时可能会变化。

VisibleForTesting

@Documented
@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR })
@Internal
public @interface VisibleForTesting {}

这个注解申明有些函数，属性，构造函数或整个类型值是在test时才是可见的。当例如方法应该是编码阶段，通常附加这个注释（因为它不打算在外部调用），但不能声明为私有，因为一些测试需要访问它。