【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时才是可见的。当例如方法应该是编码阶段，通常附加这个注释（因为它不打算在外部调用），但不能声明为私有，因为一些测试需要访问它。