# Interface BaseSessionService

All Known Implementing Classes:
  `FirestoreSessionService, InMemorySessionService, VertexAiSessionService`

public interface BaseSessionService
Defines the contract for managing `Session`s and their associated `Event`s. 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 Summary

  Modifier and Type
  Method
  Description
  `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.
  `default io.reactivex.rxjava3.core.Completable`
  `closeSession(Session session)`
  Closes a session.
  `default io.reactivex.rxjava3.core.Single<Session>`
  `createSession(SessionKey sessionKey)`
  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.
  `default io.reactivex.rxjava3.core.Single<Session>`
  `createSession(SessionKey sessionKey, @Nullable Map<String,Object> state)`
  Creates a new session with the specified parameters.
  `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.
  `default io.reactivex.rxjava3.core.Single<Session>`
  `createSession(String appName, String userId, @Nullable Map<String,Object> state, @Nullable String sessionId)`
  Creates a new session with the specified parameters.
  `io.reactivex.rxjava3.core.Single<Session>`
  `createSession(String appName, String userId, @Nullable ConcurrentMap<String,Object> state, @Nullable String sessionId)`
  Deprecated.
  Use `createSession(String, String, Map, String)` instead.
  `default io.reactivex.rxjava3.core.Completable`
  `deleteSession(SessionKey sessionKey)`
  Deletes a specific session.
  `io.reactivex.rxjava3.core.Completable`
  `deleteSession(String appName, String userId, String sessionId)`
  Deletes a specific session.
  `default io.reactivex.rxjava3.core.Maybe<Session>`
  `getSession(SessionKey sessionKey, @Nullable GetSessionConfig config)`
  Retrieves a specific session, optionally filtering the events included.
  `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.
  `default io.reactivex.rxjava3.core.Single<ListEventsResponse>`
  `listEvents(SessionKey sessionKey)`
  Lists the events within a specific session.
  `io.reactivex.rxjava3.core.Single<ListEventsResponse>`
  `listEvents(String appName, String userId, String sessionId)`
  Lists the events within a specific session.
  `default io.reactivex.rxjava3.core.Single<ListSessionsResponse>`
  `listSessions(SessionKey sessionKey)`
  Lists sessions associated with a specific application and user.
  `io.reactivex.rxjava3.core.Single<ListSessionsResponse>`
  `listSessions(String appName, String userId)`
  Lists sessions associated with a specific application and user.

- ## Method Details

  - ### createSession

    @Deprecated io.reactivex.rxjava3.core.Single<Session> createSession(String appName, String userId, @Nullable ConcurrentMap<String,Object> state, @Nullable String sessionId)
    Deprecated.
    Use `createSession(String, String, Map, String)` instead.
    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, @Nullable Map<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(SessionKey sessionKey, @Nullable Map<String,Object> state)
    Creates a new session with the specified parameters.
    Parameters:
      `sessionKey` - The session key containing appName, userId and sessionId.
      `state` - An optional map representing the initial state of the session. Can be null or empty.

  - ### 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.

  - ### createSession

    default io.reactivex.rxjava3.core.Single<Session> createSession(SessionKey sessionKey)
    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.

  - ### 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.

  - ### getSession

    default io.reactivex.rxjava3.core.Maybe<Session> getSession(SessionKey sessionKey, @Nullable GetSessionConfig config)
    Retrieves a specific session, optionally filtering the events included.

  - ### 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.

  - ### listSessions

    default io.reactivex.rxjava3.core.Single<ListSessionsResponse> listSessions(SessionKey sessionKey)
    Lists sessions associated with a specific application and user.

  - ### 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.

  - ### deleteSession

    default io.reactivex.rxjava3.core.Completable deleteSession(SessionKey sessionKey)
    Deletes a specific session.

  - ### 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.

  - ### listEvents

    default io.reactivex.rxjava3.core.Single<ListEventsResponse> listEvents(SessionKey sessionKey)
    Lists the events within a specific session.

  - ### 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.