Class TimeWindows
- java.lang.Object
-
- org.apache.kafka.streams.kstream.Windows<org.apache.kafka.streams.kstream.internals.TimeWindow>
-
- org.apache.kafka.streams.kstream.TimeWindows
-
public final class TimeWindows extends Windows<org.apache.kafka.streams.kstream.internals.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.
TimeWindow
s 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
. - If
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description TimeWindows
advanceBy(long advanceMs)
Deprecated.UseadvanceBy(Duration)
insteadTimeWindows
advanceBy(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(Object o)
TimeWindows
grace(Duration afterWindowEnd)
Reject out-of-order events that arrive more thanmillisAfterWindowEnd
after the end of its window.long
gracePeriodMs()
Return the window grace period (the time to admit out-of-order events after the end of the window.) Delay is defined as (stream_time - record_timestamp).int
hashCode()
long
maintainMs()
Deprecated.since 2.1.static TimeWindows
of(long sizeMs)
Deprecated.Useof(Duration)
insteadstatic TimeWindows
of(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.String
toString()
TimeWindows
until(long durationMs)
Deprecated.since 2.1.Map<Long,org.apache.kafka.streams.kstream.internals.TimeWindow>
windowsFor(long timestamp)
Create all windows that contain the provided timestamp, indexed by non-negative window start timestamps.
-
-
-
Method Detail
-
of
@Deprecated public static TimeWindows of(long sizeMs) throws IllegalArgumentException
Deprecated.Useof(Duration)
insteadReturn 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:
IllegalArgumentException
- if the specified window size is zero or negative
-
of
public static TimeWindows of(Duration size) throws 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:
IllegalArgumentException
- if the specified window size is zero or negative or can't be represented aslong milliseconds
-
advanceBy
@Deprecated public TimeWindows advanceBy(long advanceMs)
Deprecated.UseadvanceBy(Duration)
insteadReturn 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 that0 < advanceMs <= sizeMs
.- Returns:
- a new window definition with default maintain duration of 1 day
- Throws:
IllegalArgumentException
- if the advance interval is negative, zero, or larger than the window size
-
advanceBy
public TimeWindows advanceBy(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 that0 < advance.toMillis() <= sizeMs
.- Returns:
- a new window definition with default maintain duration of 1 day
- Throws:
IllegalArgumentException
- if the advance interval is negative, zero, or larger than the window size
-
windowsFor
public Map<Long,org.apache.kafka.streams.kstream.internals.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 classWindows<org.apache.kafka.streams.kstream.internals.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.
-
grace
public TimeWindows grace(Duration afterWindowEnd) throws IllegalArgumentException
Reject out-of-order events that arrive more thanmillisAfterWindowEnd
after the end of its window.Delay is defined as (stream_time - record_timestamp).
- Parameters:
afterWindowEnd
- The grace period to admit out-of-order events to a window.- Returns:
- this updated builder
- Throws:
IllegalArgumentException
- ifafterWindowEnd
is negative or can't be represented aslong milliseconds
-
gracePeriodMs
public long gracePeriodMs()
Description copied from class:Windows
Return the window grace period (the time to admit out-of-order events after the end of the window.) Delay is defined as (stream_time - record_timestamp).- Specified by:
gracePeriodMs
in classWindows<org.apache.kafka.streams.kstream.internals.TimeWindow>
-
until
@Deprecated public TimeWindows until(long durationMs) throws IllegalArgumentException
Deprecated.since 2.1. UseMaterialized.retention
or directly configure the retention in a store supplier and useMaterialized.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 classWindows<org.apache.kafka.streams.kstream.internals.TimeWindow>
- Parameters:
durationMs
- the window retention time- Returns:
- itself
- Throws:
IllegalArgumentException
- ifduration
is smaller than the window size
-
maintainMs
@Deprecated public long maintainMs()
Deprecated.since 2.1. UseMaterialized.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 classWindows<org.apache.kafka.streams.kstream.internals.TimeWindow>
- Returns:
- the window maintain duration
-
-