Class TimeWindows


  • public final class TimeWindows
    extends Windows<TimeWindow>
    The fixed-size time-based window specifications used for aggregations.

    The semantics of time-based aggregation windows are: Every T1 (advance) milliseconds, compute the aggregate total for T2 (size) milliseconds.

    • If advance < size a hopping windows is defined:
      it discretize a stream into overlapping windows, which implies that a record maybe contained in one and or more "adjacent" windows.
    • If advance == size a tumbling window is defined:
      it discretize a stream into non-overlapping windows, which implies that a record is only ever contained in one and only one tumbling window.
    Thus, the specified TimeWindows are aligned to the epoch. Aligned to the epoch means, that the first window starts at timestamp zero. For example, hopping windows with size of 5000ms and advance of 3000ms, have window boundaries [0;5000),[3000;8000),... and not [1000;6000),[4000;9000),... or even something "random" like [1452;6452),[4452;9452),...

    For time semantics, see TimestampExtractor.

    See Also:
    SessionWindows, UnlimitedWindows, JoinWindows, KGroupedStream.windowedBy(Windows), TimestampExtractor
    • Field Summary

      Fields 
      Modifier and Type Field Description
      long advanceMs
      The size of the window's advance interval in milliseconds, i.e., by how much a window moves forward relative to the previous one.
      long sizeMs
      The size of the windows in milliseconds.
      • Fields inherited from class org.apache.kafka.streams.kstream.Windows

        segments
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      TimeWindows advanceBy​(long advanceMs)
      Deprecated.
      TimeWindows advanceBy​(java.time.Duration advance)
      Return a window definition with the original size, but advance ("hop") the window by the given interval, which specifies by how much a window moves forward relative to the previous one.
      boolean equals​(java.lang.Object o)  
      TimeWindows grace​(java.time.Duration afterWindowEnd)
      Reject late events that arrive more than millisAfterWindowEnd after the end of its window.
      long gracePeriodMs()
      Return the window grace period (the time to admit late-arriving events after the end of the window.) Lateness is defined as (stream_time - record_timestamp).
      int hashCode()  
      long maintainMs()
      Deprecated.
      since 2.1.
      static TimeWindows of​(long sizeMs)
      Deprecated.
      Use of(Duration) instead
      static TimeWindows of​(java.time.Duration size)
      Return a window definition with the given window size, and with the advance interval being equal to the window size.
      long size()
      Return the size of the specified windows in milliseconds.
      java.lang.String toString()  
      TimeWindows until​(long durationMs)
      Deprecated.
      since 2.1.
      java.util.Map<java.lang.Long,​TimeWindow> windowsFor​(long timestamp)
      Create all windows that contain the provided timestamp, indexed by non-negative window start timestamps.
      • Methods inherited from class org.apache.kafka.streams.kstream.Windows

        segments
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • sizeMs

        public final long sizeMs
        The size of the windows in milliseconds.
      • advanceMs

        public final long advanceMs
        The size of the window's advance interval in milliseconds, i.e., by how much a window moves forward relative to the previous one.
    • Method Detail

      • of

        @Deprecated
        public static TimeWindows of​(long sizeMs)
                              throws java.lang.IllegalArgumentException
        Deprecated.
        Use of(Duration) instead
        Return a window definition with the given window size, and with the advance interval being equal to the window size. The time interval represented by the N-th window is: [N * size, N * size + size).

        This provides the semantics of tumbling windows, which are fixed-sized, gap-less, non-overlapping windows. Tumbling windows are a special case of hopping windows with advance == size.

        Parameters:
        sizeMs - The size of the window in milliseconds
        Returns:
        a new window definition with default maintain duration of 1 day
        Throws:
        java.lang.IllegalArgumentException - if the specified window size is zero or negative
      • of

        public static TimeWindows of​(java.time.Duration size)
                              throws java.lang.IllegalArgumentException
        Return a window definition with the given window size, and with the advance interval being equal to the window size. The time interval represented by the N-th window is: [N * size, N * size + size).

        This provides the semantics of tumbling windows, which are fixed-sized, gap-less, non-overlapping windows. Tumbling windows are a special case of hopping windows with advance == size.

        Parameters:
        size - The size of the window
        Returns:
        a new window definition with default maintain duration of 1 day
        Throws:
        java.lang.IllegalArgumentException - if the specified window size is zero or negative or can't be represented as long milliseconds
      • advanceBy

        @Deprecated
        public TimeWindows advanceBy​(long advanceMs)
        Deprecated.
        Return a window definition with the original size, but advance ("hop") the window by the given interval, which specifies by how much a window moves forward relative to the previous one. The time interval represented by the N-th window is: [N * advance, N * advance + size).

        This provides the semantics of hopping windows, which are fixed-sized, overlapping windows.

        Parameters:
        advanceMs - The advance interval ("hop") in milliseconds of the window, with the requirement that 0 < advanceMs <= sizeMs.
        Returns:
        a new window definition with default maintain duration of 1 day
        Throws:
        java.lang.IllegalArgumentException - if the advance interval is negative, zero, or larger-or-equal the window size
      • advanceBy

        public TimeWindows advanceBy​(java.time.Duration advance)
        Return a window definition with the original size, but advance ("hop") the window by the given interval, which specifies by how much a window moves forward relative to the previous one. The time interval represented by the N-th window is: [N * advance, N * advance + size).

        This provides the semantics of hopping windows, which are fixed-sized, overlapping windows.

        Parameters:
        advance - The advance interval ("hop") of the window, with the requirement that 0 < advance.toMillis() <= sizeMs.
        Returns:
        a new window definition with default maintain duration of 1 day
        Throws:
        java.lang.IllegalArgumentException - if the advance interval is negative, zero, or larger-or-equal the window size
      • windowsFor

        public java.util.Map<java.lang.Long,​TimeWindow> windowsFor​(long timestamp)
        Description copied from class: Windows
        Create all windows that contain the provided timestamp, indexed by non-negative window start timestamps.
        Specified by:
        windowsFor in class Windows<TimeWindow>
        Parameters:
        timestamp - the timestamp window should get created for
        Returns:
        a map of windowStartTimestamp -> Window entries
      • size

        public long size()
        Description copied from class: Windows
        Return the size of the specified windows in milliseconds.
        Specified by:
        size in class Windows<TimeWindow>
        Returns:
        the size of the specified windows
      • grace

        public TimeWindows grace​(java.time.Duration afterWindowEnd)
                          throws java.lang.IllegalArgumentException
        Reject late events that arrive more than millisAfterWindowEnd after the end of its window. Lateness is defined as (stream_time - record_timestamp).
        Parameters:
        afterWindowEnd - The grace period to admit late-arriving events to a window.
        Returns:
        this updated builder
        Throws:
        java.lang.IllegalArgumentException - if afterWindowEnd is negative or can't be represented as long milliseconds
      • gracePeriodMs

        public long gracePeriodMs()
        Description copied from class: Windows
        Return the window grace period (the time to admit late-arriving events after the end of the window.) Lateness is defined as (stream_time - record_timestamp).
        Specified by:
        gracePeriodMs in class Windows<TimeWindow>
      • until

        @Deprecated
        public TimeWindows 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(WindowBytesStoreSupplier).
        Description copied from class: Windows
        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.
        Overrides:
        until in class Windows<TimeWindow>
        Parameters:
        durationMs - the window retention time
        Returns:
        itself
        Throws:
        java.lang.IllegalArgumentException - if duration is smaller than the window size
      • maintainMs

        @Deprecated
        public long maintainMs()
        Deprecated.
        since 2.1. Use Materialized.retention instead.
        Return the window maintain duration (retention time) in milliseconds.

        For TimeWindows the maintain duration is at least as small as the window size.

        Overrides:
        maintainMs in class Windows<TimeWindow>
        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