#45 Add @experimental

seznam · Apr 12, 2017 · d1c8399 · d1c8399
1 parent 12927b9
commit d1c8399
Show file tree

Hide file tree

Showing 6 changed files with 38 additions and 2 deletions.
diff --git a/euphoria-core/src/main/java/cz/seznam/euphoria/core/annotation/stability/Experimental.java b/euphoria-core/src/main/java/cz/seznam/euphoria/core/annotation/stability/Experimental.java
@@ -0,0 +1,25 @@
+package cz.seznam.euphoria.core.annotation.stability;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Any (API) item annotated with this annotation signals that the item
+ * is purely experimental and may be change or completely removed without
+ * any notice at any time.
+ * <p>
+ *
+ * Clients should generally avoid usage of such items, except when experimenting :)
+ */
+@Documented
+@Target({
+    ElementType.TYPE,
+    ElementType.FIELD,
+    ElementType.METHOD,
+    ElementType.PARAMETER,
+    ElementType.CONSTRUCTOR,
+    ElementType.ANNOTATION_TYPE,
+    ElementType.PACKAGE
+})
+public @interface Experimental {}
diff --git a/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/dataset/windowing/Windowing.java b/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/dataset/windowing/Windowing.java
@@ -15,8 +15,9 @@
  */
 package cz.seznam.euphoria.core.client.dataset.windowing;
 
-import cz.seznam.euphoria.core.client.triggers.Trigger;
+import cz.seznam.euphoria.core.annotation.stability.Experimental;
 import cz.seznam.euphoria.core.client.functional.ResultType;
+import cz.seznam.euphoria.core.client.triggers.Trigger;
 
 import java.io.Serializable;
 
@@ -57,6 +58,7 @@ public interface Windowing<T, W extends Window> extends Serializable {
    *          strategy are to be handled opaque, otherwise a type hint about
    *          the window types
    */
+  @Experimental
   default ResultType<W> getWindowType() {
     return null;
   }

diff --git a/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/functional/DelegatedFunction.java b/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/functional/DelegatedFunction.java
@@ -15,8 +15,11 @@
  */
 package cz.seznam.euphoria.core.client.functional;
 
+import cz.seznam.euphoria.core.annotation.stability.Experimental;
+
 import java.io.Serializable;
 
+@Experimental
 public interface DelegatedFunction<F> extends Serializable {
 
   F getDelegate();

diff --git a/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/functional/ResultType.java b/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/functional/ResultType.java
@@ -15,12 +15,13 @@
  */
 package cz.seznam.euphoria.core.client.functional;
 
+import cz.seznam.euphoria.core.annotation.stability.Experimental;
 import cz.seznam.euphoria.shaded.guava.com.google.common.reflect.TypeToken;
 
 import java.io.Serializable;
 import java.lang.reflect.Type;
 
-// XXX TypeHint would be a much better name but is already take by flink :/
+@Experimental
 public abstract class ResultType<T> implements Serializable {
   private final TypeToken<T> tt = new TypeToken<T>(getClass()) {};
 

diff --git a/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/functional/ResultTypeAware.java b/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/functional/ResultTypeAware.java
@@ -15,8 +15,11 @@
  */
 package cz.seznam.euphoria.core.client.functional;
 
+import cz.seznam.euphoria.core.annotation.stability.Experimental;
+
 import java.io.Serializable;
 
+@Experimental
 public interface ResultTypeAware<T> extends Serializable {
 
   ResultType<T> getResultType();

diff --git a/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/operator/ReduceByKey.java b/euphoria-core/src/main/java/cz/seznam/euphoria/core/client/operator/ReduceByKey.java
@@ -17,6 +17,7 @@
 
 import cz.seznam.euphoria.core.annotation.operator.Recommended;
 import cz.seznam.euphoria.core.annotation.operator.StateComplexity;
+import cz.seznam.euphoria.core.annotation.stability.Experimental;
 import cz.seznam.euphoria.core.client.dataset.Dataset;
 import cz.seznam.euphoria.core.client.dataset.partitioning.Partitioning;
 import cz.seznam.euphoria.core.client.dataset.windowing.Window;
@@ -92,6 +93,7 @@ public <KEY> DatasetBuilder2<IN, KEY> keyBy(UnaryFunction<IN, KEY> keyFn) {
       return new DatasetBuilder2<>(name, input, keyFn);
     }
 
+    @Experimental
     public <KEY> DatasetBuilder2<IN, KEY> keyBy(UnaryFunction<IN, KEY> keyFn, ResultType<KEY> keyType) {
       return new DatasetBuilder2<IN, KEY>(name, input, new TypeSupport.DelegatedUnaryFunction<>(keyFn, keyType));
     }