NotableDateCacheBase<TOptions> Class

Definition

Namespace

Bodu.Globalization.Calendar.Caching

Assembly

Bodu.Globalization.Calendar.Caching.dll

Package

Bodu.Globalization.Calendar.Caching 1.0.0

Source

NotableDateCacheBase{T}.cs

Provides the storage-agnostic mechanism for an INotableDateCache: territory normalization, read-time freshness and version filtering, and write-time merge-and-prune of per-year entries. Derived types implement only the persistence of a territory's entry list; this base prescribes no physical storage structure.

public abstract class NotableDateCacheBase<TOptions> : INotableDateCache where TOptions : NotableDateCacheOptions

Type Parameters

TOptions

The options type carrying any storage settings.

Inheritance

object

NotableDateCacheBase<TOptions>

Implements

INotableDateCache

Derived

DistributedNotableDateCache

FileNotableDateCacheBase

InMemoryNotableDateCache

SqliteNotableDateCache

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

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

ReadEntries(string) returns the raw stored entries without filtering; this base applies the freshness and version policy in GetYear(string, int, string, TimeSpan, DateTimeOffset) and prunes stale and superseded entries in StoreYear(NotableDateCacheEntry, TimeSpan, DateTimeOffset), so the backing store self-cleans on every write. The read-modify-write sequence in StoreYear(NotableDateCacheEntry, TimeSpan, DateTimeOffset) runs under a per-territory lock so concurrent writes to the same territory cannot interleave and lose an entry.

The freshness, validity, version-matching, and merge rules are delegated to the shared Bodu.Globalization.Calendar.Caching.NotableDateCacheRules so every backend applies one authoritative policy. This base contributes only the per-territory locking and the read-modify-write sequencing over the entry list.

Constructors

NotableDateCacheBase(TOptions)

Initializes a new instance of the NotableDateCacheBase<TOptions> class.

protected NotableDateCacheBase(TOptions options)

Parameters

options TOptions

The options carrying any storage settings.

Exceptions

ArgumentNullException

Thrown when options is null.

ArgumentException

Thrown when options fails validation.

Properties

Options

Gets the validated options the cache was constructed with.

protected TOptions Options { get; }

Property Value

TOptions

The cache options.

Methods

Clear()

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

public abstract 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.

public virtual 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 abstract 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.

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.

public 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.

WriteEntries(string, IReadOnlyList<NotableDateCacheEntry>)

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

protected abstract 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 virtual 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