DistributedNotableDateCache Class

Definition

Namespace

Bodu.Globalization.Calendar.Caching

Assembly

Bodu.Globalization.Calendar.Caching.Distributed.dll

Package

Bodu.Globalization.Calendar.Caching.Distributed 1.0.0

Source

DistributedNotableDateCache.cs

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

object

NotableDateCacheBase<DistributedNotableDateCacheOptions>

DistributedNotableDateCache

Implements

INotableDateCache

Inherited Members

NotableDateCacheBase<DistributedNotableDateCacheOptions>.GetYear(string, int, string, TimeSpan, DateTimeOffset)

NotableDateCacheBase<DistributedNotableDateCacheOptions>.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

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

cache IDistributedCache

The backing distributed store.

options DistributedNotableDateCacheOptions

The options carrying the key prefix.

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 cache or options is null.

ArgumentException

Thrown when options fails 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

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.

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

territory string

The normalized territory key.

entries IReadOnlyList<NotableDateCacheEntry>

The entries to persist.

ttl TimeSpan

The time-to-live the write's freshness pruning was evaluated against.

asOf DateTimeOffset

The 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