Class CharacterHotkeyService

Namespace

FishMMO.Database.Npgsql.Services

Assembly

FishMMO-DB.dll

Service for managing character hotkeys in the database. Provides async operations for CRUD operations on character hotkey bar data. Implements execution strategies for automatic retry on transient database failures. Returns DatabaseResult for consistent, safe error handling.

public sealed class CharacterHotkeyService : BaseService<CharacterHotkeyEntity>, ICharacterHotkeyService, ICountByKeyAction<long>, IPersistAction<CharacterHotkeyData, long>, IPersistManyAction<CharacterHotkeyData>, IDeleteByKeyVersionedAction<long>, IFetchCollectionByKeyAction<long, CharacterHotkeyData>

Inheritance

object

BaseService<CharacterHotkeyEntity>

CharacterHotkeyService

Implements

ICharacterHotkeyService

ICountByKeyAction<long>

IPersistAction<CharacterHotkeyData, long>

IPersistManyAction<CharacterHotkeyData>

IDeleteByKeyVersionedAction<long>

IFetchCollectionByKeyAction<long, CharacterHotkeyData>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This service manages character hotkey bars including:

• Single hotkey save/update with atomic UPSERT operations
• Batch hotkey save/update with explicit transactions
• Hotkey deletion (bulk operations)
• Hotkey retrieval and count queries

All exceptions are classified by BaseService and mapped to DatabaseResult error codes (e.g., UNIQUE_VIOLATION, FOREIGN_KEY_VIOLATION, STALE_STATE, DATABASE_ERROR). Transient failures are retried automatically. Methods return DatabaseResult to provide structured error handling without throwing exceptions to calling code. Unique constraint violations are not used as normal control flow; write paths prefer deterministic SQL (e.g. UPSERT) where appropriate.

Constructors

CharacterHotkeyService(INpgsqlDbContextFactory)

Initializes a new instance of the CharacterHotkeyService class.

public CharacterHotkeyService(INpgsqlDbContextFactory dbContextFactory)

Parameters

dbContextFactory INpgsqlDbContextFactory

Factory for creating database contexts.

Exceptions

ArgumentNullException

Thrown when dbContextFactory is null.

Methods

CountAsync(long, CancellationToken)

Counts items for the given key.

public Task<DatabaseResult<int>> CountAsync(long characterId, CancellationToken cancellationToken = default)

Parameters

characterId long

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<int>>

DeleteAsync(long, long, CancellationToken)

Deletes the entity identified by the given key if incomingVersion is newer.

public Task<DatabaseResult> DeleteAsync(long characterId, long incomingVersion, CancellationToken cancellationToken = default)

Parameters

characterId long

incomingVersion long

The authoritative, monotonic version for this delete operation.

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult>

FetchAsync(long, CancellationToken)

Fetches a collection of items for the given key.

public Task<DatabaseResult<IReadOnlyList<CharacterHotkeyData>>> FetchAsync(long characterId, CancellationToken cancellationToken = default)

Parameters

characterId long

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<IReadOnlyList<CharacterHotkeyData>>>

PersistAsync(CharacterHotkeyData, CancellationToken)

Persists the provided data.

public Task<DatabaseResult<long>> PersistAsync(CharacterHotkeyData hotkey, CancellationToken cancellationToken = default)

Parameters

hotkey CharacterHotkeyData

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<long>>

PersistAsync(IEnumerable<CharacterHotkeyData>, CancellationToken)

Persists the provided items.

public Task<DatabaseResult<BulkWriteResult>> PersistAsync(IEnumerable<CharacterHotkeyData> hotkeys, CancellationToken cancellationToken = default)

Parameters

hotkeys IEnumerable<CharacterHotkeyData>

cancellationToken CancellationToken

Token to cancel the operation.

Returns

Task<DatabaseResult<BulkWriteResult>>

What the write actually did, or a failure.

Remarks

A successful result does not mean every supplied row was written. Batched writes are version-gated and the service filters what it cannot act on, so the outcome carries counts rather than a bare boolean — see BulkWriteResult, which explains which discrepancies a caller should care about and which are routine.