You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by dw...@apache.org on 2021/12/01 15:58:58 UTC
[flink] branch release-1.14 updated: [FLINK-21467] Clarify javadocs of Bounded(One/Multi)Input interfaces
This is an automated email from the ASF dual-hosted git repository.
dwysakowicz pushed a commit to branch release-1.14
in repository https://gitbox.apache.org/repos/asf/flink.git
The following commit(s) were added to refs/heads/release-1.14 by this push:
new ab9f939 [FLINK-21467] Clarify javadocs of Bounded(One/Multi)Input interfaces
ab9f939 is described below
commit ab9f9390837419f4a813df95302ba7583650abe2
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 +++++++++++++++---
.../streaming/api/operators/BoundedOneInput.java | 22 ++++++++++++++++++++--
.../streaming/api/operators/StreamOperator.java | 8 ++++++--
3 files changed, 41 insertions(+), 7 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..5a74523 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,28 @@ 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
+ * @see StreamOperator#finish()
+ */
@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)}.
+ *
+ * <p><b>NOTE:</b> Given it is semantically very similar to the {@link StreamOperator#finish()}
+ * method. It might be dropped in favour of the other method at some point in time.
+ */
void endInput() throws Exception;
}
diff --git a/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/StreamOperator.java b/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/StreamOperator.java
index 3916d13..134b912 100644
--- a/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/StreamOperator.java
+++ b/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/operators/StreamOperator.java
@@ -65,12 +65,16 @@ public interface StreamOperator<OUT> extends CheckpointListener, KeyContext, Ser
* This method is called at the end of data processing.
*
* <p>The method is expected to flush all remaining buffered data. Exceptions during this
- * flushing of buffered should be propagated, in order to cause the operation to be recognized
- * as failed, because the last data items are not processed properly.
+ * flushing of buffered data should be propagated, in order to cause the operation to be
+ * recognized as failed, because the last data items are not processed properly.
*
* <p><b>After this method is called, no more records can be produced for the downstream
* operators.</b>
*
+ * <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)}.
+ *
* <p><b>NOTE:</b>This method does not need to close any resources. You should release external
* resources in the {@link #close()} method.
*