shared-infrastructure/com.vertyll.veds.sharedinfrastructure.saga.entity/BaseSaga

BaseSaga

@MappedSuperclass

abstract class BaseSaga<S : BaseSaga<S>>(var id: String, var type: String, status: SagaStatus, var payload: String, lastError: String? = null, var startedAt: Instant, completedAt: Instant? = null, updatedAt: Instant = Instant.now(), var version: Long? = null) : Saga<S> (source)

JPA-backed base implementation of the Saga port.

The Saga port exposes its fields as val (immutable from the engine's point of view). Internally this class uses var because Jakarta Persistence requires writable fields for proxy/dirty-tracking. State transitions are exclusively performed via behavior methods (DDD rich aggregate) which mutate the same instance and return this — Hibernate then issues a partial UPDATE on flush.

Mongo/Cassandra adapters can implement these methods by returning a fresh copy of the document instead. The engine never observes this difference.

Constructors

BaseSaga

constructor(id: String, type: String, status: SagaStatus, payload: String, lastError: String? = null, startedAt: Instant, completedAt: Instant? = null, updatedAt: Instant = Instant.now(), version: Long? = null)

Properties

completedAt

open override var completedAt: Instant?

Instant the saga reached a terminal status; null while it is still in flight.

open override var id: String

Globally-unique saga id (typically a UUID). Used as the Kafka key for correlated events.

lastError

open override var lastError: String?

Latest failure reason (step failure, timeout, …); null while the saga is healthy.

payload

open override var payload: String

Original request payload as a JSON string. Treated as opaque by the engine.

startedAt

open override var startedAt: Instant

Instant the saga was started.

status

open override var status: SagaStatus

Current lifecycle SagaStatus; see the enum for the full state machine.

type

open override var type: String

Saga type discriminator (e.g. "UserRegistration"). Conventionally a SagaTypeValue.

updatedAt

open override var updatedAt: Instant

Instant of the most recent state change; used by SagaWatchdog to detect AWAITING_RESPONSE timeouts and to throttle compensation retries.

version

open override var version: Long?

JPA optimistic-locking version, or null for storage backends that do not provide one.

Functions

markAwaitingResponse

open override fun markAwaitingResponse(): S

Transitions to SagaStatus.AWAITING_RESPONSE and stamps updatedAt.

markCompensated

open override fun markCompensated(): S

Transitions to SagaStatus.COMPENSATED and stamps completedAt/updatedAt.

markCompensationFailed

open override fun markCompensationFailed(): S

Transitions to SagaStatus.COMPENSATION_FAILED and stamps completedAt/updatedAt.

markCompleted

open override fun markCompleted(): S

Transitions to SagaStatus.COMPLETED and stamps completedAt/updatedAt.

markFailed

open override fun markFailed(error: String): S

Transitions to SagaStatus.FAILED, stores error as lastError, and stamps completedAt/updatedAt.

startCompensating

open override fun startCompensating(error: String): S

Transitions to SagaStatus.COMPENSATING, stores error as lastError, and stamps updatedAt. Used when a step failure triggers compensation but the saga has not yet completed compensation.