[
https://issues.apache.org/jira/browse/FLINK-18283?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Abhijit Shandilya updated FLINK-18283:
--------------------------------------
Description:
+*Summary:*+
Javadoc for ProcessWindowFunction is has incorrect (outdated) information.
+*Description:*+
The current javadoc for
[ProcessWindowFunction|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.html]
[clear|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.html#clear-org.apache.flink.streaming.api.functions.windowing.ProcessWindowFunction.Context-]
method says
{quote}Deletes any state in the Context when the Window is purged.
{quote}
But, this is not true anymore. This behavior was changed in FLINK-4994.
Before FLINK-4994, when Trigger.PURGE was called, it would invoke
ProcessWindowFunction's clear( ) method to clean up all keyed per-window state.
But after FLINK-4994, ProcessWindowFunction's clear is called only when the
window expires, which is to say the window reaches its
[window.maxTimestamp|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/windowing/windows/Window.html#maxTimestamp--].
This change in behavior comes from
[this|https://github.com/apache/flink/commit/0b331a421267a541d91e94f2713534704ed32bed#diff-408a499e1a35840c52e29b7ccab866b1R461-R464]
code change (repeated in a few other places) in FLINK-4994.
+*Proposed change:*+
I think we should change the description to say
{quote}Deletes any state in the Context when the Window expires (reaches its
[maxTimestamp|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/windowing/windows/Window.html#maxTimestamp--]).
{quote}
+*Why this can be helpful:*+
The current documentation could be misleading. Developers may expect to get
the _keyed per-window state_ cleared when a PURGE happens. But this will not
happen. I myself had to go through flink source code to identify the
disconnect. Updating the javadoc can help future users to avoid such confusions.
+*Links to lines of code that will need updating:*+ #
[ProcessWindowFunction.scala|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-scala/src/main/scala/org/apache/flink/streaming/api/scala/function/ProcessWindowFunction.scala#L54]
#
[ProcessAllWindowFunction.scala|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-scala/src/main/scala/org/apache/flink/streaming/api/scala/function/ProcessAllWindowFunction.scala#L51]
#
[ProcessWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.java#L55]
#
[ProcessAllWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/functions/windowing/ProcessAllWindowFunction.java#L53]
#
[InternalWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/runtime/operators/windowing/functions/InternalWindowFunction.java#L47]
was:
+*Summary:*+
Javadoc for ProcessWindowFunction is has incorrect (outdated) information.
+*Description:*+
The current javadoc for
[ProcessWindowFunction|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.html]
[clear|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.html#clear-org.apache.flink.streaming.api.functions.windowing.ProcessWindowFunction.Context-]
method says
{quote}Deletes any state in the Context when the Window is purged.{quote}
But, this is not true anymore. This behavior was changed in FLINK-4994.
Before FLINK-4994, when Trigger.PURGE was called, it would invoke
ProcessWindowFunction's clear( ) method to clean up all keyed per-window state.
But after FLINK-4994, ProcessWindowFunction's clear is called only when the
window expires, which is to say the window reaches its [window.maxTimestamp()
|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/windowing/windows/Window.html#maxTimestamp--]
This change in behavior comes from
[this|https://github.com/apache/flink/commit/0b331a421267a541d91e94f2713534704ed32bed#diff-408a499e1a35840c52e29b7ccab866b1R461-R464]
code change (repeated in a few other places) in FLINK-4994.
+*Proposed change:*+
I think we should change the description to say
{quote}Deletes any state in the Context when the Window expires (reaches its
[maxTimestamp|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/windowing/windows/Window.html#maxTimestamp--]).{quote}
+*Why this can be helpful:*+
The current documentation could be misleading. Developers may expect to get the
_keyed per-window state_ cleared when a PURGE happens. But this will not
happen. I myself had to go through flink source code to identify the
disconnect. Updating the javadoc can help future users to avoid such confusions.
+*Links to lines of code that will need updating:*+ #
[ProcessWindowFunction.scala|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-scala/src/main/scala/org/apache/flink/streaming/api/scala/function/ProcessWindowFunction.scala#L54]
#
[ProcessAllWindowFunction.scala|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-scala/src/main/scala/org/apache/flink/streaming/api/scala/function/ProcessAllWindowFunction.scala#L51]
#
[ProcessWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.java#L55]
#
[ProcessAllWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/functions/windowing/ProcessAllWindowFunction.java#L53]
#
[InternalWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/runtime/operators/windowing/functions/InternalWindowFunction.java#L47]
> [Javdoc] Update outdated Javadoc for clear method of ProcessWindowFunction
> --------------------------------------------------------------------------
>
> Key: FLINK-18283
> URL: https://issues.apache.org/jira/browse/FLINK-18283
> Project: Flink
> Issue Type: Improvement
> Components: API / Core
> Reporter: Abhijit Shandilya
> Priority: Minor
> Labels: JavaDoc, ProcessWindowFunction
> Original Estimate: 2h
> Remaining Estimate: 2h
>
> +*Summary:*+
> Javadoc for ProcessWindowFunction is has incorrect (outdated) information.
> +*Description:*+
> The current javadoc for
> [ProcessWindowFunction|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.html]
>
> [clear|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.html#clear-org.apache.flink.streaming.api.functions.windowing.ProcessWindowFunction.Context-]
> method says
> {quote}Deletes any state in the Context when the Window is purged.
> {quote}
> But, this is not true anymore. This behavior was changed in FLINK-4994.
> Before FLINK-4994, when Trigger.PURGE was called, it would invoke
> ProcessWindowFunction's clear( ) method to clean up all keyed per-window
> state.
> But after FLINK-4994, ProcessWindowFunction's clear is called only when the
> window expires, which is to say the window reaches its
> [window.maxTimestamp|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/windowing/windows/Window.html#maxTimestamp--].
> This change in behavior comes from
> [this|https://github.com/apache/flink/commit/0b331a421267a541d91e94f2713534704ed32bed#diff-408a499e1a35840c52e29b7ccab866b1R461-R464]
> code change (repeated in a few other places) in FLINK-4994.
> +*Proposed change:*+
> I think we should change the description to say
> {quote}Deletes any state in the Context when the Window expires (reaches its
> [maxTimestamp|https://ci.apache.org/projects/flink/flink-docs-release-1.10/api/java/org/apache/flink/streaming/api/windowing/windows/Window.html#maxTimestamp--]).
> {quote}
> +*Why this can be helpful:*+
> The current documentation could be misleading. Developers may expect to get
> the _keyed per-window state_ cleared when a PURGE happens. But this will not
> happen. I myself had to go through flink source code to identify the
> disconnect. Updating the javadoc can help future users to avoid such
> confusions.
> +*Links to lines of code that will need updating:*+ #
> [ProcessWindowFunction.scala|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-scala/src/main/scala/org/apache/flink/streaming/api/scala/function/ProcessWindowFunction.scala#L54]
> #
> [ProcessAllWindowFunction.scala|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-scala/src/main/scala/org/apache/flink/streaming/api/scala/function/ProcessAllWindowFunction.scala#L51]
> #
> [ProcessWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/functions/windowing/ProcessWindowFunction.java#L55]
> #
> [ProcessAllWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/api/functions/windowing/ProcessAllWindowFunction.java#L53]
> #
> [InternalWindowFunction.java|https://github.com/apache/flink/blob/8674b69964eae50cad024f2c5caf92a71bf21a09/flink-streaming-java/src/main/java/org/apache/flink/streaming/runtime/operators/windowing/functions/InternalWindowFunction.java#L47]
>
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
