org.apache.kafka.streams.kstream

Class SessionWindows

java.lang.Object

org.apache.kafka.streams.kstream.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 Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
SessionWindows	grace(Duration afterWindowEnd) Reject out-of-order events that arrive more than afterWindowEnd after the end of its window.
long	gracePeriodMs()
int	hashCode()
long	inactivityGap() Return the specified gap for the session windows in milliseconds.
long	maintainMs() Deprecated. since 2.1. Use Materialized.retention instead.
String	toString()
SessionWindows	until(long durationMs) Deprecated. since 2.1. Use Materialized.retention or directly configure the retention in a store supplier and use Materialized.as(SessionBytesStoreSupplier).
static SessionWindows	with(Duration inactivityGap) Create a new window specification with the specified inactivity gap.
static SessionWindows	with(long inactivityGapMs) Deprecated. Use with(Duration) instead.

Methods inherited from class java.lang.Object

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

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

until

@Deprecated
public SessionWindows until(long durationMs)
                                 throws 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:

IllegalArgumentException - if durationMs is smaller than window gap

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

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object