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 Detail

      • with

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

        public static SessionWindows with​(java.time.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:
        java.lang.IllegalArgumentException - if inactivityGap is zero or negative or can't be represented as long milliseconds
      • until

        @Deprecated
        public SessionWindows until​(long durationMs)
                             throws java.lang.IllegalArgumentException
        Deprecated.
        since 2.1. Use Materialized.retention or directly configure the retention in a store supplier and use Materialized.as(SessionBytesStoreSupplier).
        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
      • grace

        public SessionWindows grace​(java.time.Duration afterWindowEnd)
                             throws java.lang.IllegalArgumentException
        Reject late 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 a too-late event is rejected and then a subsequent event moves the window boundary forward.
        Parameters:
        afterWindowEnd - The grace period to admit late-arriving events to a window.
        Returns:
        this updated builder
        Throws:
        java.lang.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
      • 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
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object