SqliteNotableDateCache Class

Definition

Namespace

Bodu.Globalization.Calendar.Caching

Assembly

Bodu.Globalization.Calendar.Caching.Sqlite.dll

Package

Bodu.Globalization.Calendar.Caching.Sqlite 1.0.0

Source

SqliteNotableDateCache.cs

An INotableDateCache that persists computed years in a SQLite database, expiring them through the same freshness and version mechanism as the in-memory and file caches.

public sealed class SqliteNotableDateCache : NotableDateCacheBase<SqliteNotableDateCacheOptions>, INotableDateCache, IDisposable

Inheritance

object

NotableDateCacheBase<SqliteNotableDateCacheOptions>

SqliteNotableDateCache

Implements

INotableDateCache

IDisposable

Inherited Members

NotableDateCacheBase<SqliteNotableDateCacheOptions>.StoreYear(NotableDateCacheEntry, TimeSpan, DateTimeOffset)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ComparableExtensions.AtLeast<T>(T, T, IComparer<T>)

ComparableExtensions.AtMost<T>(T, T, IComparer<T>)

ComparableExtensions.IsEqualTo<T>(T, T, IComparer<T>)

ComparableExtensions.Max<T>(T, T, IComparer<T>)

ComparableExtensions.Min<T>(T, T, IComparer<T>)

Remarks

Computed years live in one table keyed by (territory, year, version), one row per cached year, with the year's occurrences stored as a JSON blob and the computed instant as invariant round-trip text. The read-merge-write mechanism, per-territory locking, and the freshness, validity, version-matching, and merge rules are all inherited from NotableDateCacheBase<TOptions>; this class contributes only its SQLite storage, plus a single-row GetYear(string, int, string, TimeSpan, DateTimeOffset) override so a lookup reads one row rather than parsing every year's occurrence blob.

The cache is a single-process best-effort store. As required by INotableDateCache, a storage failure surfaces as an empty read or a skipped write rather than an exception, and each swallowed failure is logged at Warning rate-limited to at most one warning per minute. A single keep-alive connection is held open for the instance lifetime so a shared in-memory database survives between operations.

Constructors

SqliteNotableDateCache(SqliteNotableDateCacheOptions, TimeProvider?, ILogger?)

Initializes a new instance of the SqliteNotableDateCache class.

public SqliteNotableDateCache(SqliteNotableDateCacheOptions options, TimeProvider? timeProvider = null, ILogger? logger = null)

Parameters

options SqliteNotableDateCacheOptions

The options carrying the database location.

timeProvider TimeProvider

The time source the degradation-warning cooldown is measured against, or null to use System.

logger ILogger

The logger that receives the rate-limited best-effort degradation warnings, or null to leave the degradation unreported.

Exceptions

ArgumentNullException

Thrown when options is null.

ArgumentException

Thrown when options fails validation.

SqliteNotableDateCache(string)

Initializes a new instance of the SqliteNotableDateCache class bound to a database file.

public SqliteNotableDateCache(string databaseFilePath)

Parameters

databaseFilePath string

The path to the SQLite database file used by the cache.

Exceptions

ArgumentNullException

Thrown when databaseFilePath is null.

ArgumentException

Thrown when databaseFilePath is empty or white space.

Methods

Clear()

Removes every cached entry, returning the cache to its empty state.

public override void Clear()

Remarks

This is a best-effort operation: a backing-store failure is swallowed rather than thrown, consistent with the rest of the contract.

Dispose()

Releases the keep-alive connection held for the instance lifetime and clears the connection pool, so every handle to the database is closed and the file is deletable immediately after disposal.

public void Dispose()

Remarks

Idempotent: a second or concurrent call is a safe no-op. The disposed flag is flipped with Exchange(ref int, int) so exactly one caller wins the transition and disposes the keep-alive connection. Clearing the pool is required because Microsoft.Data.Sqlite pools closed connections by default: without it, the pooled handles from per-operation connections (and the returned keep-alive) keep the database file open past disposal, which blocks deletion on Windows and leaves the write-ahead-log sidecar unpurged everywhere.

GetYear(string, int, string, TimeSpan, DateTimeOffset)

Returns the cached entry for the requested territory, civil year, and resource version when one is present and still fresh, evaluated against asOf.

public override NotableDateCacheEntry? GetYear(string territory, int year, string resourceVersion, TimeSpan ttl, DateTimeOffset asOf)

Parameters

territory string

The requested territory code.

year int

The civil year.

resourceVersion string

The version token of the resource currently in effect.

ttl TimeSpan

The duration a computed year remains fresh after it was computed.

asOf DateTimeOffset

The instant against which freshness is evaluated.

Returns

NotableDateCacheEntry

The fresh, version-matching cached entry, or null when none is available, fresh, or version-matching.

Remarks

Declared virtual so a backend whose storage can answer a single year cheaper than reading the whole territory - for example a keyed database row - can override the read while inheriting the write mechanism. An override must apply the same freshness, validity, and version policy through Bodu.Globalization.Calendar.Caching.NotableDateCacheRules.

Exceptions

ArgumentNullException

Thrown when territory or resourceVersion is null.

ReadEntries(string)

Reads the raw, unfiltered persisted entries for a normalized territory.

protected override IReadOnlyList<NotableDateCacheEntry> ReadEntries(string territory)

Parameters

territory string

The normalized territory key.

Returns

IReadOnlyList<NotableDateCacheEntry>

The stored entries, or an empty list when none are available or the read fails.

Remarks

Declared protected internal so the storage seam is open to the backends in this assembly and in the companion SQLite and distributed packages, which derive from this base. An unrelated third-party backend implements the public INotableDateCache contract directly instead, as NullNotableDateCache does.

WriteEntries(string, IReadOnlyList<NotableDateCacheEntry>)

Writes the supplied entries for a normalized territory, replacing any existing state.

protected override bool WriteEntries(string territory, IReadOnlyList<NotableDateCacheEntry> entries)

Parameters

territory string

The normalized territory key.

entries IReadOnlyList<NotableDateCacheEntry>

The entries to persist. The list is freshly allocated by the caller for this write, so a backend may store the reference directly without a defensive copy.

Returns

bool

true when the entries were persisted, including the deliberate deletion of an empty state; false when a storage failure was swallowed and nothing was persisted.

Remarks

Declared protected internal for the same reason as ReadEntries(string). The bool result lets StoreYear(NotableDateCacheEntry, TimeSpan, DateTimeOffset) distinguish a durable write from a best-effort backend that swallowed a fault, so a failed write is reported as Failed rather than falsely as Stored.

Applies to

Product	Versions
.NET	8, 10