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, org.apache.kafka.common.serialization.Serde, org.apache.kafka.common.serialization.Serde, org.apache.kafka.common.serialization.Serde), KStream.leftJoin(KStream, ValueJoiner, JoinWindows), KStream.leftJoin(KStream, ValueJoiner, JoinWindows, org.apache.kafka.common.serialization.Serde, org.apache.kafka.common.serialization.Serde, org.apache.kafka.common.serialization.Serde), KStream.outerJoin(KStream, ValueJoiner, JoinWindows), KStream.outerJoin(KStream, ValueJoiner, JoinWindows), 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

Methods

Modifier and Type	Method and Description
JoinWindows	after(long timeDifferenceMs) Changes the end window boundary to timeDifferenceMs but keep the start window boundary as is.
JoinWindows	before(long timeDifferenceMs) Changes the start window boundary to timeDifferenceMs but keep the end window boundary as is.
boolean	equals(java.lang.Object o)
int	hashCode()
long	maintainMs() Return the window maintain duration (retention time) in milliseconds.
static JoinWindows	of(long timeDifferenceMs) 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.
long	size() Return the size of the specified windows in milliseconds.
JoinWindows	until(long durationMs) Set the window maintain duration (retention time) in milliseconds.
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, toString, 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

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

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

before

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

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 it's 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

after

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

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 it's 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

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

until

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

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

public long maintainMs()

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 final boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object