org.apache.kafka.streams.kstream

Class JoinWindows

java.lang.Object

org.apache.kafka.streams.kstream.Windows<Window>

org.apache.kafka.streams.kstream.JoinWindows

public final class JoinWindows
extends Windows<Window>

The window specifications used for joins.

A JoinWindows instance defines a maximum time difference for a join over two streams on the same key. In SQL-style you would express this join as

     SELECT * FROM stream1, stream2
     WHERE
       stream1.key = stream2.key
       AND
       stream1.ts - before <= stream2.ts AND stream2.ts <= stream1.ts + after
 

There are three different window configuration supported:

• before = after = time-difference
• before = 0 and after = time-difference
• before = time-difference and after = 0

A join is symmetric in the sense, that a join specification on the first stream returns the same result record as a join specification on the second stream with flipped before and after values.

Both values (before and after) must not result in an "inverse" window, i.e., upper-interval bound cannot be smaller than lower-interval bound.

JoinWindows are sliding windows, thus, they are aligned to the actual record timestamps. This implies, that each input record defines its own window with start and end time being relative to the record's timestamp.

For time semantics, see TimestampExtractor.

See Also:

TimeWindows, UnlimitedWindows, SessionWindows, KStream.join(KStream, ValueJoiner, JoinWindows), KStream.join(KStream, ValueJoiner, JoinWindows, Joined), KStream.leftJoin(KStream, ValueJoiner, JoinWindows), KStream.leftJoin(KStream, ValueJoiner, JoinWindows, Joined), KStream.outerJoin(KStream, ValueJoiner, JoinWindows), KStream.outerJoin(KStream, ValueJoiner, JoinWindows, Joined), TimestampExtractor

Field Summary

Fields

Modifier and Type	Field and Description
long	afterMs Maximum time difference for tuples that are after the join tuple.
long	beforeMs Maximum time difference for tuples that are before the join tuple.

Fields inherited from class org.apache.kafka.streams.kstream.Windows

segments

Method Summary

Modifier and Type	Method and Description
JoinWindows	after(java.time.Duration timeDifference) Changes the end window boundary to timeDifference but keep the start window boundary as is.
JoinWindows	after(long timeDifferenceMs) Deprecated. Use after(Duration) instead
JoinWindows	before(java.time.Duration timeDifference) Changes the start window boundary to timeDifference but keep the end window boundary as is.
JoinWindows	before(long timeDifferenceMs) Deprecated. Use before(Duration) instead.
boolean	equals(java.lang.Object o)
JoinWindows	grace(java.time.Duration afterWindowEnd) Reject late events that arrive more than afterWindowEnd 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. This function should not be used anymore as retention period can be specified via Materialized.withRetention(Duration).
static JoinWindows	of(java.time.Duration timeDifference) Specifies that records of the same key are joinable if their timestamps are within timeDifference, i.e., the timestamp of a record from the secondary stream is max timeDifference earlier or later than the timestamp of the record from the primary stream.
static JoinWindows	of(long timeDifferenceMs) Deprecated. Use of(Duration) instead.
long	size() Return the size of the specified windows in milliseconds.
java.lang.String	toString()
JoinWindows	until(long durationMs) Deprecated. since 2.1. Use Materialized.withRetention(Duration) instead.
java.util.Map<java.lang.Long,Window>	windowsFor(long timestamp) Not supported by JoinWindows.

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

beforeMs

public final long beforeMs

Maximum time difference for tuples that are before the join tuple.

afterMs

public final long afterMs

Maximum time difference for tuples that are after the join tuple.

Method Detail

of

@Deprecated
public static JoinWindows of(long timeDifferenceMs)
                                  throws java.lang.IllegalArgumentException

Deprecated. Use of(Duration) instead.

Specifies that records of the same key are joinable if their timestamps are within timeDifferenceMs, i.e., the timestamp of a record from the secondary stream is max timeDifferenceMs earlier or later than the timestamp of the record from the primary stream.

Parameters:

timeDifferenceMs - join window interval in milliseconds

Throws:

java.lang.IllegalArgumentException - if timeDifferenceMs is negative

of

public static JoinWindows of(java.time.Duration timeDifference)
                      throws java.lang.IllegalArgumentException

