Package 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 Details

    • 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 it 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 it 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 it 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 it 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.