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 <dwysakow...@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. *