cadonna commented on a change in pull request #11100:
URL: https://github.com/apache/kafka/pull/11100#discussion_r673778552
##########
File path: docs/streams/developer-guide/dsl-api.html
##########
@@ -3208,14 +3208,13 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable
Foreign-Key
import org.apache.kafka.streams.kstream.TimeWindows;
// A tumbling time window with a size of 5 minutes (and, by definition, an
implicit
-// advance interval of 5 minutes). Note the explicit grace period, as the
current
-// default value is 24 hours, which may be larger than needed for smaller
windows.
-Duration windowSizeMs = Duration.ofMinutes(5);
-Duration gracePeriodMs = Duration.ofMinutes(1);
-TimeWindows.of(windowSizeMs).grace(gracePeriodMs);
+// advance interval of 5 minutes).
+Duration windowSize = Duration.ofMinutes(5);
+Duration gracePeriod = Duration.ofMinutes(1);
Review comment:
Here I would either mention the grace period in the comment above or
remove the grace period completely. Otherwise, it comes a bit as a surprise
that a grace period is specified.
##########
File path: docs/streams/developer-guide/dsl-api.html
##########
@@ -3230,13 +3229,13 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable
Foreign-Key
<pre class="line-numbers"><code
class="language-java">import org.apache.kafka.streams.kstream.SlidingWindows;
// A sliding time window with a time difference of 10 minutes and grace period
of 30 minutes
-Duration timeDifferenceMs = Duration.ofMinutes(10);
-Duration gracePeriodMs = Duration.ofMinutes(30);
-SlidingWindows.withTimeDifferenceAndGrace(timeDifferenceMs,gracePeriodMs);</code></pre>
+Duration timeDifference = Duration.ofMinutes(10);
+Duration gracePeriod = Duration.ofMinutes(30);
+SlidingWindows.ofTimeDifferenceAndGrace(timeDifference,
gracePeriod);</code></pre>
<div class="admonition note">
<p><b>Note</b></p>
<p>Sliding windows <em>require</em> that you set
a grace period, as shown above. For time windows and session windows,
- setting the grace period is optional and
defaults to 24 hours.</p>
+ setting the grace period is optional.</p>
Review comment:
That is not true anymore. More precisely, it is only true for deprecated
methods, that we do not want to mention in the docs, right? Maybe you can even
remove the note completely, since it explains a difference between sliding
windows and other windows that does not exist anymore.
##########
File path: docs/streams/developer-guide/dsl-api.html
##########
@@ -3322,8 +3321,8 @@ <h5><a class="toc-backref" href="#id34">KTable-KTable
Foreign-Key
</div></div>
<p>The key parts of this program are:
<dl>
- <dt><code>grace(ofMinutes(10))</code></dt>
- <dd>This allows us to bound the lateness of
events the window will accept.
+
<dt><code>ofSizeAndGrace(Duration.ofHours(1), ofMinutes(10))</code></dt>
+ <dd>The <code>ofMinutes(10)</code>
parameter allows us to bound the lateness of events the window will accept.
Review comment:
```suggestion
<dd>The specified grace period of 10
minutes (i.e., the <code>ofMinutes(10)</code> argument) allows us to bound the
lateness of events the window will accept.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
