org.apache.kafka.streams.state

Interface SessionStore<K,AGG>

Type Parameters:

K - type of the record keys

AGG - type of the aggregated values

All Superinterfaces:

ReadOnlySessionStore<K,AGG>, StateStore

public interface SessionStore<K,AGG>
extends StateStore, ReadOnlySessionStore<K,AGG>

Interface for storing the aggregated values of sessions.

The key is internally represented as Windowed<K> that comprises the plain key and the Window that represents window start- and end-timestamp.

If two sessions are merged, a new session with new start- and end-timestamp must be inserted into the store while the two old sessions must be deleted.

Method Summary

Modifier and Type	Method and Description
default KeyValueIterator<Windowed<K>,AGG>	backwardFindSessions(K key, Instant earliestSessionEndTime, Instant latestSessionStartTime) Fetch any sessions with the matching key and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from latest to earliest.
default KeyValueIterator<Windowed<K>,AGG>	backwardFindSessions(K keyFrom, K keyTo, Instant earliestSessionEndTime, Instant latestSessionStartTime) Fetch any sessions in the given range of keys and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from latest to earliest.
default AGG	fetchSession(K key, Instant sessionStartTime, Instant sessionEndTime) Get the value of key from a single session.
default KeyValueIterator<Windowed<K>,AGG>	findSessions(K key, Instant earliestSessionEndTime, Instant latestSessionStartTime) Fetch any sessions with the matching key and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from earliest to latest.
default KeyValueIterator<Windowed<K>,AGG>	findSessions(K keyFrom, K keyTo, Instant earliestSessionEndTime, Instant latestSessionStartTime) Fetch any sessions in the given range of keys and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from earliest to latest.
default KeyValueIterator<Windowed<K>,AGG>	findSessions(long earliestSessionEndTime, long latestSessionEndTime) Return all the session window entries that ends between the specified range (both ends are inclusive).
void	put(Windowed<K> sessionKey, AGG aggregate) Write the aggregated value for the provided key to the store
void	remove(Windowed<K> sessionKey) Remove the session aggregated with provided Windowed key from the store

Methods inherited from interface org.apache.kafka.streams.processor.StateStore

close, flush, getPosition, init, init, isOpen, name, persistent, query

Methods inherited from interface org.apache.kafka.streams.state.ReadOnlySessionStore

backwardFetch, backwardFetch, backwardFindSessions, backwardFindSessions, fetch, fetch, fetchSession, findSessions, findSessions

Method Detail

findSessions

default KeyValueIterator<Windowed<K>,AGG> findSessions(long earliestSessionEndTime,
                                                       long latestSessionEndTime)

Return all the session window entries that ends between the specified range (both ends are inclusive). This function would be used to retrieve all closed and immutable windows.

Parameters:

earliestSessionEndTime - earliest session end time to search from, inclusive

latestSessionEndTime - latest session end time to search to, inclusive

findSessions

default KeyValueIterator<Windowed<K>,AGG> findSessions(K key,
                                                       Instant earliestSessionEndTime,
                                                       Instant latestSessionStartTime)

Description copied from interface: ReadOnlySessionStore

Fetch any sessions with the matching key and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from earliest to latest. I.e., earliestSessionEndTime is the lower bound of the search interval and latestSessionStartTime is the upper bound of the search interval, and the method returns all sessions that overlap with the search interval. Thus, if a session ends before earliestSessionEndTime, or starts after latestSessionStartTime if won't be contained in the result:

 earliestSessionEndTime: ESET
 latestSessionStartTime: LSST

                       [ESET............LSST]
 [not-included] [included]   [included]   [included] [not-included]
 

This iterator must be closed after use.

Specified by:

findSessions in interface ReadOnlySessionStore<K,AGG>

Parameters:

key - the key to return sessions for

earliestSessionEndTime - the end timestamp of the earliest session to search for, where iteration starts.

latestSessionStartTime - the end timestamp of the latest session to search for, where iteration ends.

Returns:

iterator of sessions with the matching key and aggregated values, from earliest to latest session time.

backwardFindSessions

default KeyValueIterator<Windowed<K>,AGG> backwardFindSessions(K key,
                                                               Instant earliestSessionEndTime,
                                                               Instant latestSessionStartTime)

Description copied from interface: ReadOnlySessionStore

