FileNotableDateCacheBase Class
Definition
- Namespace
- Bodu.Globalization.Calendar.Caching
- Assembly
- Bodu.Globalization.Calendar.Caching.dll
- Package
- Bodu.Globalization.Calendar.Caching 1.3.0
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
-
FileNotableDateCacheBase
- Implements
- Derived
- Inherited Members
- Extension Methods
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
optionsFileNotableDateCacheOptionsThe file-cache options that select the storage directory.
timeProviderTimeProviderThe time source the swallowed-failure warning rate-limiting is measured against, or null to use System.
loggerILoggerThe 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
optionsis null.- ArgumentException
Thrown when
optionsfails 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
.tomlor.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
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.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |