CachingNotableDateService Class

Definition

Namespace

Bodu.Globalization.Calendar.Caching

Assembly

Bodu.Globalization.Calendar.Caching.dll

Package

Bodu.Globalization.Calendar.Caching 1.0.0

Source

CachingNotableDateService.cs

An INotableDateService decorator that serves notable-date resolutions from an INotableDateCache, recomputing and caching a whole civil year on a miss and refreshing on a time-to-live or a resource-version change.

public sealed class CachingNotableDateService : INotableDateService, IDisposable

Inheritance

object

CachingNotableDateService

Implements

INotableDateService

IDisposable

Inherited Members

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

Every query is answered per civil year: a range is decomposed into the years it spans, each year is served from the cache when a fresh, version-matching entry exists or otherwise recomputed for the whole year and written back, and the assembled occurrences are clipped to the requested window by their emitted date. Because the notable-date engine resolves per Gregorian year, a whole-year entry is the reusable unit: a later single-day or sub-range query for the same year is served without recomputing, and a query for exactly one whole civil year is served as the cached list itself with no copying.

Output ordering relies on the INotableDateCache ordering contract - cached occurrences round-trip in the order supplied, which is the wrapped service's date-then-identity ordering, and emitted dates in one civil year always precede the next year's - so assembled results are ordered without re-sorting. As a safeguard, the assembled result is verified with a linear scan, and only a non-conforming cache backend pays a full sort.

The filtered overloads apply the filter after assembling the unfiltered result, exactly as the wrapped service does, so a NotableDateFilter never participates in the cache key. The discovery methods delegate straight to the wrapped service.

When constructed with an INotableDateResourceProvider, the decorator observes the resource currently in effect and derives a version token from its identity and a reload generation, so a Reload(NotableDateResource) invalidates every cached year on the next query. Without a provider, a fixed version token from the options is used.

Constructors

CachingNotableDateService(INotableDateService, INotableDateCache, NotableDateCachingOptions, INotableDateResourceProvider?, TimeProvider?, ILoggerFactory?, bool)

Initializes a new instance of the CachingNotableDateService class.

public CachingNotableDateService(INotableDateService inner, INotableDateCache cache, NotableDateCachingOptions options, INotableDateResourceProvider? versionSource = null, TimeProvider? timeProvider = null, ILoggerFactory? loggerFactory = null, bool ownsCache = false)

Parameters

inner INotableDateService

The service that computes a year on a cache miss.

cache INotableDateCache

The cache computed years are served from and written to.

options NotableDateCachingOptions

The caching options.

versionSource INotableDateResourceProvider

The resource provider to observe for reloads, or null to use a fixed version token from options.

timeProvider TimeProvider

The clock the computed and lookup instants are measured against, or null for System.

loggerFactory ILoggerFactory

The factory used to create the diagnostics logger, or null to disable logging.

ownsCache bool

Whether this service disposes cache when it is disposed.

Exceptions

ArgumentNullException

Thrown when inner, cache, or options is null.

ArgumentException

Thrown when options fails validation.

Methods

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetSupportedCalendars()

Gets the distinct calendar systems any rule in the resource is expressed in.

public IReadOnlyList<CalendarSystem> GetSupportedCalendars()

Returns

IReadOnlyList<CalendarSystem>

The calendar systems in use, in ascending order.

GetSupportedTerritories()

Gets the distinct territories any rule in the resource is scoped to.

public IReadOnlyList<string> GetSupportedTerritories()

Returns

IReadOnlyList<string>

The scoped territory codes in case-insensitive ascending order; empty when every rule is global (unscoped).

Resolve(DateRange, string)

Resolves the notable-date occurrences emitted within an inclusive date range for the requested territory.

public IReadOnlyList<NotableDate> Resolve(DateRange range, string territory)

Parameters

range DateRange

The inclusive range of days to resolve.

territory string

The requested territory code.

Returns

IReadOnlyList<NotableDate>

The occurrences whose emitted date falls within the range, ordered by date then identity.

Resolve(DateRange, string, NotableDateFilter)

Resolves the notable-date occurrences emitted within an inclusive date range for the requested territory, restricted to those matching the supplied filter.

public IReadOnlyList<NotableDate> Resolve(DateRange range, string territory, NotableDateFilter filter)

Parameters

range DateRange

The inclusive range of days to resolve.

territory string

The requested territory code.

filter NotableDateFilter

The filter that emitted occurrences must satisfy.

Returns

IReadOnlyList<NotableDate>

The matching occurrences, ordered by date then identity.

Resolve(DateOnly, string)

Resolves the notable-date occurrences emitted on a single day for the requested territory.

public IReadOnlyList<NotableDate> Resolve(DateOnly date, string territory)

Parameters

date DateOnly

The day to resolve.

territory string

The requested territory code.

Returns

IReadOnlyList<NotableDate>

The occurrences whose emitted date equals date; empty when there are none.

Resolve(DateOnly, string, NotableDateFilter)

Resolves the notable-date occurrences emitted on a single day for the requested territory, restricted to those matching the supplied filter.

public IReadOnlyList<NotableDate> Resolve(DateOnly date, string territory, NotableDateFilter filter)

Parameters

date DateOnly

The day to resolve.

territory string

The requested territory code.

filter NotableDateFilter

The filter that emitted occurrences must satisfy.

Returns

IReadOnlyList<NotableDate>

The matching occurrences; empty when there are none.

Warm(IEnumerable<string>, int, int)

Warms the cache for a set of territories over an inclusive span of civil years, resolving each territory's whole span through the normal read-through path so cold years are computed and cached while already cached years cost only a cache read.

public int Warm(IEnumerable<string> territories, int firstYear, int lastYear)

Parameters

territories IEnumerable<string>

The territory codes to warm.

firstYear int

The inclusive first civil year of the span to warm.

lastYear int

The inclusive last civil year of the span to warm.

Returns

int

The number of territories warmed successfully.

Remarks

Territories are warmed sequentially - year resolution is a synchronous, CPU-bound computation with no I/O to overlap. A territory whose resolution fails is logged at Warning and skipped - the remaining territories still warm - and is excluded from the returned count. Later queries for any warmed year are cache hits until the time-to-live or a resource-version change expires them.

Exceptions

ArgumentNullException

Thrown when territories is null.

ArgumentOutOfRangeException

firstYear or lastYear is outside the range representable by DateOnly.

ArgumentException

lastYear precedes firstYear.

Applies to

Product	Versions
.NET	8, 10