Flink Annotations

import org.apache.flink.annotation.Public;
import org.apache.flink.annotation.PublicEvolving;
import org.apache.flink.annotation.Experimental;
import org.apache.flink.annotation.Internal;
import org.apache.flink.annotation.VisibleForTesting;
import org.apache.flink.FlinkVersion;

import org.apache.flink.annotation.docs.Documentation;
import org.apache.flink.annotation.docs.ConfigGroup;
import org.apache.flink.annotation.docs.ConfigGroups;
import org.apache.flink.annotation.docs.FlinkJsonSchema;

import org.apache.flink.annotation.Public;
import org.apache.flink.annotation.PublicEvolving;
import org.apache.flink.FlinkVersion;

// Mark a class as stable public API
@Public
public class MyPublicClass {
    // Stable method
    public void stableMethod() { }
    
    // Method with evolving signature
    @PublicEvolving
    public void evolvingMethod(int param) { }
}

// Version management
FlinkVersion current = FlinkVersion.current();
boolean isNewer = FlinkVersion.v2_1.isNewerVersionThan(FlinkVersion.v2_0);
Optional<FlinkVersion> version = FlinkVersion.byCode("2.1");

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Public
@interface Public {}

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Retention(RetentionPolicy.RUNTIME)
@Public
@interface PublicEvolving {}

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Retention(RetentionPolicy.RUNTIME)
@Public
@interface Experimental {}

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Public
@interface Internal {}

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD, ElementType.CONSTRUCTOR})
@Internal
// Note: Uses default retention policy (RetentionPolicy.CLASS)
@interface VisibleForTesting {}

// Stable public API - guaranteed compatibility across minor releases
@Public
public class DataStreamAPI {
    public void map() { }
}

// Public API but interface may evolve
@Public
public class StreamingContext {
    @PublicEvolving
    public void experimentalFeature() { }
}

// Experimental feature that may change or be removed
@Experimental
public class NewStreamProcessor {
    public void process() { }
}

// Internal API for framework use only
@Internal
public class RuntimeHelper {
    public void internalMethod() { }
}

// Method visible only for testing purposes
public class MyService {
    @VisibleForTesting
    void packagePrivateMethod() { }
}

public enum FlinkVersion {
    v1_3("1.3"), v1_4("1.4"), v1_5("1.5"), v1_6("1.6"), v1_7("1.7"), 
    v1_8("1.8"), v1_9("1.9"), v1_10("1.10"), v1_11("1.11"), v1_12("1.12"), 
    v1_13("1.13"), v1_14("1.14"), v1_15("1.15"), v1_16("1.16"), v1_17("1.17"), 
    v1_18("1.18"), v1_19("1.19"), v1_20("1.20"), v2_0("2.0"), v2_1("2.1");
    
    /**
     * Returns string representation of the version
     */
    public String toString();
    
    /**
     * Compares if this version is newer than the other version
     * @param otherVersion version to compare against
     * @return true if this version is newer
     */
    public boolean isNewerVersionThan(FlinkVersion otherVersion);
    
    /**
     * Returns all versions within the defined range, inclusive both start and end
     * @param start starting version (inclusive)
     * @param end ending version (inclusive)
     * @return Set of versions in range
     */
    public static Set<FlinkVersion> rangeOf(FlinkVersion start, FlinkVersion end);
    
    /**
     * Gets version by version code string
     * @param code version string like "2.1"
     * @return Optional containing version if found
     */
    public static Optional<FlinkVersion> byCode(String code);
    
    /**
     * Creates version from major and minor numbers
     * @param majorVersion major version number
     * @param minorVersion minor version number
     * @return FlinkVersion instance
     */
    public static FlinkVersion valueOf(int majorVersion, int minorVersion);
    
    /**
     * Returns the version for the current branch (latest version)
     * @return current FlinkVersion
     */
    public static FlinkVersion current();
}

// Get current version
FlinkVersion current = FlinkVersion.current(); // Returns v2_1

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

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

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

