0
# Flink Annotations
1

2
Flink Annotations is Apache Flink's annotation library that provides API stability annotations for marking classes and interfaces with different stability levels. It includes comprehensive annotations for Public, PublicEvolving, Experimental, Internal, and VisibleForTesting classifications, along with version management utilities and documentation generation support.
3

4
## Package Information
5

6
- **Package Name**: flink-annotations
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.apache.flink</groupId>
13
    <artifactId>flink-annotations</artifactId>
14
    <version>2.1.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.apache.flink.annotation.Public;
22
import org.apache.flink.annotation.PublicEvolving;
23
import org.apache.flink.annotation.Experimental;
24
import org.apache.flink.annotation.Internal;
25
import org.apache.flink.annotation.VisibleForTesting;
26
import org.apache.flink.FlinkVersion;
27
```
28

29
For documentation annotations:
30

31
```java
32
import org.apache.flink.annotation.docs.Documentation;
33
import org.apache.flink.annotation.docs.ConfigGroup;
34
import org.apache.flink.annotation.docs.ConfigGroups;
35
import org.apache.flink.annotation.docs.FlinkJsonSchema;
36
```
37

38
## Basic Usage
39

40
```java
41
import org.apache.flink.annotation.Public;
42
import org.apache.flink.annotation.PublicEvolving;
43
import org.apache.flink.FlinkVersion;
44

45
// Mark a class as stable public API
46
@Public
47
public class MyPublicClass {
48
    // Stable method
49
    public void stableMethod() { }
50
    
51
    // Method with evolving signature
52
    @PublicEvolving
53
    public void evolvingMethod(int param) { }
54
}
55

56
// Version management
57
FlinkVersion current = FlinkVersion.current();
58
boolean isNewer = FlinkVersion.v2_1.isNewerVersionThan(FlinkVersion.v2_0);
59
Optional<FlinkVersion> version = FlinkVersion.byCode("2.1");
60
```
61

62
## Architecture
63

64
Flink Annotations is organized into three main components:
65

66
- **API Stability Annotations**: Core annotations (`@Public`, `@PublicEvolving`, `@Experimental`, `@Internal`, `@VisibleForTesting`) for marking interface stability levels
67
- **Version Management**: `FlinkVersion` enum providing version comparison and range operations for migration and compatibility testing
68
- **Documentation Generation**: Specialized annotations in the `docs` package for controlling configuration documentation generation
69

70
## Capabilities
71

72
### API Stability Annotations
73

74
Core annotations for marking API stability levels across Apache Flink codebase.
75

76
```java { .api }
77
@Target(ElementType.TYPE)
78
@Retention(RetentionPolicy.RUNTIME)
79
@Public
80
@interface Public {}
81

82
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
83
@Retention(RetentionPolicy.RUNTIME)
84
@Public
85
@interface PublicEvolving {}
86

87
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
88
@Retention(RetentionPolicy.RUNTIME)
89
@Public
90
@interface Experimental {}
91

92
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
93
@Retention(RetentionPolicy.RUNTIME)
94
@Public
95
@interface Internal {}
96

97
@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
98
@Internal
99
// Note: Uses default retention policy (RetentionPolicy.CLASS)
100
@interface VisibleForTesting {}
101
```
102

103
**Usage Examples:**
104

105
```java
106
// Stable public API - guaranteed compatibility across minor releases
107
@Public
108
public class DataStreamAPI {
109
    public void map() { }
110
}
111

112
// Public API but interface may evolve
113
@Public
114
public class StreamingContext {
115
    @PublicEvolving
116
    public void experimentalFeature() { }
117
}
118

119
// Experimental feature that may change or be removed
120
@Experimental
121
public class NewStreamProcessor {
122
    public void process() { }
123
}
124

125
// Internal API for framework use only
126
@Internal
127
public class RuntimeHelper {
128
    public void internalMethod() { }
129
}
130

131
// Method visible only for testing purposes
132
public class MyService {
133
    @VisibleForTesting
134
    void packagePrivateMethod() { }
135
}
136
```
137

138
### Version Management
139

140
Utilities for Flink version management and comparison.
141

142
```java { .api }
143
public enum FlinkVersion {
144
    v1_3("1.3"), v1_4("1.4"), v1_5("1.5"), v1_6("1.6"), v1_7("1.7"), 
145
    v1_8("1.8"), v1_9("1.9"), v1_10("1.10"), v1_11("1.11"), v1_12("1.12"), 
146
    v1_13("1.13"), v1_14("1.14"), v1_15("1.15"), v1_16("1.16"), v1_17("1.17"), 
147
    v1_18("1.18"), v1_19("1.19"), v1_20("1.20"), v2_0("2.0"), v2_1("2.1");
148
    
149
    /**
150
     * Returns string representation of the version
151
     */
152
    public String toString();
153
    
154
    /**
155
     * Compares if this version is newer than the other version
156
     * @param otherVersion version to compare against
157
     * @return true if this version is newer
158
     */
159
    public boolean isNewerVersionThan(FlinkVersion otherVersion);
160
    
161
    /**
162
     * Returns all versions within the defined range, inclusive both start and end
163
     * @param start starting version (inclusive)
164
     * @param end ending version (inclusive)
165
     * @return Set of versions in range
166
     */
167
    public static Set<FlinkVersion> rangeOf(FlinkVersion start, FlinkVersion end);
168
    
169
    /**
170
     * Gets version by version code string
171
     * @param code version string like "2.1"
172
     * @return Optional containing version if found
173
     */
174
    public static Optional<FlinkVersion> byCode(String code);
175
    
176
    /**
177
     * Creates version from major and minor numbers
178
     * @param majorVersion major version number
179
     * @param minorVersion minor version number
180
     * @return FlinkVersion instance
181
     */
182
    public static FlinkVersion valueOf(int majorVersion, int minorVersion);
183
    
184
    /**
185
     * Returns the version for the current branch (latest version)
186
     * @return current FlinkVersion
187
     */
188
    public static FlinkVersion current();
189
}
190
```
191

192
**Usage Examples:**
193

194
```java
195
// Get current version
196
FlinkVersion current = FlinkVersion.current(); // Returns v2_1
197

