[GitHub] [kafka] cadonna commented on a change in pull request #11100: MINOR: update doc to reflect the grace period change

[GitBox <gi...@apache.org>]

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: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org