Package de.delinkedde.areashopreborn.persistence

Klasse PurchaseRepository

java.lang.Object
de.delinkedde.areashopreborn.persistence.PurchaseRepository
public final class PurchaseRepository extends Object
Persists purchase journals and atomic ownership transitions. All methods are synchronous and must run through the database executor.

  • Konstruktordetails

    • PurchaseRepository

      public PurchaseRepository(Database database)
      Creates a purchase repository.
      Parameter:
      database - SQLite database owner

  • Methodendetails

    • insert

      public void insert(PurchaseTransaction transaction) throws SQLException
      Inserts a new purchase journal entry.
      Parameter:
      transaction - transaction snapshot
      Löst aus:
      SQLException - when persistence fails

    • findByIdempotencyKey

      public Optional<PurchaseTransaction> findByIdempotencyKey(String idempotencyKey) throws SQLException
      Finds a purchase by its caller-controlled idempotency key.
      Parameter:
      idempotencyKey - unique request key
      Gibt zurück:
      matching durable transaction when present
      Löst aus:
      SQLException - when the query fails

    • findById

      public Optional<PurchaseTransaction> findById(UUID transactionId) throws SQLException
      Finds a purchase journal by its stable identifier.
      Parameter:
      transactionId - transaction identifier
      Gibt zurück:
      matching transaction when present
      Löst aus:
      SQLException - when the query fails

    • findNonTerminal

      public List<PurchaseTransaction> findNonTerminal() throws SQLException
      Lists purchase journals whose cross-system workflow did not reach a terminal state.
      Gibt zurück:
      oldest nonterminal transactions first
      Löst aus:
      SQLException - when the query fails

    • findNonTerminal

      public List<PurchaseTransaction> findNonTerminal(int limit) throws SQLException
      Lists a bounded oldest-first batch of nonterminal purchase journals.
      Parameter:
      limit - maximum journals returned
      Gibt zurück:
      oldest nonterminal transactions first
      Löst aus:
      SQLException - when the query fails

    • quarantine

      public void quarantine(UUID transactionId, UUID regionId, String failureCode, String failureDetail) throws SQLException
      Atomically quarantines a purchase journal and its region for administrator inspection.
      Parameter:
      transactionId - transaction identifier
      regionId - affected region identifier
      failureCode - stable recovery reason
      failureDetail - diagnostic detail
      Löst aus:
      SQLException - when the quarantine cannot be persisted

    • reserve

      public boolean reserve(PurchaseTransaction transaction, RegionState previousRegionState, Instant reservedUntil, int maximumOwnedParcels) throws SQLException
      Atomically reserves a listing and region and inserts the purchase journal.
      Parameter:
      transaction - transaction to journal
      previousRegionState - expected region state before reservation
      reservedUntil - reservation expiry
      maximumOwnedParcels - effective buyer limit, or -1 for unlimited
      Gibt zurück:
      true when the reservation was acquired
      Löst aus:
      SQLException - when persistence fails

    • releaseReservation

      public void releaseReservation(UUID transactionId, UUID listingId, UUID regionId, RegionState restoredRegionState, TransactionState transactionState, String failureCode, String failureDetail) throws SQLException
      Releases a reservation and records a failed or compensated transaction.
      Parameter:
      transactionId - transaction identifier
      listingId - listing identifier
      regionId - region identifier
      restoredRegionState - region state before reservation
      transactionState - terminal transaction state
      failureCode - stable failure code
      failureDetail - diagnostic detail
      Löst aus:
      SQLException - when persistence fails

    • updateState

      public void updateState(UUID transactionId, TransactionState state, String failureCode, String failureDetail) throws SQLException
      Updates durable transaction progress and optional failure details.
      Parameter:
      transactionId - transaction identifier
      state - new progress state
      failureCode - stable failure code, or null
      failureDetail - diagnostic detail, or null
      Löst aus:
      SQLException - when persistence fails

    • resolvePayoutConfirmed

      public void resolvePayoutConfirmed(PurchaseTransaction transaction, UUID administratorId, String evidence, Instant resolvedAt) throws SQLException
      Atomically records an administrator-attested payout and closes a quarantined purchase.

      The compare-and-set requires the transaction to remain in manual review and SQLite to name the buyer as current region owner. The evidence is retained in the transaction detail and the immutable audit log.

      Parameter:
      transaction - expected quarantined transaction
      administratorId - resolving administrator
      evidence - external verification reference
      resolvedAt - resolution timestamp
      Löst aus:
      SQLException - when state changed concurrently or persistence fails

    • persistOwnership

      public void persistOwnership(UUID transactionId, UUID regionId, UUID listingId, UUID buyerId) throws SQLException
      Atomically changes ownership, closes the listing, and advances the journal.
      Parameter:
      transactionId - transaction identifier
      regionId - region identifier
      listingId - listing identifier
      buyerId - new owner identifier
      Löst aus:
      SQLException - when the atomic transition fails