[flink] branch release-1.13 updated: [FLINK-21467] Clarify javadocs of Bounded(One/Multi)Input interfaces

[dw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

dwysakowicz pushed a commit to branch release-1.13
in repository https://gitbox.apache.org/repos/asf/flink.git


The following commit(s) were added to refs/heads/release-1.13 by this push:
     new 0e1fa1a  [FLINK-21467] Clarify javadocs of Bounded(One/Multi)Input interfaces
0e1fa1a is described below

commit 0e1fa1aa37d2b8ae09cf3b16ec1093c571a70a77
Author: Dawid Wysakowicz <dw...@apache.org>
AuthorDate: Fri Nov 26 13:41:17 2021 +0100

    [FLINK-21467] Clarify javadocs of Bounded(One/Multi)Input interfaces
    
    We clarify contracts of Bounded(One/Multi)Input interfaces. Especially
    adding a warning none of those interfaces should be used for commiting
    side effects.
---
 .../streaming/api/operators/BoundedMultiInput.java     | 18 +++++++++++++++---
 .../flink/streaming/api/operators/BoundedOneInput.java | 18 ++++++++++++++++--
 2 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedMultiInput.java b/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedMultiInput.java
index c030456..659b8a1 100755
--- a/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedMultiInput.java
+++ b/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedMultiInput.java
@@ -19,13 +19,25 @@ package org.apache.flink.streaming.api.operators;
 
 import org.apache.flink.annotation.PublicEvolving;
 
-/** Interface for the multi-input operators that can process EndOfInput event. */
+/**
+ * Interface for multi-input operators that need to be notified about the logical/semantical end of
+ * input.
+ *
+ * <p><b>NOTE:</b> Classes should not implement both {@link BoundedOneInput} and {@link
+ * BoundedMultiInput} at the same time!
+ *
+ * @see BoundedOneInput
+ */
 @PublicEvolving
 public interface BoundedMultiInput {
 
     /**
-     * It is notified that no more data will arrive on the input identified by the {@code inputId}.
-     * The {@code inputId} is numbered starting from 1, and `1` indicates the first input.
+     * It is notified that no more data will arrive from the input identified by the {@code
+     * inputId}. The {@code inputId} is numbered starting from 1, and `1` indicates the first input.
+     *
+     * <p><b>WARNING:</b> It is not safe to use this method to commit any transactions or other side
+     * effects! You can use this method to e.g. flush data buffered for the given input or implement
+     * an ordered reading from multiple inputs via {@link InputSelectable}.
      */
     void endInput(int inputId) throws Exception;
 }
diff --git a/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedOneInput.java b/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedOneInput.java
index 9115557..2f2c8b1 100755
--- a/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedOneInput.java
+++ b/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/BoundedOneInput.java
@@ -19,10 +19,24 @@ package org.apache.flink.streaming.api.operators;
 
 import org.apache.flink.annotation.PublicEvolving;
 
-/** Interface for the one-input operators that can process EndOfInput event. */
+/**
+ * Interface for one-input operators that need to be notified about the logical/semantical end of
+ * input.
+ *
+ * <p><b>NOTE:</b> Classes should not implement both {@link BoundedOneInput} and {@link
+ * BoundedMultiInput} at the same time!
+ *
+ * @see BoundedMultiInput
+ */
 @PublicEvolving
 public interface BoundedOneInput {
 
-    /** It is notified that no more data will arrive on the input. */
+    /**
+     * It is notified that no more data will arrive from the input.
+     *
+     * <p><b>WARNING:</b> It is not safe to use this method to commit any transactions or other side
+     * effects! You can use this method to flush any buffered data that can later on be committed
+     * e.g. in a {@link StreamOperator#notifyCheckpointComplete(long)}.
+     */
     void endInput() throws Exception;
 }