Package de.delinkedde.areashopreborn.persistence

Klasse EstateRepository

java.lang.Object
de.delinkedde.areashopreborn.persistence.EstateRepository
public final class EstateRepository extends Object
Stores and retrieves the persistent business state of regions and listings. All methods are synchronous and must be invoked through the database executor.

  • Konstruktordetails

    • EstateRepository

      public EstateRepository(Database database)
      Creates a repository backed by the supplied database.
      Parameter:
      database - SQLite database owner

  • Methodendetails

    • insertRegion

      public void insertRegion(EstateRegion region) throws SQLException
      Inserts a new city or parcel.
      Parameter:
      region - region snapshot to insert
      Löst aus:
      SQLException - when persistence fails or a constraint is violated

    • insertRegionAudited

      public void insertRegionAudited(EstateRegion region, UUID actorId, String action, String detail) throws SQLException
      Atomically inserts a region and its creation audit entry.
      Parameter:
      region - region snapshot to insert
      actorId - actor creating or importing the region
      action - stable audit action
      detail - bounded creation context
      Löst aus:
      SQLException - when either insert fails

    • findRegionById

      public Optional<EstateRegion> findRegionById(UUID id) throws SQLException
      Finds a region by its internal identifier.
      Parameter:
      id - internal region identifier
      Gibt zurück:
      matching region, or an empty optional
      Löst aus:
      SQLException - when the query fails

    • findRegion

      public Optional<EstateRegion> findRegion(String worldKey, String nameOrProtectionId) throws SQLException
      Finds a region by display name or protection identifier within one world.
      Parameter:
      worldKey - owning world key
      nameOrProtectionId - display name or WorldGuard identifier
      Gibt zurück:
      matching region, or an empty optional
      Löst aus:
      SQLException - when the query fails

    • findRegionGlobally

      public Optional<EstateRegion> findRegionGlobally(String nameOrProtectionId) throws SQLException
      Finds the first globally matching region by display name or protection identifier.
      Parameter:
      nameOrProtectionId - display name or WorldGuard identifier
      Gibt zurück:
      matching region, or an empty optional
      Löst aus:
      SQLException - when the query fails

    • findAt

      public Optional<EstateRegion> findAt(String worldKey, int x, int y, int z) throws SQLException
      Finds the most specific managed region containing an exact block position.

      Parcels are preferred over cities, followed by the smallest volume and a stable protection identifier.

      Parameter:
      worldKey - Bukkit world key
      x - block X coordinate
      y - block Y coordinate
      z - block Z coordinate
      Gibt zurück:
      most specific containing region when managed
      Löst aus:
      SQLException - when the query fails

    • findGeometry

      public RegionGeometry findGeometry(EstateRegion region) throws SQLException
      Loads the exact polygon and height range of a managed region.

      Legacy databases are populated by migration V013. The rectangular fallback keeps repository fixtures and manually repaired databases readable when no geometry rows exist.

      Parameter:
      region - region snapshot whose geometry is requested
      Gibt zurück:
      exact persisted geometry or an equivalent rectangular fallback
      Löst aus:
      SQLException - when the vertex query fails

    • replaceGeometry

      public void replaceGeometry(EstateRegion region, RegionGeometry geometry, UUID actorId, String action, String detail) throws SQLException
      Atomically replaces polygon vertices, indexed bounds, and the audit trail.
      Parameter:
      region - current region snapshot
      geometry - replacement geometry
      actorId - actor performing the change
      action - stable audit action
      detail - bounded audit detail
      Löst aus:
      SQLException - when optimistic locking or persistence fails

    • mergeParcels

      public void mergeParcels(EstateRegion target, EstateRegion source, RegionGeometry geometry, EstateRepository.ValueBasis combinedBasis, UUID actorId) throws SQLException
      Atomically persists a parcel merge and archives the source parcel.

      Target settings remain authoritative. Source access grants, displays, teleport points, group links, home grants, offer defaults, and obsolete infrastructure metadata are removed so archived records cannot continue affecting gameplay.

      Parameter:
      target - retained parcel
      source - archived source parcel
      geometry - combined target geometry
      combinedBasis - optional combined financial basis for a sold target
      actorId - actor performing the merge
      Löst aus:
      SQLException - when optimistic locking or persistence fails

    • findValueBasis

      public Optional<EstateRepository.ValueBasis> findValueBasis(UUID regionId) throws SQLException
      Loads the explicit financial value basis used by sellback and sold-parcel merges.
      Parameter:
      regionId - parcel identifier
      Gibt zurück:
      current basis when the parcel has completed purchase history
      Löst aus:
      SQLException - when the query fails

    • findChildren

      public List<EstateRegion> findChildren(UUID parentId) throws SQLException
      Lists active direct children of a parent region.

      Regions archived by a parcel merge are excluded. Their WorldGuard region no longer exists, so treating them as live children would block city deletion, height changes, and access synchronization.

      Parameter:
      parentId - parent region identifier
      Gibt zurück:
      children ordered by display name
      Löst aus:
      SQLException - when the query fails

    • findManyChildren

      public List<EstateRegion> findManyChildren(UUID parentId, int limit) throws SQLException
      Returns a bounded prefix of a region's active direct children.
      Parameter:
      parentId - parent region identifier
      limit - maximum number of rows to return
      Gibt zurück:
      children ordered by display name
      Löst aus:
      SQLException - when the query fails

    • countChildren

      public int countChildren(UUID parentId) throws SQLException
      Counts active direct children without materializing their domain snapshots.
      Parameter:
      parentId - parent region identifier
      Gibt zurück:
      direct child count excluding merged archives
      Löst aus:
      SQLException - when the query fails

    • findChildrenIntersectingFootprint

      public List<EstateRegion> findChildrenIntersectingFootprint(UUID parentId, CuboidBounds proposed, int expansion, int limit) throws SQLException
      Finds only direct children whose X/Z footprint can intersect an expanded proposal.

      Vertical overlap remains a domain-policy decision. Filtering X/Z in SQLite avoids materializing every parcel of a large city for one local geometry check.

      Parameter:
      parentId - parent city identifier
      proposed - proposed parcel bounds
      expansion - horizontal expansion applied on all sides
      limit - maximum candidate rows
      Gibt zurück:
      stable geometry candidate snapshots
      Löst aus:
      SQLException - when the query fails

    • findCitiesIntersectingFootprint

      public List<EstateRegion> findCitiesIntersectingFootprint(String worldKey, CuboidBounds proposed, int limit) throws SQLException
      Finds city bounding boxes that can intersect a proposed horizontal footprint.
      Parameter:
      worldKey - Bukkit world key
      proposed - proposed bounding cuboid
      limit - maximum candidate count
      Gibt zurück:
      stable city candidates for exact polygon checks
      Löst aus:
      SQLException - when the query fails

    • findOwnedBy

      public List<EstateRegion> findOwnedBy(UUID ownerId) throws SQLException
      Lists regions owned or managed as landlord by a player.
      Parameter:
      ownerId - player identifier
      Gibt zurück:
      matching regions
      Löst aus:
      SQLException - when the query fails

    • findOwnedBy

      public List<EstateRegion> findOwnedBy(UUID ownerId, int limit) throws SQLException
      Returns a bounded prefix of regions owned or managed by a player.
      Parameter:
      ownerId - player identifier
      limit - maximum number of rows to return
      Gibt zurück:
      matching regions ordered by display name
      Löst aus:
      SQLException - when the query fails

    • findLandlordRestrictedParcels

      public List<EstateRegion> findLandlordRestrictedParcels(int limit) throws SQLException
      Loads parcels where inherited city membership must not grant the landlord gameplay access. Sold player property and actively rented property are both isolated from the city landlord.
      Parameter:
      limit - maximum parcel count
      Gibt zurück:
      immutable restricted parcel snapshots
      Löst aus:
      SQLException - when the query fails

    • countOwnedParcels

      public int countOwnedParcels(UUID ownerId) throws SQLException
      Counts parcels currently owned by a player for acquisition-limit enforcement.
      Parameter:
      ownerId - player identifier
      Gibt zurück:
      owned parcel count
      Löst aus:
      SQLException - when the query fails

    • countManagedCities

      public int countManagedCities(UUID playerId) throws SQLException
      Counts cities directly controlled by a landlord or owner.
      Parameter:
      playerId - player identifier
      Gibt zurück:
      managed city count
      Löst aus:
      SQLException - when the query fails

    • findAvailable

      public List<EstateRegion> findAvailable(String cityName) throws SQLException
      Lists regions with active sale listings, optionally restricted to a parent city.
      Parameter:
      cityName - optional city display name or protection identifier
      Gibt zurück:
      saleable regions ordered by display name
      Löst aus:
      SQLException - when the query fails

    • findAvailable

      public List<EstateRegion> findAvailable(String cityName, int limit) throws SQLException
      Returns a bounded prefix of active sale listings.
      Parameter:
      cityName - optional city display name or protection identifier
      limit - maximum number of rows to return
      Gibt zurück:
      saleable regions ordered by display name
      Löst aus:
      SQLException - when the query fails

    • findAvailable

      public List<EstateRegion> findAvailable(String cityName, int limit, int offset) throws SQLException
      Returns one bounded market page without materializing preceding rows.
      Parameter:
      cityName - optional city display name or protection identifier
      limit - maximum number of rows to return
      offset - number of matching rows to skip
      Gibt zurück:
      saleable regions ordered by display name
      Löst aus:
      SQLException - when the query fails

    • findAvailableMarket

      public List<EstateRepository.MarketListing> findAvailableMarket(String cityName, int limit, int offset) throws SQLException
      Returns one sale-market page with the user-facing city name and price in the same query.
      Parameter:
      cityName - optional city display name or protection identifier
      limit - maximum number of rows
      offset - number of matching rows to skip
      Gibt zurück:
      sale cards ordered by parcel display name
      Löst aus:
      SQLException - when the query fails

    • countAvailable

      public int countAvailable(String cityName) throws SQLException
      Counts active sale listings, optionally restricted to one city.
      Parameter:
      cityName - optional city display name or protection identifier
      Gibt zurück:
      matching listing count
      Löst aus:
      SQLException - when the query fails

    • findAll

      public List<EstateRegion> findAll() throws SQLException
      Lists every active managed region with cities before parcels for hierarchy-sensitive operations.

      Merged archives are excluded because their WorldGuard region was removed during the merge. Including them would abort startup priority enforcement with a missing-region failure.

      Gibt zurück:
      all live regions in stable hierarchy order
      Löst aus:
      SQLException - when the query fails

    • findPage

      public List<EstateRegion> findPage(EstateRegion after, int limit) throws SQLException
      Loads a hierarchy-ordered keyset page of active regions for long-running maintenance jobs.

      Merged archives are excluded so reconciliation never reports or recreates a WorldGuard region that the merge deliberately removed.

      Parameter:
      after - previous page's last region, or null for the first page
      limit - maximum rows returned
      Gibt zurück:
      immutable page with cities before parcels
      Löst aus:
      SQLException - when the query fails

    • findProtectionIds

      public List<String> findProtectionIds(RegionType type, int limit) throws SQLException
      Loads only the lightweight protection identifiers needed by command completion.
      Parameter:
      type - optional region type restriction
      limit - maximum number of identifiers to return
      Gibt zurück:
      immutable, case-insensitively ordered identifiers
      Löst aus:
      SQLException - when the query fails

    • findSuggestedRegionNames

      public List<String> findSuggestedRegionNames(RegionType type, int limit) throws SQLException
      Loads user-facing display names and stable protection identifiers for command completion. Duplicate values are removed case-insensitively while stable identifiers remain available as an unambiguous fallback.
      Parameter:
      type - optional region type restriction
      limit - maximum number of returned suggestions
      Gibt zurück:
      immutable, case-insensitively ordered lookup values
      Löst aus:
      SQLException - when the query fails

    • findActiveRenter

      public Optional<UUID> findActiveRenter(UUID regionId) throws SQLException
      Finds the renter whose active contract currently grants WorldGuard member access.
      Parameter:
      regionId - rented region identifier
      Gibt zurück:
      active renter when present
      Löst aus:
      SQLException - when the query fails

    • findCitiesManagedBy

      public List<EstateRegion> findCitiesManagedBy(UUID playerId) throws SQLException
      Lists cities directly or indirectly managed by a player.
      Parameter:
      playerId - player identifier
      Gibt zurück:
      managed cities
      Löst aus:
      SQLException - when the query fails

    • isManager

      public boolean isManager(UUID regionId, UUID playerId) throws SQLException
      Checks whether a player has a delegated manager role.
      Parameter:
      regionId - city identifier
      playerId - player identifier
      Gibt zurück:
      true when the manager assignment exists
      Löst aus:
      SQLException - when the query fails

    • isBuilder

      public boolean isBuilder(UUID cityId, UUID playerId) throws SQLException
      Checks whether a player has the build-only role in a city.
      Parameter:
      cityId - city identifier
      playerId - player identifier
      Gibt zurück:
      true when the builder assignment exists
      Löst aus:
      SQLException - when the query fails

    • findBuilders

      public List<UUID> findBuilders(UUID cityId, int limit) throws SQLException
      Lists build-only players assigned to a city.
      Parameter:
      cityId - city identifier
      limit - maximum identities returned
      Gibt zurück:
      immutable builder UUIDs
      Löst aus:
      SQLException - when the query fails

    • addBuilder

      public void addBuilder(UUID cityId, UUID playerId, UUID actorId) throws SQLException
      Adds a build-only city role.
      Parameter:
      cityId - city identifier
      playerId - builder identifier
      actorId - assigning actor
      Löst aus:
      SQLException - when the role already exists or persistence fails

    • removeBuilder

      public void removeBuilder(UUID cityId, UUID playerId) throws SQLException
      Removes a build-only city role.
      Parameter:
      cityId - city identifier
      playerId - builder identifier
      Löst aus:
      SQLException - when the role is missing or persistence fails

    • updateRegionStateAndOwner

      public void updateRegionStateAndOwner(UUID id, RegionState state, UUID ownerId) throws SQLException
      Atomically updates a region's lifecycle state and owner.
      Parameter:
      id - region identifier
      state - new lifecycle state
      ownerId - new owner, or null
      Löst aus:
      SQLException - when the update fails

    • transferOwnership

      public void transferOwnership(UUID regionId, UUID expectedOwner, UUID newOwner) throws SQLException
      Atomically transfers a sold parcel and removes all previous member grants.
      Parameter:
      regionId - region identifier
      expectedOwner - current owner used for compare-and-set protection
      newOwner - new owner
      Löst aus:
      SQLException - when ownership changed concurrently or persistence fails

    • setOwner

      public void setOwner(UUID regionId, UUID ownerId) throws SQLException
      Administratively replaces a region owner without changing its lifecycle state.
      Parameter:
      regionId - region identifier
      ownerId - replacement owner
      Löst aus:
      SQLException - when the region is missing or persistence fails

    • setCityLandlord

      public void setCityLandlord(UUID cityId, UUID landlordId) throws SQLException
      Atomically changes a city's landlord and propagates the commercial recipient to its parcels.
      Parameter:
      cityId - city identifier
      landlordId - replacement landlord
      Löst aus:
      SQLException - when the city is missing or persistence fails

    • rename

      public void rename(UUID regionId, String displayName) throws SQLException
      Changes only the user-facing display name of a managed region.
      Parameter:
      regionId - region identifier
      displayName - replacement display name
      Löst aus:
      SQLException - when the region is missing or persistence fails

    • updateRegionState

      public void updateRegionState(UUID id, RegionState state) throws SQLException
      Updates a region's lifecycle state.
      Parameter:
      id - region identifier
      state - new lifecycle state
      Löst aus:
      SQLException - when the update fails

    • deleteRegion

      public void deleteRegion(UUID id) throws SQLException
      Deletes an unreferenced region.
      Parameter:
      id - region identifier
      Löst aus:
      SQLException - when deletion fails or references still exist

    • insertListing

      public void insertListing(Listing listing) throws SQLException
      Inserts a new market listing.
      Parameter:
      listing - listing snapshot
      Löst aus:
      SQLException - when persistence fails or an active listing already exists

    • publishResale

      public void publishResale(EstateRegion previousRegion, Listing listing, UUID actorId) throws SQLException
      Atomically publishes a resale listing, advances its parcel, and writes the audit entry.
      Parameter:
      previousRegion - sold parcel snapshot used for optimistic authorization
      listing - proposed active resale listing
      actorId - owner publishing the listing
      Löst aus:
      SQLException - when the parcel changed concurrently or persistence fails

    • cancelListing

      public void cancelListing(EstateRegion previousRegion, Listing previousListing, RegionState restoredState, UUID actorId) throws SQLException
      Atomically cancels an active listing, restores its region, and writes an audit entry.
      Parameter:
      previousRegion - region snapshot before cancellation
      previousListing - active listing snapshot
      restoredState - resulting region state
      actorId - authorized seller or administrator
      Löst aus:
      SQLException - when either snapshot changed concurrently or persistence fails

    • findActiveListing

      public Optional<Listing> findActiveListing(UUID regionId) throws SQLException
      Finds the active or reserved listing for a region.
      Parameter:
      regionId - region identifier
      Gibt zurück:
      active listing, or an empty optional
      Löst aus:
      SQLException - when the query fails

    • reserveListing

      public boolean reserveListing(UUID listingId, Instant reservedUntil) throws SQLException
      Exclusively reserves an active listing using a compare-and-set update.
      Parameter:
      listingId - listing identifier
      reservedUntil - reservation expiry
      Gibt zurück:
      true when this caller acquired the reservation
      Löst aus:
      SQLException - when the update fails

    • updateListingState

      public void updateListingState(UUID listingId, ListingState state) throws SQLException
      Updates a listing state and closes terminal listings.
      Parameter:
      listingId - listing identifier
      state - new listing state
      Löst aus:
      SQLException - when the update fails

    • addMember

      public void addMember(UUID regionId, UUID playerId, String role, UUID actorId) throws SQLException
      Adds a member or delegated manager to a region.
      Parameter:
      regionId - region identifier
      playerId - assigned player
      role - persistent role name
      actorId - player performing the assignment
      Löst aus:
      SQLException - when persistence fails

    • removeMember

      public void removeMember(UUID regionId, UUID playerId, String role) throws SQLException
      Removes a member or delegated manager from a region.
      Parameter:
      regionId - region identifier
      playerId - assigned player
      role - persistent role name
      Löst aus:
      SQLException - when deletion fails

    • findMembers

      public List<UUID> findMembers(UUID regionId, String role) throws SQLException
      Lists players assigned to a role for a region.
      Parameter:
      regionId - region identifier
      role - persistent role name
      Gibt zurück:
      assigned player identifiers
      Löst aus:
      SQLException - when the query fails

    • findMembers

      public List<UUID> findMembers(UUID regionId, String role, int limit) throws SQLException
      Lists a bounded prefix of players assigned to a role.
      Parameter:
      regionId - region identifier
      role - persistent role name
      limit - maximum identities returned
      Gibt zurück:
      assigned player identifiers in stable order
      Löst aus:
      SQLException - when the query fails

    • setTeleportPoint

      public void setTeleportPoint(UUID regionId, TeleportPoint point) throws SQLException
      Stores or replaces a region teleport destination.
      Parameter:
      regionId - region identifier
      point - teleport destination
      Löst aus:
      SQLException - when persistence fails

    • findTeleportPoint

      public Optional<TeleportPoint> findTeleportPoint(UUID regionId) throws SQLException
      Finds a region teleport destination.
      Parameter:
      regionId - region identifier
      Gibt zurück:
      saved teleport destination, or an empty optional
      Löst aus:
      SQLException - when the query fails

    • isMember

      public boolean isMember(UUID regionId, UUID playerId) throws SQLException
      Checks whether a player is a regular member of a region.
      Parameter:
      regionId - region identifier
      playerId - player identifier
      Gibt zurück:
      true when membership exists
      Löst aus:
      SQLException - when the query fails

    • audit

      public void audit(UUID actorId, String action, String targetType, UUID targetId, String oldState, String newState, String detail) throws SQLException
      Appends an immutable audit entry.
      Parameter:
      actorId - actor identifier, or null for the system
      action - action name
      targetType - audited object type
      targetId - audited object identifier
      oldState - previous state
      newState - resulting state
      detail - optional contextual detail
      Löst aus:
      SQLException - when persistence fails

    • auditBatch

      public void auditBatch(List<EstateRepository.AuditRecord> records) throws SQLException
      Appends a bounded audit batch using one connection and one transaction.
      Parameter:
      records - immutable audit rows
      Löst aus:
      SQLException - when any row fails; no row is then committed