198
// Version comparison
199
boolean isNewer = FlinkVersion.v2_1.isNewerVersionThan(FlinkVersion.v2_0); // true
200

201
// Get version by string
202
Optional<FlinkVersion> version = FlinkVersion.byCode("2.1"); // Optional[v2_1]
203

204
// Create version from numbers
205
FlinkVersion version = FlinkVersion.valueOf(2, 1); // v2_1
206

207
// Get version range
208
Set<FlinkVersion> versions = FlinkVersion.rangeOf(
209
    FlinkVersion.v1_18, 
210
    FlinkVersion.v2_0
211
); // [v1_18, v1_19, v1_20, v2_0]
212
```
213

214
### Documentation Generation Support
215

216
Annotations for controlling configuration documentation generation.
217

218
```java { .api }
219
public final class Documentation {
220
    /**
221
     * Annotation used on config option fields to override the documented default
222
     */
223
    @Target(ElementType.FIELD)
224
    @Retention(RetentionPolicy.RUNTIME)
225
    @Internal
226
    public @interface OverrideDefault {
227
        String value();
228
    }
229
    
230
    /**
231
     * Annotation used on config option fields to include them in specific sections
232
     */
233
    @Target(ElementType.FIELD)
234
    @Retention(RetentionPolicy.RUNTIME)
235
    @Internal
236
    public @interface Section {
237
        /** The sections in the config docs where this option should be included */
238
        String[] value() default {};
239
        /** The relative position of the option in its section */
240
        int position() default Integer.MAX_VALUE;
241
    }
242
    
243
    /**
244
     * Annotation used on table config options for adding meta data labels
245
     */
246
    @Target(ElementType.FIELD)
247
    @Retention(RetentionPolicy.RUNTIME)
248
    @Internal
249
    public @interface TableOption {
250
        ExecMode execMode();
251
    }
252
    
253
    /**
254
     * Annotation used on config option fields to mark them as suffix-options
255
     */
256
    @Target({ElementType.FIELD, ElementType.TYPE})
257
    @Retention(RetentionPolicy.RUNTIME)
258
    @Internal
259
    public @interface SuffixOption {
260
        String value();
261
    }
262
    
263
    /**
264
     * Annotation used on config option fields to exclude from documentation
265
     */
266
    @Target({ElementType.FIELD, ElementType.TYPE})
267
    @Retention(RetentionPolicy.RUNTIME)
268
    @Internal
269
    public @interface ExcludeFromDocumentation {
270
        /** The optional reason why it is excluded from documentation */
271
        String value() default "";
272
    }
273
    
274
    /** The execution mode the config works for */
275
    public enum ExecMode {
276
        BATCH("Batch"),
277
        STREAMING("Streaming"), 
278
        BATCH_STREAMING("Batch and Streaming");
279
        
280
        public String toString();
281
    }
282
    
283
    /** Constants for section names */
284
    public static final class Sections {
285
        public static final String COMMON_HOST_PORT = "common_host_port";
286
        public static final String COMMON_STATE_BACKENDS = "common_state_backends";
287
        public static final String COMMON_CHECKPOINTING = "common_checkpointing";
288
        public static final String COMMON_HIGH_AVAILABILITY = "common_high_availability";
289
        public static final String COMMON_HIGH_AVAILABILITY_ZOOKEEPER = "common_high_availability_zk";
290
        public static final String COMMON_HIGH_AVAILABILITY_JOB_RESULT_STORE = "common_high_availability_jrs";
291
        public static final String COMMON_MEMORY = "common_memory";
292
        public static final String COMMON_MISCELLANEOUS = "common_miscellaneous";
293
        
294
        public static final String SECURITY_SSL = "security_ssl";
295
        public static final String SECURITY_AUTH_KERBEROS = "security_auth_kerberos";
296
        public static final String SECURITY_DELEGATION_TOKEN = "security_delegation_token";
297
        public static final String SECURITY_AUTH_ZOOKEEPER = "security_auth_zk";
298
        
299
        public static final String STATE_BACKEND_ROCKSDB = "state_backend_rocksdb";
300
        public static final String STATE_BACKEND_FORST = "state_backend_forst";
301
        public static final String STATE_LATENCY_TRACKING = "state_latency_tracking";
302
        public static final String STATE_SIZE_TRACKING = "state_size_tracking";
303
        public static final String STATE_CHANGELOG = "state_changelog";
304
        
305
        public static final String EXPERT_CLASS_LOADING = "expert_class_loading";
306
        public static final String EXPERT_DEBUGGING_AND_TUNING = "expert_debugging_and_tuning";
307
        public static final String EXPERT_SCHEDULING = "expert_scheduling";
308
        public static final String EXPERT_FAULT_TOLERANCE = "expert_fault_tolerance";
309
        public static final String EXPERT_CHECKPOINTING = "expert_checkpointing";
310
        public static final String EXPERT_REST = "expert_rest";
311
        public static final String EXPERT_HIGH_AVAILABILITY = "expert_high_availability";
312
        public static final String EXPERT_ZOOKEEPER_HIGH_AVAILABILITY = "expert_high_availability_zk";
313
        public static final String EXPERT_KUBERNETES_HIGH_AVAILABILITY = "expert_high_availability_k8s";
314
        public static final String EXPERT_SECURITY_SSL = "expert_security_ssl";
315
        public static final String EXPERT_ROCKSDB = "expert_rocksdb";
316
        public static final String EXPERT_FORST = "expert_forst";
317
        public static final String EXPERT_CLUSTER = "expert_cluster";
318
        public static final String EXPERT_JOB_MANAGER = "expert_jobmanager";
319
        
320
        public static final String ALL_JOB_MANAGER = "all_jobmanager";
321
        public static final String ALL_TASK_MANAGER = "all_taskmanager";
322
        public static final String ALL_TASK_MANAGER_NETWORK = "all_taskmanager_network";
323
        
324
        public static final String DEPRECATED_FILE_SINKS = "deprecated_file_sinks";
325
        
326
        public static final String METRIC_REPORTERS = "metric_reporters";
327
        public static final String TRACE_REPORTERS = "trace_reporters";
328
        public static final String EVENT_REPORTERS = "event_reporters";
329
        
330
        public static final String CHECKPOINT_FILE_MERGING = "checkpoint_file_merging";
331
    }
332
}
333

