FileNotableDateCacheBase Class

Definition

Namespace

Bodu.Globalization.Calendar.Caching

Assembly

Bodu.Globalization.Calendar.Caching.dll

Package

Bodu.Globalization.Calendar.Caching 1.0.0

Source

FileNotableDateCacheBase.cs

Provides the file-storage mechanism for an INotableDateCache: one file per territory under a cache directory, atomic temp-and-move writes, a last-write-time parse memo, and best-effort degradation on storage failures. Derived types implement only the file extension and the serialization of a territory's entry list.

public abstract class FileNotableDateCacheBase : NotableDateCacheBase<FileNotableDateCacheOptions>, INotableDateCache

Inheritance

object

NotableDateCacheBase<FileNotableDateCacheOptions>

FileNotableDateCacheBase

Implements

INotableDateCache

Derived

JsonNotableDateCache

TomlNotableDateCache

Inherited Members

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

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

NotableDateCacheBase<FileNotableDateCacheOptions>.WriteEntries(string, IReadOnlyList<NotableDateCacheEntry>, TimeSpan, DateTimeOffset)

NotableDateCacheBase<FileNotableDateCacheOptions>.Options

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

Each territory maps to a single file named after the normalized, sanitized territory code. A read that fails, or a file that cannot be deserialized, degrades to an empty result rather than throwing (unless ThrowOnStorageFailure is set), and a swallowed storage failure is reported through a rate-limited warning so a sustained outage does not flood the log.

Writes are atomic through Bodu.Caching.AtomicFileWriter, so a concurrent reader never observes a partially written file, and a parse memo keyed by the file's last-write time avoids re-reading and re-parsing an unchanged file while still re-parsing a file changed by another process.

Constructors

FileNotableDateCacheBase(FileNotableDateCacheOptions, TimeProvider?, ILogger?)

Initializes a new instance of the FileNotableDateCacheBase class.

protected FileNotableDateCacheBase(FileNotableDateCacheOptions options, TimeProvider? timeProvider = null, ILogger? logger = null)

Parameters

options FileNotableDateCacheOptions

The file-cache options that select the storage directory.

timeProvider TimeProvider

The time source the swallowed-failure warning rate-limiting is measured against, or null to use System.

logger ILogger

The logger that receives a rate-limited warning when a best-effort storage failure is swallowed, or null to disable that reporting.

Exceptions

ArgumentNullException

Thrown when options is null.

ArgumentException

Thrown when options fails validation.

IOException

Thrown when ValidateStorageOnStart is set and the cache directory cannot be created. A path whose parent is a file reports the DirectoryNotFoundException specialization on some platforms and the base type on others, so catch IOException.

UnauthorizedAccessException

Thrown when ValidateStorageOnStart is set and the process lacks permission to create the cache directory.

Properties

CacheDirectory

Gets the directory the cache files are stored under.

public string CacheDirectory { get; }

Property Value

string

The resolved cache directory.

FileExtension

Gets the file extension used by the concrete format, including the leading dot.

protected abstract string FileExtension { get; }

Property Value

string

The file extension, such as .toml or .json.

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.

Applies to

Product	Versions
.NET	8, 10