[jira] [Created] (FLINK-18283) [Javdoc] Update outdated Javadoc for clear method of ProcessWindowFunction

[Shang Yuanchun (Jira)]

Abhijit Shandilya created FLINK-18283:
-----------------------------------------

             Summary: [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


+*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)