334
/**
335
 * Annotation for specifying config option groups
336
 */
337
@Target({})
338
@Internal
339
public @interface ConfigGroup {
340
    String name();
341
    String keyPrefix();
342
}
343

344
/**
345
 * Annotation used on classes to enable separation of options into different tables
346
 */
347
@Target(ElementType.TYPE)
348
@Retention(RetentionPolicy.RUNTIME)
349
@Internal
350
public @interface ConfigGroups {
351
    ConfigGroup[] groups() default {};
352
}
353

354
/**
355
 * Annotations for auto-generating JSON payload documentation
356
 */
357
@Internal
358
public class FlinkJsonSchema {
359
    /**
360
     * Documents a class that supports setting dynamic properties of a certain type
361
     */
362
    @Target(ElementType.TYPE)
363
    @Retention(RetentionPolicy.RUNTIME)
364
    @Internal
365
    public @interface AdditionalFields {
366
        /**
367
         * Actual type the additional fields need to match
368
         * @return type of the additional fields
369
         */
370
        Class<?> type();
371
    }
372
}
373
```
374

375
**Usage Examples:**
376

377
```java
378
// Override default value in documentation
379
@Documentation.OverrideDefault("custom-default")
380
private ConfigOption<String> myOption;
381

382
// Place option in specific documentation section
383
@Documentation.Section({"common_checkpointing"})
384
private ConfigOption<Integer> checkpointInterval;
385

386
// Mark as table-specific option for streaming mode
387
@Documentation.TableOption(execMode = Documentation.ExecMode.STREAMING)
388
private ConfigOption<Boolean> streamingOption;
389

390
// Group related config options
391
@ConfigGroups(groups = {
392
    @ConfigGroup(name = "ssl", keyPrefix = "security.ssl")
393
})
394
public class SecurityOptions {
395
    // config options...
396
}
397

398
// Support additional dynamic fields
399
@FlinkJsonSchema.AdditionalFields(type = String.class)
400
public class DynamicConfig {
401
    // allows additional string properties
402
}
403
```
404

405
## Types
406

407
```java { .api }
408
// Version enumeration
409
public enum FlinkVersion {
410
    v1_3, v1_4, v1_5, v1_6, v1_7, v1_8, v1_9, v1_10, v1_11, v1_12,
411
    v1_13, v1_14, v1_15, v1_16, v1_17, v1_18, v1_19, v1_20, v2_0, v2_1;
412
}
413

414
// Documentation execution modes
415
public enum Documentation.ExecMode {
416
    BATCH, STREAMING, BATCH_STREAMING;
417
}
418
```