Package org.apache.kafka.streams.kstream

Class SessionWindows

  • public final class SessionWindows
extends java.lang.Object
    A session based window specification used for aggregating events into sessions.

    Sessions represent a period of activity separated by a defined gap of inactivity. Any events processed that fall within the inactivity gap of any existing sessions are merged into the existing sessions. If the event falls outside of the session gap then a new session will be created.

    For example, if we have a session gap of 5 and the following data arrives: 

     +--------------------------------------+
 |    key    |    value    |    time    |
 +-----------+-------------+------------+
 |    A      |     1       |     10     |
 +-----------+-------------+------------+
 |    A      |     2       |     12     |
 +-----------+-------------+------------+
 |    A      |     3       |     20     |
 +-----------+-------------+------------+
    We'd have 2 sessions for key A. One starting from time 10 and ending at time 12 and another starting and ending at time 20. The length of the session is driven by the timestamps of the data within the session. Thus, session windows are no fixed-size windows (c.f. TimeWindows and JoinWindows).

    If we then received another record: 

     +--------------------------------------+
 |    key    |    value    |    time    |
 +-----------+-------------+------------+
 |    A      |     4       |     16     |
 +-----------+-------------+------------+
    The previous 2 sessions would be merged into a single session with start time 10 and end time 20. The aggregate value for this session would be the result of aggregating all 4 values.

    For time semantics, see TimestampExtractor.

    See Also:
    TimeWindows, UnlimitedWindows, JoinWindows, KGroupedStream.windowedBy(SessionWindows), TimestampExtractor

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object o)  
      int hashCode()  
      long inactivityGap()
      Return the specified gap for the session windows in milliseconds.
      long maintainMs()
      Return the window maintain duration (retention time) in milliseconds.
      SessionWindows until​(long durationMs)
      Set the window maintain duration (retention time) in milliseconds.
      static SessionWindows with​(long inactivityGapMs)
      Create a new window specification with the specified inactivity gap in milliseconds.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • with

        public static SessionWindows with​(long inactivityGapMs)
        Create a new window specification with the specified inactivity gap in milliseconds.
        Parameters:
        inactivityGapMs - the gap of inactivity between sessions in milliseconds
        Returns:
        a new window specification with default maintain duration of 1 day
        Throws:
        java.lang.IllegalArgumentException - if inactivityGapMs is zero or negative

      • until

        public SessionWindows until​(long durationMs)
                     throws java.lang.IllegalArgumentException
        Set the window maintain duration (retention time) in milliseconds. This retention time is a guaranteed lower bound for how long a window will be maintained.
        Returns:
        itself
        Throws:
        java.lang.IllegalArgumentException - if durationMs is smaller than window gap

      • inactivityGap

        public long inactivityGap()
        Return the specified gap for the session windows in milliseconds.
        Returns:
        the inactivity gap of the specified windows

      • maintainMs

        public long maintainMs()
        Return the window maintain duration (retention time) in milliseconds.

        For SessionWindows the maintain duration is at least as small as the window gap.

        Returns:
        the window maintain duration

      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object