// Get version range
Set<FlinkVersion> versions = FlinkVersion.rangeOf(
    FlinkVersion.v1_18, 
    FlinkVersion.v2_0
); // [v1_18, v1_19, v1_20, v2_0]

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 specific sections
     */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface Section {
        /** The sections in the config docs where this option should be included */
        String[] value() default {};
        /** The relative position of the option in its section */
        int position() default Integer.MAX_VALUE;
    }
    
    /**
     * Annotation used on table config options for adding meta data labels
     */
    @Target(ElementType.FIELD)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface TableOption {
        ExecMode execMode();
    }
    
    /**
     * Annotation used on config option fields to mark them as suffix-options
     */
    @Target({ElementType.FIELD, ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface SuffixOption {
        String value();
    }
    
    /**
     * Annotation used on config option fields to exclude from documentation
     */
    @Target({ElementType.FIELD, ElementType.TYPE})
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface ExcludeFromDocumentation {
        /** The optional reason why it is excluded from documentation */
        String value() default "";
    }
    
    /** The execution mode the config works for */
    public enum ExecMode {
        BATCH("Batch"),
        STREAMING("Streaming"), 
        BATCH_STREAMING("Batch and Streaming");
        
        public String toString();
    }
    
    /** Constants for section names */
    public static final class Sections {
        public static final String COMMON_HOST_PORT = "common_host_port";
        public static final String COMMON_STATE_BACKENDS = "common_state_backends";
        public static final String COMMON_CHECKPOINTING = "common_checkpointing";
        public static final String COMMON_HIGH_AVAILABILITY = "common_high_availability";
        public static final String COMMON_HIGH_AVAILABILITY_ZOOKEEPER = "common_high_availability_zk";
        public static final String COMMON_HIGH_AVAILABILITY_JOB_RESULT_STORE = "common_high_availability_jrs";
        public static final String COMMON_MEMORY = "common_memory";
        public static final String COMMON_MISCELLANEOUS = "common_miscellaneous";
        
        public static final String SECURITY_SSL = "security_ssl";
        public static final String SECURITY_AUTH_KERBEROS = "security_auth_kerberos";
        public static final String SECURITY_DELEGATION_TOKEN = "security_delegation_token";
        public static final String SECURITY_AUTH_ZOOKEEPER = "security_auth_zk";
        
        public static final String STATE_BACKEND_ROCKSDB = "state_backend_rocksdb";
        public static final String STATE_BACKEND_FORST = "state_backend_forst";
        public static final String STATE_LATENCY_TRACKING = "state_latency_tracking";
        public static final String STATE_SIZE_TRACKING = "state_size_tracking";
        public static final String STATE_CHANGELOG = "state_changelog";
        
        public static final String EXPERT_CLASS_LOADING = "expert_class_loading";
        public static final String EXPERT_DEBUGGING_AND_TUNING = "expert_debugging_and_tuning";
        public static final String EXPERT_SCHEDULING = "expert_scheduling";
        public static final String EXPERT_FAULT_TOLERANCE = "expert_fault_tolerance";
        public static final String EXPERT_CHECKPOINTING = "expert_checkpointing";
        public static final String EXPERT_REST = "expert_rest";
        public static final String EXPERT_HIGH_AVAILABILITY = "expert_high_availability";
        public static final String EXPERT_ZOOKEEPER_HIGH_AVAILABILITY = "expert_high_availability_zk";
        public static final String EXPERT_KUBERNETES_HIGH_AVAILABILITY = "expert_high_availability_k8s";
        public static final String EXPERT_SECURITY_SSL = "expert_security_ssl";
        public static final String EXPERT_ROCKSDB = "expert_rocksdb";
        public static final String EXPERT_FORST = "expert_forst";
        public static final String EXPERT_CLUSTER = "expert_cluster";
        public static final String EXPERT_JOB_MANAGER = "expert_jobmanager";
        
        public static final String ALL_JOB_MANAGER = "all_jobmanager";
        public static final String ALL_TASK_MANAGER = "all_taskmanager";
        public static final String ALL_TASK_MANAGER_NETWORK = "all_taskmanager_network";
        
        public static final String DEPRECATED_FILE_SINKS = "deprecated_file_sinks";
        
        public static final String METRIC_REPORTERS = "metric_reporters";
        public static final String TRACE_REPORTERS = "trace_reporters";
        public static final String EVENT_REPORTERS = "event_reporters";
        
        public static final String CHECKPOINT_FILE_MERGING = "checkpoint_file_merging";
    }
}

/**
 * Annotation for specifying config option groups
 */
@Target({})
@Internal
public @interface ConfigGroup {
    String name();
    String keyPrefix();
}

/**
 * Annotation used on classes to enable separation of options into different tables
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Internal
public @interface ConfigGroups {
    ConfigGroup[] groups() default {};
}

/**
 * Annotations for auto-generating JSON payload documentation
 */
@Internal
public class FlinkJsonSchema {
    /**
     * Documents a class that supports setting dynamic properties of a certain type
     */
    @Target(ElementType.TYPE)
    @Retention(RetentionPolicy.RUNTIME)
    @Internal
    public @interface AdditionalFields {
        /**
         * Actual type the additional fields need to match
         * @return type of the additional fields
         */
        Class<?> type();
    }
}

// Override default value in documentation
@Documentation.OverrideDefault("custom-default")
private ConfigOption<String> myOption;

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

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

// Group related config options
@ConfigGroups(groups = {
    @ConfigGroup(name = "ssl", keyPrefix = "security.ssl")
})
public class SecurityOptions {
    // config options...
}

// Support additional dynamic fields
@FlinkJsonSchema.AdditionalFields(type = String.class)
public class DynamicConfig {
    // allows additional string properties
}

// Version enumeration
public enum FlinkVersion {
    v1_3, v1_4, v1_5, v1_6, v1_7, v1_8, v1_9, v1_10, v1_11, v1_12,
    v1_13, v1_14, v1_15, v1_16, v1_17, v1_18, v1_19, v1_20, v2_0, v2_1;
}

// Documentation execution modes
public enum Documentation.ExecMode {
    BATCH, STREAMING, BATCH_STREAMING;
}