Fetch any sessions with the matching key and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from latest to earliest. I.e., earliestSessionEndTime is the lower bound of the search interval and latestSessionStartTime is the upper bound of the search interval, and the method returns all sessions that overlap with the search interval. Thus, if a session ends before earliestSessionEndTime, or starts after latestSessionStartTime if won't be contained in the result:

 earliestSessionEndTime: ESET
 latestSessionStartTime: LSST

                       [ESET............LSST]
 [not-included] [included]   [included]   [included] [not-included]
 

This iterator must be closed after use.

Specified by:

backwardFindSessions in interface ReadOnlySessionStore<K,AGG>

Parameters:

key - the key to return sessions for

earliestSessionEndTime - the end timestamp of the earliest session to search for, where iteration ends.

latestSessionStartTime - the end timestamp of the latest session to search for, where iteration starts.

Returns:

backward iterator of sessions with the matching key and aggregated values, from latest to earliest session time.

findSessions

default KeyValueIterator<Windowed<K>,AGG> findSessions(K keyFrom,
                                                       K keyTo,
                                                       Instant earliestSessionEndTime,
                                                       Instant latestSessionStartTime)

Description copied from interface: ReadOnlySessionStore

Fetch any sessions in the given range of keys and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from earliest to latest. I.e., earliestSessionEndTime is the lower bound of the search interval and latestSessionStartTime is the upper bound of the search interval, and the method returns all sessions that overlap with the search interval. Thus, if a session ends before earliestSessionEndTime, or starts after latestSessionStartTime if won't be contained in the result:

 earliestSessionEndTime: ESET
 latestSessionStartTime: LSST

                       [ESET............LSST]
 [not-included] [included]   [included]   [included] [not-included]
 

This iterator must be closed after use.

Specified by:

findSessions in interface ReadOnlySessionStore<K,AGG>

Parameters:

keyFrom - The first key that could be in the range A null value indicates a starting position from the first element in the store.

keyTo - The last key that could be in the range A null value indicates that the range ends with the last element in the store.

earliestSessionEndTime - the end timestamp of the earliest session to search for, where iteration starts.

latestSessionStartTime - the end timestamp of the latest session to search for, where iteration ends.

Returns:

iterator of sessions with the matching keys and aggregated values, from earliest to latest session time.

backwardFindSessions

default KeyValueIterator<Windowed<K>,AGG> backwardFindSessions(K keyFrom,
                                                               K keyTo,
                                                               Instant earliestSessionEndTime,
                                                               Instant latestSessionStartTime)

Description copied from interface: ReadOnlySessionStore

Fetch any sessions in the given range of keys and the sessions end is ≥ earliestSessionEndTime and the sessions start is ≤ latestSessionStartTime iterating from latest to earliest. I.e., earliestSessionEndTime is the lower bound of the search interval and latestSessionStartTime is the upper bound of the search interval, and the method returns all sessions that overlap with the search interval. Thus, if a session ends before earliestSessionEndTime, or starts after latestSessionStartTime if won't be contained in the result:

 earliestSessionEndTime: ESET
 latestSessionStartTime: LSST

                       [ESET............LSST]
 [not-included] [included]   [included]   [included] [not-included]
 

This iterator must be closed after use.

Specified by:

backwardFindSessions in interface ReadOnlySessionStore<K,AGG>

Parameters:

keyFrom - The first key that could be in the range A null value indicates a starting position from the first element in the store.

keyTo - The last key that could be in the range A null value indicates that the range ends with the last element in the store.

earliestSessionEndTime - the end timestamp of the earliest session to search for, where iteration ends.

latestSessionStartTime - the end timestamp of the latest session to search for, where iteration starts.

Returns:

backward iterator of sessions with the matching keys and aggregated values, from latest to earliest session time.

fetchSession

default AGG fetchSession(K key,
                         Instant sessionStartTime,
                         Instant sessionEndTime)

Description copied from interface: ReadOnlySessionStore

Get the value of key from a single session.

Specified by:

fetchSession in interface ReadOnlySessionStore<K,AGG>

Parameters:

key - the key to fetch

sessionStartTime - start timestamp of the session

sessionEndTime - end timestamp of the session

Returns:

The value or null if no session with the exact start and end timestamp exists for the given key

remove

void remove(Windowed<K> sessionKey)

Remove the session aggregated with provided Windowed key from the store

Parameters:

sessionKey - key of the session to remove

Throws:

NullPointerException - If null is used for sessionKey.

put

void put(Windowed<K> sessionKey,
         AGG aggregate)

Write the aggregated value for the provided key to the store

Parameters:

sessionKey - key of the session to write

aggregate - the aggregated value for the session, it can be null; if the serialized bytes are also null it is interpreted as deletes

Throws:

NullPointerException - If null is used for sessionKey.