Interface BaseSessionService

All Known Implementing Classes:
InMemorySessionService, VertexAiSessionService
public interface BaseSessionService
Defines the contract for managing Sessions and their associated Events. Provides methods for creating, retrieving, listing, and deleting sessions, as well as listing and appending events to a session. Implementations of this interface handle the underlying storage and retrieval logic.

  • Method Details

    • createSession

      io.reactivex.rxjava3.core.Single<Session> createSession(String appName, String userId, @Nullable ConcurrentMap<String,Object> state, @Nullable String sessionId)
      Creates a new session with the specified parameters.
      Parameters:
      appName - The name of the application associated with the session.
      userId - The identifier for the user associated with the session.
      state - An optional map representing the initial state of the session. Can be null or empty.
      sessionId - An optional client-provided identifier for the session. If empty or null, the service should generate a unique ID.
      Returns:
      The newly created Session instance.
      Throws:
      SessionException - if creation fails.

    • createSession

      default io.reactivex.rxjava3.core.Single<Session> createSession(String appName, String userId)
      Creates a new session with the specified application name and user ID, using a default state (null) and allowing the service to generate a unique session ID.

      This is a shortcut for createSession(String, String, Map, String) with null state and a null session ID.

      Parameters:
      appName - The name of the application associated with the session.
      userId - The identifier for the user associated with the session.
      Returns:
      The newly created Session instance.
      Throws:
      SessionException - if creation fails.

    • getSession

      io.reactivex.rxjava3.core.Maybe<Session> getSession(String appName, String userId, String sessionId, Optional<GetSessionConfig> config)
      Retrieves a specific session, optionally filtering the events included.
      Parameters:
      appName - The name of the application.
      userId - The identifier of the user.
      sessionId - The unique identifier of the session to retrieve.
      config - Optional configuration to filter the events returned within the session (e.g., limit number of recent events, filter by timestamp). If empty, default retrieval behavior is used (potentially all events or a service-defined limit).
      Returns:
      An Optional containing the Session if found, otherwise Optional.empty().
      Throws:
      SessionException - for retrieval errors other than not found.

    • listSessions

      io.reactivex.rxjava3.core.Single<ListSessionsResponse> listSessions(String appName, String userId)
      Lists sessions associated with a specific application and user.

      The Session objects in the response typically contain only metadata (like ID, creation time) and not the full event list or state to optimize performance.

      Parameters:
      appName - The name of the application.
      userId - The identifier of the user whose sessions are to be listed.
      Returns:
      A ListSessionsResponse containing a list of matching sessions.
      Throws:
      SessionException - if listing fails.

    • deleteSession

      io.reactivex.rxjava3.core.Completable deleteSession(String appName, String userId, String sessionId)
      Deletes a specific session.
      Parameters:
      appName - The name of the application.
      userId - The identifier of the user.
      sessionId - The unique identifier of the session to delete.
      Throws:
      SessionNotFoundException - if the session doesn't exist.
      SessionException - for other deletion errors.

    • listEvents

      io.reactivex.rxjava3.core.Single<ListEventsResponse> listEvents(String appName, String userId, String sessionId)
      Lists the events within a specific session. Supports pagination via the response object.
      Parameters:
      appName - The name of the application.
      userId - The identifier of the user.
      sessionId - The unique identifier of the session whose events are to be listed.
      Returns:
      A ListEventsResponse containing a list of events and an optional token for retrieving the next page.
      Throws:
      SessionNotFoundException - if the session doesn't exist.
      SessionException - for other listing errors.

    • closeSession

      default io.reactivex.rxjava3.core.Completable closeSession(Session session)
      Closes a session. This is currently a placeholder and may involve finalizing session state or performing cleanup actions in future implementations. The default implementation does nothing.
      Parameters:
      session - The session object to close.

    • appendEvent

      @CanIgnoreReturnValue default io.reactivex.rxjava3.core.Single<Event> appendEvent(Session session, Event event)
      Appends an event to an in-memory session object and updates the session's state based on the event's state delta, if applicable.

      This method primarily modifies the passed session object in memory. Persisting these changes typically requires a separate call to an update/save method provided by the specific service implementation, or might happen implicitly depending on the implementation's design.

      If the event is marked as partial (e.g., event.isPartial() == true), it is returned directly without modifying the session state or event list. State delta keys starting with State.TEMP_PREFIX are ignored during state updates.

      Parameters:
      session - The Session object to which the event should be appended (will be mutated).
      event - The Event to append.
      Returns:
      The appended Event instance (or the original event if it was partial).
      Throws:
      NullPointerException - if session or event is null.