Table of Contents

INotableDateCache Interface

Definition

Namespace
Bodu.Globalization.Calendar.Caching
Assembly
Bodu.Globalization.Calendar.Caching.dll
Package
Bodu.Globalization.Calendar.Caching 1.0.0
Source
INotableDateCache.cs

Persists computed notable-date resolutions so an expensive per-year resolution need not be recomputed while it remains fresh, keyed by territory, civil year, and resource version.

public interface INotableDateCache
Extension Methods

Remarks

The cache stores one NotableDateCacheEntry per (territory, year, resource version): the unfiltered occurrences the notable-date engine emits for a whole civil year. A range query is served by assembling the per-year entries it spans and clipping to the requested window, so the cache unit is always a single civil year.

The cache owns expiry. A caller supplies a time-to-live and an evaluation instant on every call: GetYear(string, int, string, TimeSpan, DateTimeOffset) returns an entry only while it is fresh, and StoreYear(NotableDateCacheEntry, TimeSpan, DateTimeOffset) prunes stale and superseded-version entries as it merges, so the backing store self-cleans over time. An entry is served only when its ResourceVersion matches the requested version, so a resource reload - signalled by a changed version token - forces a recompute rather than serving stale data.

Territory is normalized case-insensitively for keying, so us and US address the same entry; a subdivision (CA-ON) and its parent country (CA) are distinct keys, matching the engine's own resolution.

Ordering contract. An entry's occurrences must round-trip in the order they were supplied to StoreYear(NotableDateCacheEntry, TimeSpan, DateTimeOffset) - the notable-date service's date-then-identity order. The caching service relies on this to assemble ordered range results without re-sorting; a backend that cannot preserve order forces a sort fallback on every read it serves.

Implementations are expected to be resilient: a cache failure should manifest as an empty read or a no-op write rather than an exception that breaks notable-date resolution. Argument validation still throws.

Methods

Clear()

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

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.

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.

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.

Exceptions

ArgumentNullException

Thrown when territory or resourceVersion is null.

StoreYear(NotableDateCacheEntry, TimeSpan, DateTimeOffset)

Stores a computed year, merging it into the territory's cached entries so the most recently computed entry wins per year, and pruning entries that are stale or belong to a superseded resource version.

NotableDateCacheWriteStatus StoreYear(NotableDateCacheEntry entry, TimeSpan ttl, DateTimeOffset asOf)

Parameters

entry NotableDateCacheEntry

The computed year to store.

ttl TimeSpan

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

asOf DateTimeOffset

The instant against which stale entries are pruned.

Returns

NotableDateCacheWriteStatus

Stored when the entry was persisted; Failed when a storage error was swallowed and nothing was persisted; Skipped for a cache that intentionally stores nothing.

Exceptions

ArgumentNullException

Thrown when entry is null.

Applies to

ProductVersions
.NET8, 10