[FLINK-18283] Update outdated Javadoc for clear method of ProcessWindowFunction

• Type: Improvement
• Status: Closed
• Priority: Minor
• Resolution: Fixed
• Fix Version/s: 1.11.0
• Component/s: API / Core, API / DataStream
• Labels: pull-request-available
• Assignee: Abhijit Shandilya
• Reporter: Abhijit Shandilya
• Created: 13/Jun/20 01:48
• Updated: 30/Jun/20 05:27
• Resolved: 23/Jun/20 13:45

Description

Summary:
Javadoc for ProcessWindowFunction has incorrect (outdated) information.

Description:
The current javadoc for ProcessWindowFunction clear method says

Deletes any state in the Context when the Window is purged.

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.

This change in behavior comes from this code change (repeated in a few other places) in FLINK-4994.

Proposed change:
I think we should change the description to say

Deletes any state in the Context when the Window expires (reaches its maxTimestamp).

Why this can be helpful:
The current documentation could be misleading. Developers will assume that the keyed per-window state will get cleared when a PURGE executes. But that won't 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: 

1. ProcessWindowFunction.scala
2. ProcessAllWindowFunction.scala
3. ProcessWindowFunction.java
4. ProcessAllWindowFunction.java
5. InternalWindowFunction.java 

I have a PR ready, which I can put out once the ticket is approved / assigned.

Issue Links

• links to: GitHub Pull Request #12735