[FLINK-3093] Introduce annotations for interface stability in flink-core

This closes apache#1427

flink-annotations/pom.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http:https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<project xmlns="http:https://maven.apache.org/POM/4.0.0" xmlns:xsi="http:https://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http:https://maven.apache.org/POM/4.0.0 http:https://maven.apache.org/maven-v4_0_0.xsd">
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.flink</groupId>
+ <artifactId>flink-parent</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <relativePath>..</relativePath>
+ </parent>
+
+ <artifactId>flink-annotations</artifactId>
+ <name>flink-annotations</name>
+
+ <packaging>jar</packaging>
+
+</project>

flink-annotations/src/main/java/org/apache/flink/annotation/Experimental.java

@@ -0,0 +1,34 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http:https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+package org.apache.flink.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Interface to mark methods within stable, public APIs as experimental.
+ * It also allows to mark types explicitly as experimental
+ *
+ * An experimental API might change between minor releases.
+ */
+@Documented
+@Target({ ElementType.TYPE, ElementType.METHOD })
+public @interface Experimental {
+}

flink-annotations/src/main/java/org/apache/flink/annotation/Internal.java

@@ -0,0 +1,33 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http:https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+package org.apache.flink.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Interface to mark methods within stable, public APIs as an internal developer API.
+ *
+ * Developer APIs are stable but internal to Flink and might change across releases.
+ */
+@Documented
+@Target({ ElementType.TYPE, ElementType.METHOD })
+public @interface Internal {
+}

flink-annotations/src/main/java/org/apache/flink/annotation/Public.java

@@ -0,0 +1,35 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http:https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+package org.apache.flink.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation for marking classes as public, stable interfaces.
+ *
+ * Classes, methods and fields with this annotation are stable across minor releases (1.0, 1.1, 1.2). In other words,
+ * applications using @PublicInterface annotated classes will compile against newer versions of the same major release.
+ *
+ * Only major releases (1.0, 2.0, 3.0) can break interfaces with this annotation.
+ */
+@Documented
+@Target(ElementType.TYPE)
+public @interface Public {}

flink-core/pom.xml

@@ -35,6 +35,12 @@ under the License.
  <packaging>jar</packaging>
 
  <dependencies>
+ <dependency>
+ <groupId>org.apache.flink</groupId>
+ <artifactId>flink-annotations</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+
  <dependency>
  <groupId>org.apache.flink</groupId>
  <artifactId>${shading-artifact.name}</artifactId>

flink-core/src/main/java/org/apache/flink/api/common/CodeAnalysisMode.java

@@ -18,6 +18,8 @@
 
 package org.apache.flink.api.common;
 
+import org.apache.flink.annotation.Public;
+
 /**
  * Specifies to which extent user-defined functions are analyzed in order
  * to give the Flink optimizer an insight of UDF internals and inform
@@ -31,6 +33,7 @@
  * - Warnings if a tuple access uses a wrong index
  * - Information about the number of object creations (for manual optimization)
  */
