Class SessionWindows


  • public final class SessionWindows
    extends 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 Detail

      • with

        @Deprecated
        public static SessionWindows with​(long inactivityGapMs)
        Deprecated.
        Use with(Duration) instead.
        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:
        IllegalArgumentException - if inactivityGapMs is zero or negative
      • with

        public static SessionWindows with​(Duration inactivityGap)
        Create a new window specification with the specified inactivity gap.
        Parameters:
        inactivityGap - the gap of inactivity between sessions
        Returns:
        a new window specification with default maintain duration of 1 day
        Throws:
        IllegalArgumentException - if inactivityGap is zero or negative or can't be represented as long milliseconds
      • grace

        public SessionWindows grace​(Duration afterWindowEnd)
                             throws IllegalArgumentException
        Reject out-of-order events that arrive more than afterWindowEnd after the end of its window.

        Note that new events may change the boundaries of session windows, so aggressive close times can lead to surprising results in which an out-of-order event is rejected and then a subsequent event moves the window boundary forward.

        Parameters:
        afterWindowEnd - The grace period to admit out-of-order events to a window.
        Returns:
        this updated builder
        Throws:
        IllegalArgumentException - if the afterWindowEnd is negative of can't be represented as long milliseconds
      • gracePeriodMs

        public long gracePeriodMs()
      • inactivityGap

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

        @Deprecated
        public long maintainMs()
        Deprecated.
        since 2.1. Use Materialized.retention instead.
        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
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object