Table of Contents

CachingNotableDateService Class

Definition

Namespace
Bodu.Globalization.Calendar.Caching
Assembly
Bodu.Globalization.Calendar.Caching.dll
Package
Bodu.Globalization.Calendar.Caching 1.3.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
CachingNotableDateService
Implements
Inherited Members
Extension Methods

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 as the wrapped service selects them: by default an occurrence is kept when any day from its emitted date to its last day falls within the window, and under the resource's ObservedDateRangePolicy its actual span, or either span, decides instead. 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.

A civil year's entry holds every occurrence the wrapped service includes in the year, by default every occurrence whose span overlaps it, so a multi-day occurrence that starts in one year and runs into the next is held by both years' entries. A range spanning several years therefore takes such an occurrence from the entry of the year its controlling span starts in (the emitted span by default, the actual span or the earlier of the two under the resource's ObservedDateRangePolicy), or from the first year's entry when that span starts before the range's first year, and never returns it twice.

The decorator learns the observed-date range policy from the resource provider it observes, or else from the NotableDateService or ReloadableNotableDateService it wraps. Around any other INotableDateService, with no provider, it clips by the emitted span.

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 the occurrences taken from one civil year's entry always precede those taken from 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 span intersects 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 span covers 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

ProductVersions
.NET8, 10