【Flink基础】-- 源码中的注解

时间：2023-01-14 07:56:20


1.Flink自定义注解级别

在升级 Flink版本至 1.15.3时，偶然遇到了一个异常，然后就准备详细了解下源码中的注解。设计注解的初衷：为了更好地进行代码和版本管理，Flink使用了Java的注解特性自定义了注解，对代码进行增强说明。

注解的使用场景：

  • 提供信息给编译器：编译器可以利用注解来探测错误和警告信息
  • 编译阶段时的处理：软件工具可以利用注解信息来生成代码，HTML文档或其他相应处理
  • 运行时的处理：某些注解可以在程序运行时接受代码的提取

Flink 注解源码包的位置：org.apache.flink.annotation.*



【Flink基础】-- 源码中的注解


Flink的自定义注解有如下几种：

1.2代码相关注解

在阅读Flink源码时，记住常用的有@internal、@public、@publicevolving这三个注释就够了。

1.2.1 @Experimental

该注解标识类仅供实验目的使用。添加该注解的类通常不会使用@Public和 @PublicEvolving注解

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.2 @VIsibleForTesting

该注解声明类、属性、构造方法、或整个类型，其可见性只对测试目的开放。 这个注解的典型场景是， 当一个方法是应当别申明为私有（不打算被外部调用）而无法申明为私有时(因为某些测试需要访问它)，通常会附加此注释。

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.3 @Internal

该注解标识方法是稳定的，或公有的API是一个内部开发者级别的API。开发者级别的API是稳定的但只对Flink内部开放，但可能会通过版本发布改变。

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.4 @Public

该注解标识类是公有的，接口是稳定的。使用该注解的类、方法、属性在小版本中(1.0,1.1,1.2)是稳定的,但在大版本(1.0,2.0,3.0)中可能会破坏。

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

1.2.5 @PublicEvolving

该注解标识类和方法是公有的，但是有不断演变的接口。添加该注解的类和方法通常不会使用Public

package org.apache.flink.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;

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

2.文档配置相关注解

文档相关的配置注释，主要在生成配置html文件的时候使用，便于配置文件的管理,具体使用可以参考ConfigOptionsDocGenerator类。

import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.getDescription;
import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.getDocumentedKey;
import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.stringifyDefault;
import static org.apache.flink.docs.configuration.ConfigOptionsDocGenerator.typeToHtml;

2.1 @ConfigGroup

改注解标识一个类指定了一组配置项

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

2.2 @configGroups

改注解标识一个类包含多个配置项，

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

2.3 Documentation.OverrideDefault

该注解用于配置项字段，标识覆盖默认值

@Target(ElementType.FIELD)
  @Retention(RetentionPolicy.RUNTIME)
  @Internal
  public @interface OverrideDefault {
      String value();
  }

2.4 Documentation.CommonOption

该注解用于配置项字段，将配置项添加到CommonOption Section中。 CommonOption.position参数控制生成html页面中表的位置，较低的值会置于顶部

@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;
  }

2.5 Documentation.ExcludeFromDocumentation

该注解用于配置项字段，用于从文档中排除配置选项。

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

3.Java注解分类

注解按生命周期来划分可分为3类：

3.1 RetentionPolicy.SOURCE

注解只保留在源文件，当Java文件编译成class文件的时候，注解被遗弃；

3.2 RetentionPolicy.CLASS

注解被保留到class文件，但jvm加载class文件时候被遗弃，这是默认的生命周期；

3.3 RetentionPolicy.RUNTIME

注解不仅被保存到class文件中，jvm加载class文件之后，仍然存在；

标签：

相关文章