DistributedNotableDateCache Class
Definition
- Namespace
- Bodu.Globalization.Calendar.Caching
- Assembly
- Bodu.Globalization.Calendar.Caching.Distributed.dll
- Package
- Bodu.Globalization.Calendar.Caching.Distributed 1.3.0
An INotableDateCache that persists computed years in any IDistributedCache - Redis, SQL Server, or an in-memory distributed cache - as one JSON blob per territory, expiring them through the same freshness and version mechanism as the other backends.
public sealed class DistributedNotableDateCache : NotableDateCacheBase<DistributedNotableDateCacheOptions>, INotableDateCache
- Inheritance
-
DistributedNotableDateCache
- Implements
- Inherited Members
- Extension Methods
Remarks
A territory's cached years are stored as a single JSON blob under a per-territory key, so a read-modify-write of a territory's state is one get and one set. The read-merge-write mechanism, per-territory in-process locking, and the freshness, validity, version-matching, and merge rules are all inherited from NotableDateCacheBase<TOptions>; this class contributes only the blob storage. Because IDistributedCache offers no atomic read-modify-write, concurrent writes from separate processes are last-write-wins, which is acceptable for a best-effort cache.
As required by INotableDateCache, a storage failure surfaces as an empty read or a skipped write rather than an exception; cancellation is allowed to propagate. Each swallowed failure is logged at Warning rate-limited to at most one warning per minute. Because a distributed store cannot be enumerated through IDistributedCache, Clear() removes only the keys this instance has written.
Constructors
DistributedNotableDateCache(IDistributedCache, DistributedNotableDateCacheOptions, TimeProvider?, ILogger?)
Initializes a new instance of the DistributedNotableDateCache class.
public DistributedNotableDateCache(IDistributedCache cache, DistributedNotableDateCacheOptions options, TimeProvider? timeProvider = null, ILogger? logger = null)
Parameters
cacheIDistributedCacheThe backing distributed store.
optionsDistributedNotableDateCacheOptionsThe options carrying the key prefix.
timeProviderTimeProviderThe time source the degradation-warning cooldown is measured against, or null to use System.
loggerILoggerThe logger that receives the rate-limited best-effort degradation warnings, or null to leave the degradation unreported.
Exceptions
- ArgumentNullException
Thrown when
cacheoroptionsis null.- ArgumentException
Thrown when
optionsfails validation.
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.
ReadEntries(string)
Reads the raw, unfiltered persisted entries for a normalized territory.
protected override IReadOnlyList<NotableDateCacheEntry> ReadEntries(string territory)
Parameters
territorystringThe 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 this assembly can call the storage seam, while a backend in
any other assembly can still derive from this base and override it: the companion SQLite and distributed
packages do, and a third-party store overrides it with protected override.
A backend that needs none of this base's policy 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
territorystringThe normalized territory key.
entriesIReadOnlyList<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.
WriteEntries(string, IReadOnlyList<NotableDateCacheEntry>, TimeSpan, DateTimeOffset)
Writes the supplied entries for a normalized territory with the time-to-live and evaluation instant the write was performed under, so a backend whose store supports server-side expiration can derive an entry lifetime.
protected override bool WriteEntries(string territory, IReadOnlyList<NotableDateCacheEntry> entries, TimeSpan ttl, DateTimeOffset asOf)
Parameters
territorystringThe normalized territory key.
entriesIReadOnlyList<NotableDateCacheEntry>The entries to persist.
ttlTimeSpanThe time-to-live the write's freshness pruning was evaluated against.
asOfDateTimeOffsetThe instant the write was evaluated at.
Returns
- bool
true when the entries were persisted; false when a storage failure was swallowed and nothing was persisted.
Remarks
The default implementation ignores the time-to-live and delegates to WriteEntries(string, IReadOnlyList<NotableDateCacheEntry>), so backends without server-side expiration - and third-party derivations of the existing seam - are unaffected. The distributed backend overrides this to stamp an absolute expiration onto each territory blob so untouched keys self-evict.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |