Package dev.mintychochip.mint

Interface Service

@AvailableSince("1.1") public interface Service
Primary service interface for managing economy accounts and transactions.

All account operations are asynchronous and return CompletableFuture. Transactions are synchronously created but execute asynchronously on commit.

Since:
1.0

  • Method Details

    • getName

      String getName()
      Returns the name of this service implementation.
      Returns:
      the service name

    • getMaxFractionalDigits

      int getMaxFractionalDigits()
      Returns the maximum number of fractional digits allowed for currency amounts.
      Returns:
      maximum decimal places for monetary values

    • beginTransaction

      default Transaction beginTransaction(UUID accountId)
      Begins a new transaction against the specified account with empty context.

      Equivalent to beginTransaction(accountId, TransactionContext.empty()).

      Parameters:
      accountId - the account to transact against
      Returns:
      a new active transaction

    • beginTransaction

      Transaction beginTransaction(UUID accountId, TransactionContext ctx)
      Begins a new transaction against the specified account with provided context.

      The transaction is created in Transaction.State.ACTIVE state. Operations can be chained before calling Transaction.commit().

      Parameters:
      accountId - the account to transact against
      ctx - context containing actor and optional reason
      Returns:
      a new active transaction

    • getBalanceByAccount

      CompletableFuture<BigDecimal> getBalanceByAccount(UUID accountId)
      Asynchronously retrieves the balance of the specified account.
      Parameters:
      accountId - the account identifier
      Returns:
      future completing with the account balance

    • getBalanceByHolder

      CompletableFuture<BigDecimal> getBalanceByHolder(UUID holderId)
      Asynchronously retrieves the balance of the account for the specified holder.
      Parameters:
      holderId - the holder's unique identifier
      Returns:
      future completing with the account balance

    • getBalances

      CompletableFuture<List<BigDecimal>> getBalances(List<UUID> accountIds)
      Asynchronously retrieves balances for multiple accounts in a single batch operation.
      Parameters:
      accountIds - list of account identifiers
      Returns:
      future completing with list of balances in the same order as input

    • hasAccount

      CompletableFuture<Boolean> hasAccount(UUID holderId)
      Asynchronously checks if an account exists for the specified holder.
      Parameters:
      holderId - the holder's unique identifier
      Returns:
      future completing with true if account exists, false otherwise

    • createAccount

      CompletableFuture<Account> createAccount(UUID holderId, String name)
      Asynchronously creates a new account for the specified holder.
      Parameters:
      holderId - the holder's unique identifier
      name - the display name for the account
      Returns:
      future completing with the newly created account

    • getAccount

      CompletableFuture<Optional<Account>> getAccount(UUID accountId)
      Asynchronously retrieves an account by its identifier.
      Parameters:
      accountId - the account identifier
      Returns:
      future completing with optional containing the account if found, empty otherwise

    • deleteAccount

      CompletableFuture<Boolean> deleteAccount(UUID accountId)
      Asynchronously deletes the specified account.
      Parameters:
      accountId - the account identifier
      Returns:
      future completing with true if account was deleted, false if not found

    • updateAccountName

      CompletableFuture<Boolean> updateAccountName(UUID accountId, String name)
      Asynchronously updates the display name of the specified account.
      Parameters:
      accountId - the account identifier
      name - the new display name for the account
      Returns:
      future completing with true if account name was updated, false if account not found

    • transfer

      CompletableFuture<BigDecimal> transfer(UUID fromHolderId, UUID toHolderId, BigDecimal amount)
      Asynchronously transfers funds from one holder's account to another holder's account.
      Parameters:
      fromHolderId - the holder transferring funds
      toHolderId - the holder receiving funds
      amount - the amount to transfer
      Returns:
      future completing with the amount actually transferred

    • deposit

      CompletableFuture<BigDecimal> deposit(UUID holderId, BigDecimal amount)
      Asynchronously deposits funds into the specified holder's account.
      Parameters:
      holderId - the holder's unique identifier
      amount - the amount to deposit
      Returns:
      future completing with the amount actually deposited

    • withdraw

      CompletableFuture<BigDecimal> withdraw(UUID holderId, BigDecimal amount)
      Asynchronously withdraws funds from the specified holder's account.
      Parameters:
      holderId - the holder's unique identifier
      amount - the amount to withdraw
      Returns:
      future completing with the amount actually withdrawn

    • getTopBalances

      CompletableFuture<Map<UUID,BigDecimal>> getTopBalances(int limit)
      Asynchronously retrieves all holder balances sorted by balance in descending order.

      This is useful for leaderboards and statistics. The returned map contains holder UUIDs as keys and their corresponding balances as values.

      Parameters:
      limit - the maximum number of entries to return
      Returns:
      future completing with a list of holder-balance pairs sorted by balance (highest first)