+@Public
 public enum CodeAnalysisMode {
 
  /**

flink-core/src/main/java/org/apache/flink/api/common/ExecutionConfig.java

@@ -19,6 +19,8 @@
 package org.apache.flink.api.common;
 
 import com.esotericsoftware.kryo.Serializer;
+import org.apache.flink.annotation.Experimental;
+import org.apache.flink.annotation.Public;
 
 import java.io.Serializable;
 import java.util.LinkedHashMap;
@@ -51,6 +53,7 @@
  * automatically applied.</li>
  * </ul>
  */
+@Public
 public class ExecutionConfig implements Serializable {
 
  private static final long serialVersionUID = 1L;
@@ -150,6 +153,7 @@ public boolean isClosureCleanerEnabled() {
  *
  * @param interval The interval between watermarks in milliseconds.
  */
+ @Experimental
  public ExecutionConfig setAutoWatermarkInterval(long interval) {
  enableTimestamps();
  this.autoWatermarkInterval = interval;
@@ -167,6 +171,7 @@ public ExecutionConfig setAutoWatermarkInterval(long interval) {
  *
  * @see #setAutoWatermarkInterval(long)
  */
+ @Experimental
  public ExecutionConfig enableTimestamps() {
  this.timestampsEnabled = true;
  return this;
@@ -177,6 +182,7 @@ public ExecutionConfig enableTimestamps() {
  *
  * @see #enableTimestamps()
  */
+ @Experimental
  public ExecutionConfig disableTimestamps() {
  this.timestampsEnabled = false;
  return this;
@@ -187,6 +193,7 @@ public ExecutionConfig disableTimestamps() {
  *
  * @see #enableTimestamps()
  */
+ @Experimental
  public boolean areTimestampsEnabled() {
  return timestampsEnabled;
  }
@@ -196,6 +203,7 @@ public boolean areTimestampsEnabled() {
  *
  * @see #setAutoWatermarkInterval(long)
  */
+ @Experimental
  public long getAutoWatermarkInterval() {
  return this.autoWatermarkInterval;
  }
@@ -377,13 +385,15 @@ public boolean isObjectReuseEnabled() {
  * 
  * @param codeAnalysisMode see {@link CodeAnalysisMode}
  */
+ @Experimental
  public void setCodeAnalysisMode(CodeAnalysisMode codeAnalysisMode) {
  this.codeAnalysisMode = codeAnalysisMode;
  }
 
  /**
  * Returns the {@link CodeAnalysisMode} of the program.
  */
+ @Experimental
  public CodeAnalysisMode getCodeAnalysisMode() {
  return codeAnalysisMode;
  }

flink-core/src/main/java/org/apache/flink/api/common/ExecutionMode.java

@@ -18,10 +18,13 @@
 
 package org.apache.flink.api.common;
 
+import org.apache.flink.annotation.Public;
+
 /**
  * The execution mode specifies how a batch program is executed in terms
  * of data exchange: pipelining or batched.
  */
+@Public
 public enum ExecutionMode {
 
  /**

flink-core/src/main/java/org/apache/flink/api/common/JobExecutionResult.java

@@ -18,6 +18,9 @@
 
 package org.apache.flink.api.common;
 
+import org.apache.flink.annotation.Experimental;
+import org.apache.flink.annotation.Public;
+
 import java.util.Collections;
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
@@ -26,6 +29,7 @@
  * The result of a job execution. Gives access to the execution time of the job,
  * and to all accumulators created by this job.
  */
+@Public
 public class JobExecutionResult extends JobSubmissionResult {
 
  private long netRuntime;
@@ -99,6 +103,8 @@ public Map<String, Object> getAllAccumulatorResults() {
  * @return Result of the counter, or null if the counter does not exist
  * @throws java.lang.ClassCastException Thrown, if the accumulator was not aggregating a {@link java.lang.Integer}
  */
+ @Deprecated
+ @Experimental
  public Integer getIntCounterResult(String accumulatorName) {
  Object result = this.accumulatorResults.get(accumulatorName);
  if (result == null) {

flink-core/src/main/java/org/apache/flink/api/common/JobID.java

@@ -18,6 +18,7 @@
 
 package org.apache.flink.api.common;
 
+import org.apache.flink.annotation.Public;
 import org.apache.flink.util.AbstractID;
 import javax.xml.bind.DatatypeConverter;
 import java.nio.ByteBuffer;
@@ -30,6 +31,7 @@
  * incrementally in different parts. Newer fragments of a graph can be attached to existing
  * graphs, thereby extending the current data flow graphs.</p>
  */
+@Public
 public final class JobID extends AbstractID {
 
  private static final long serialVersionUID = 1L;

flink-core/src/main/java/org/apache/flink/api/common/JobSubmissionResult.java

@@ -18,9 +18,12 @@
 
 package org.apache.flink.api.common;
 
+import org.apache.flink.annotation.Public;
+
 /**
  * The result of submitting a job to a JobManager.
  */
+@Public
 public class JobSubmissionResult {
 
  private JobID jobID;

flink-core/src/main/java/org/apache/flink/api/common/accumulators/Accumulator.java

@@ -18,6 +18,8 @@
 
 package org.apache.flink.api.common.accumulators;
 
+import org.apache.flink.annotation.Public;
+
 import java.io.Serializable;
 
 /**
@@ -39,6 +41,7 @@
  * Type of the accumulator result as it will be reported to the
  * client
  */
+@Public
 public interface Accumulator<V, R extends Serializable> extends Serializable, Cloneable {
  /**
  * @param value

flink-core/src/main/java/org/apache/flink/api/common/accumulators/AverageAccumulator.java

@@ -18,10 +18,13 @@
 
 package org.apache.flink.api.common.accumulators;
 
+import org.apache.flink.annotation.Public;
+
 /**
  * An accumulator that computes the average value.
  * Input can be {@code long}, {@code integer}, or {@code double} and the result is {@code double}.
  */
+@Public
 public class AverageAccumulator implements SimpleAccumulator<Double> {
 
  private static final long serialVersionUID = 3672555084179165255L;

flink-core/src/main/java/org/apache/flink/api/common/accumulators/DoubleCounter.java

@@ -18,6 +18,7 @@
 
 package org.apache.flink.api.common.accumulators;
 
+
 /**
  * An accumulator that sums up {@code double} values.
  */

flink-core/src/main/java/org/apache/flink/api/common/accumulators/Histogram.java

@@ -18,6 +18,8 @@
 
 package org.apache.flink.api.common.accumulators;
 
+import org.apache.flink.annotation.Public;
+
 import java.util.Map;
 import java.util.TreeMap;
 
@@ -29,6 +31,7 @@
  * This class does not extend to continuous values later, because it makes no
  * attempt to put the data in bins.
  */
+@Public
 public class Histogram implements Accumulator<Integer, TreeMap<Integer, Integer>> {
 
  private static final long serialVersionUID = 1L;

flink-core/src/main/java/org/apache/flink/api/common/accumulators/IntCounter.java

@@ -19,6 +19,7 @@
 
 package org.apache.flink.api.common.accumulators;
 
+
 /**
  * An accumulator that sums up {@code Integer} values.
  */

flink-core/src/main/java/org/apache/flink/api/common/accumulators/ListAccumulator.java

@@ -18,13 +18,16 @@
 
 package org.apache.flink.api.common.accumulators;
 
+import org.apache.flink.annotation.Public;
+
 import java.util.ArrayList;
 
 /**
  * This accumulator stores a collection of objects.
  *
  * @param <T> The type of the accumulated objects
  */
+@Public
 public class ListAccumulator<T> implements Accumulator<T, ArrayList<T>> {
 
  private static final long serialVersionUID = 1L;