Package org.springframework.ai.session

Interface SessionService

All Known Implementing Classes:

DefaultSessionService

public interface SessionService

The sessions of an application and their conversations: creating and finding sessions, appending and reading their events, compacting them. appendEvent(org.springframework.ai.session.SessionEvent) appends one event. appendEvents(String, List, long) appends a batch only if the log has not changed since the caller read its version. Compaction writes this way, and so can any other code that builds events from the log. DefaultSessionService implements it on a SessionRepository.

Since:

2.1.0

Author:

Christian Tzolov

Method Summary

Modifier and Type	Method	Description
void	appendEvent(SessionEvent event)	Appends an event to the session named by SessionEvent.getSessionId().
boolean	appendEvents(String sessionId, List<SessionEvent> events, long expectedVersion)	Appends one or more events in order, atomically, only if the log's version still equals expectedVersion.
default void	appendMessage(String sessionId, Message message)	Wraps the message in a SessionEvent and appends it; see appendEvent(SessionEvent).
CompactionResult	compact(String sessionId, CompactionTrigger trigger, CompactionStrategy strategy)	Evaluates the trigger on the active view and, when it fires, runs the strategy and records its result: one EventType.COMPACTION boundary event followed by the summary events, in one version-checked appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long).
Session	create(CreateSessionRequest request)	Creates a session with the request's id, a random UUID when it has none, its time to live and its metadata.
void	delete(String sessionId)	Deletes the session and its events.
int	deleteExpiredSessions(Instant before)	Deletes every session that expired before the given instant, with their events, and returns how many.
@Nullable Session	findById(String sessionId)
List<Session>	findByMetadata(String name, String value)	The sessions whose metadata holds value under name, oldest first, for the keys the store indexes; see SessionRepository.findByMetadata(java.lang.String, java.lang.String).
default Session	findOrCreate(CreateSessionRequest request)	The session with the request's id, created from the request when there is none.
default List<Message>	getActiveMessages(String sessionId)	The messages of the active view, the context window to send to the model: getEvents(sessionId, EventFilter.active()) as messages.
default List<SessionEvent>	getEvents(String sessionId)	Every event of the log, oldest first.
List<SessionEvent>	getEvents(String sessionId, EventFilter filter)	The events the filter selects, oldest first; see EventFilter.
long	getEventVersion(String sessionId)	The version of the session's log.
default List<Message>	getMessages(String sessionId)	The messages of the whole log, the events a compaction covered and the summaries included: the full history, not a prompt.

Method Details

create

Session create(CreateSessionRequest request)

Creates a session with the request's id, a random UUID when it has none, its time to live and its metadata.

Throws:

SessionAlreadyExistsException - if a session with the requested id exists

findOrCreate

default Session findOrCreate(CreateSessionRequest request)

The session with the request's id, created from the request when there is none. Safe under concurrent first use: when another caller creates it first, the stored session is returned, not this request's. The default finds, creates, and on a SessionAlreadyExistsException finds again, through this service's own findById(java.lang.String) and create(org.springframework.ai.session.CreateSessionRequest).

Throws:

IllegalArgumentException - if the request has no id, null or blank

findById

@Nullable Session findById(String sessionId)

findByMetadata

List<Session> findByMetadata(String name,
 String value)

The sessions whose metadata holds value under name, oldest first, for the keys the store indexes; see SessionRepository.findByMetadata(java.lang.String, java.lang.String). The sessions of a principal are findByMetadata(SessionAttributes.PRINCIPAL_NAME, name).

delete

void delete(String sessionId)

Deletes the session and its events.

deleteExpiredSessions

int deleteExpiredSessions(Instant before)

Deletes every session that expired before the given instant, with their events, and returns how many. Nothing calls this on its own: call it from a scheduler, every hour for example.

appendEvent

void appendEvent(SessionEvent event)

Appends an event to the session named by SessionEvent.getSessionId().

Throws:

IllegalArgumentException - if the event wraps a SystemMessage and the service does not allow storing system messages; see DefaultSessionService.Builder.allowSystemMessages(boolean)

appendMessage

default void appendMessage(String sessionId,
 Message message)

Wraps the message in a SessionEvent and appends it; see appendEvent(SessionEvent).

appendEvents

boolean appendEvents(String sessionId,
 List<SessionEvent> events,
 long expectedVersion)

Appends one or more events in order, atomically, only if the log's version still equals expectedVersion. Otherwise nothing is written and false is returned: another writer appended in between. On success the version advances once, whatever the number of events. This is the compare-and-set of the log, as SessionRepository.appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long) defines it.

Read getEventVersion(java.lang.String), then read what the new events depend on, then call this method. On false, read again and rebuild the events. Compaction writes its boundary and summaries this way.

Parameters:

sessionId - the session whose log is appended to; every event must belong to it

events - the events to append, oldest first; at least one, with ids that are new to the log

expectedVersion - the version read before the events were prepared

Returns:

true when the events were appended, false when the log moved on and nothing was written

Throws:

IllegalArgumentException - if the session does not exist, the batch is empty, an event belongs to another session, an id is already in the log or appears twice, or an event holds a system message that appendEvent(org.springframework.ai.session.SessionEvent) would reject. The system message check runs before the version check. The other checks may run only when the version matches, so a stale version can return false for a batch that would otherwise throw.

getEventVersion

long getEventVersion(String sessionId)

The version of the session's log. It advances on every append of a new event and once per successful appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long). An appendEvent(org.springframework.ai.session.SessionEvent) of an id the log already holds is a no-op and does not advance it. 0 for a session without events, or one that does not exist. Read it before the events that a version-checked appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long) depends on.

getEvents

List<SessionEvent> getEvents(String sessionId,
 EventFilter filter)

The events the filter selects, oldest first; see EventFilter.

getEvents

default List<SessionEvent> getEvents(String sessionId)

Every event of the log, oldest first.

getMessages

default List<Message> getMessages(String sessionId)

The messages of the whole log, the events a compaction covered and the summaries included: the full history, not a prompt. Use getActiveMessages(String) for the prompt.

getActiveMessages

default List<Message> getActiveMessages(String sessionId)

The messages of the active view, the context window to send to the model: getEvents(sessionId, EventFilter.active()) as messages.

compact

CompactionResult compact(String sessionId,
 CompactionTrigger trigger,
 CompactionStrategy strategy)

Evaluates the trigger on the active view and, when it fires, runs the strategy and records its result: one EventType.COMPACTION boundary event followed by the summary events, in one version-checked appendEvents(java.lang.String, java.util.List<org.springframework.ai.session.SessionEvent>, long). The log is never changed; the boundary defines the view from then on. An append that lands in between does not waste the summary: the new events join the view verbatim and the write is retried, a bounded number of times. Pass request -> true to compact unconditionally.

Returns:

the result as written, the events appended meanwhile added to its preserved tail; CompactionResult.isUnchanged() when nothing was written: the trigger did not fire, the strategy covered nothing, another compaction landed first, or appends kept overtaking the write