Specifies that records of the same key are joinable if their timestamps are within timeDifference, i.e., the timestamp of a record from the secondary stream is max timeDifference earlier or later than the timestamp of the record from the primary stream.

Parameters:

timeDifference - join window interval

Throws:

java.lang.IllegalArgumentException - if timeDifference is negative or can't be represented as long milliseconds

before

@Deprecated
public JoinWindows before(long timeDifferenceMs)
                               throws java.lang.IllegalArgumentException

Deprecated. Use before(Duration) instead.

Changes the start window boundary to timeDifferenceMs but keep the end window boundary as is. Thus, records of the same key are joinable if the timestamp of a record from the secondary stream is at most timeDifferenceMs earlier than the timestamp of the record from the primary stream. timeDifferenceMs can be negative but its absolute value must not be larger than current window "after" value (which would result in a negative window size).

Parameters:

timeDifferenceMs - relative window start time in milliseconds

Throws:

java.lang.IllegalArgumentException - if the resulting window size is negative

before

public JoinWindows before(java.time.Duration timeDifference)
                   throws java.lang.IllegalArgumentException

Changes the start window boundary to timeDifference but keep the end window boundary as is. Thus, records of the same key are joinable if the timestamp of a record from the secondary stream is at most timeDifference earlier than the timestamp of the record from the primary stream. timeDifference can be negative but its absolute value must not be larger than current window "after" value (which would result in a negative window size).

Parameters:

timeDifference - relative window start time

Throws:

java.lang.IllegalArgumentException - if the resulting window size is negative or timeDifference can't be represented as long milliseconds

after

@Deprecated
public JoinWindows after(long timeDifferenceMs)
                              throws java.lang.IllegalArgumentException

Deprecated. Use after(Duration) instead

Changes the end window boundary to timeDifferenceMs but keep the start window boundary as is. Thus, records of the same key are joinable if the timestamp of a record from the secondary stream is at most timeDifferenceMs later than the timestamp of the record from the primary stream. timeDifferenceMs can be negative but its absolute value must not be larger than current window "before" value (which would result in a negative window size).

Parameters:

timeDifferenceMs - relative window end time in milliseconds

Throws:

java.lang.IllegalArgumentException - if the resulting window size is negative

after

public JoinWindows after(java.time.Duration timeDifference)
                  throws java.lang.IllegalArgumentException

Changes the end window boundary to timeDifference but keep the start window boundary as is. Thus, records of the same key are joinable if the timestamp of a record from the secondary stream is at most timeDifference later than the timestamp of the record from the primary stream. timeDifference can be negative but its absolute value must not be larger than current window "before" value (which would result in a negative window size).

Parameters:

timeDifference - relative window end time

Throws:

java.lang.IllegalArgumentException - if the resulting window size is negative or timeDifference can't be represented as long milliseconds

windowsFor

public java.util.Map<java.lang.Long,Window> windowsFor(long timestamp)

Not supported by JoinWindows. Throws UnsupportedOperationException.

Specified by:

windowsFor in class Windows<Window>

Parameters:

timestamp - the timestamp window should get created for

Returns:

a map of windowStartTimestamp -> Window entries

Throws:

java.lang.UnsupportedOperationException - at every invocation

size

public long size()

Description copied from class: Windows

Return the size of the specified windows in milliseconds.

Specified by:

size in class Windows<Window>

Returns:

the size of the specified windows

grace

public JoinWindows grace(java.time.Duration afterWindowEnd)
                  throws java.lang.IllegalArgumentException

Reject late events that arrive more than afterWindowEnd 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 the afterWindowEnd is negative of 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<Window>

until

@Deprecated
public JoinWindows until(long durationMs)
                              throws java.lang.IllegalArgumentException

Deprecated. since 2.1. Use Materialized.withRetention(Duration) instead.

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<Window>

Parameters:

durationMs - the window retention time in milliseconds

Returns:

itself

Throws:

java.lang.IllegalArgumentException - if durationMs is smaller than the window size

maintainMs

@Deprecated
public long maintainMs()

Deprecated. since 2.1. This function should not be used anymore as retention period can be specified via Materialized.withRetention(Duration).

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<Window>

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