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 <[email protected]>
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;
}
