CachingNotableDateService Class
Definition
- Namespace
- Bodu.Globalization.Calendar.Caching
- Assembly
- Bodu.Globalization.Calendar.Caching.dll
- Package
- Bodu.Globalization.Calendar.Caching 1.3.0
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
innerINotableDateServiceThe service that computes a year on a cache miss.
cacheINotableDateCacheThe cache computed years are served from and written to.
optionsNotableDateCachingOptionsThe caching options.
versionSourceINotableDateResourceProviderThe resource provider to observe for reloads, or null to use a fixed version token from
options.timeProviderTimeProviderThe clock the computed and lookup instants are measured against, or null for System.
loggerFactoryILoggerFactoryThe factory used to create the diagnostics logger, or null to disable logging.
ownsCacheboolWhether this service disposes
cachewhen it is disposed.
Exceptions
- ArgumentNullException
Thrown when
inner,cache, oroptionsis null.- ArgumentException
Thrown when
optionsfails 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
rangeDateRangeThe inclusive range of days to resolve.
territorystringThe 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
rangeDateRangeThe inclusive range of days to resolve.
territorystringThe requested territory code.
filterNotableDateFilterThe 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
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
dateDateOnlyThe day to resolve.
territorystringThe requested territory code.
filterNotableDateFilterThe 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
territoriesIEnumerable<string>The territory codes to warm.
firstYearintThe inclusive first civil year of the span to warm.
lastYearintThe 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
territoriesis null.- ArgumentOutOfRangeException
firstYearorlastYearis outside the range representable by DateOnly.- ArgumentException
lastYearprecedesfirstYear.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |