NotableDateResourceLoader Class

Definition

Namespace

Bodu.Globalization.Calendar

Assembly

Bodu.Globalization.Calendar.dll

Package

Bodu.Globalization.Calendar 1.0.1

Source

NotableDateResourceLoader.cs

Provides the entry points for loading a notable-date document from XML or JSON into a validated NotableDateResource.

public static class NotableDateResourceLoader

Inheritance

object

NotableDateResourceLoader

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// A self-contained document with no imports.
NotableDateResource resource = NotableDateResourceLoader.Load(documentXml);
NotableDateService service = new(resource);

// A document that imports shared concepts: map each import name to its content.
var library = new Dictionary<string, string>(StringComparer.Ordinal)
{
    ["common-christian"] = christianXml,
};
NotableDateResource composed = NotableDateResourceLoader.Load(
    documentXml,
    name => library.TryGetValue(name, out string? content) ? content : null);

// The same pipeline accepts the JSON projection of the schema.
NotableDateResource fromJson = NotableDateResourceLoader.LoadJson(documentJson);

Remarks

Loading runs the deterministic pipeline: parse the document, resolve its imports against a supplied resource resolver, apply ID-targeted override operations, assemble the resource, then run semantic validation. When any error-severity diagnostic is produced the load fails with a NotableDateValidationException that carries the full diagnostic set.

The overloads without a resolver cannot satisfy imports; a document declaring Imports must be loaded with the resolver overload, whose delegate maps a resource name to that resource's XML or JSON content.

When to use. Call Load(string, ILogger?) / LoadJson(string, ILogger?) (or the Stream overloads) for a self-contained document, and the resolver overloads when the document imports shared concepts or adjustment policies from other resources. For the bundled territory packs prefer the data-pack factories (for example the AmericasCalendarData bundle), which load and wire the embedded resources for you.

Logging. Each Load / LoadJson overload accepts an optional ILogger (defaulting to Instance, so logging is opt-in). When supplied it records a successfully loaded resource with its definition and policy counts (Debug) and a validation failure with its error-diagnostic count (Warning, logged immediately before the NotableDateValidationException is thrown). These levels are fixed.

Methods

Load(Stream, ILogger?)

Loads and validates a notable-date document from a stream of XML content.

public static NotableDateResource Load(Stream stream, ILogger? logger = null)

Parameters

stream Stream

The stream containing the notable-date document XML.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

The stream content is empty or white-space.

FormatException

The stream content is not well-formed XML.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

Load(Stream, Func<string, string?>, ILogger?)

Loads and validates a notable-date document from a stream of XML content, resolving imports through the supplied resolver.

public static NotableDateResource Load(Stream stream, Func<string, string?> resourceResolver, ILogger? logger = null)

Parameters

stream Stream

The stream containing the notable-date document XML.

resourceResolver Func<string, string>

A delegate mapping a resource name to its XML or JSON content, or null when missing.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

stream or resourceResolver is null.

ArgumentException

The stream content is empty or white-space.

FormatException

The stream content is not well-formed XML.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

Load(string, ILogger?)

Loads and validates a notable-date document from its XML content.

public static NotableDateResource Load(string xml, ILogger? logger = null)

Parameters

xml string

The notable-date document XML content.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

xml is null.

ArgumentException

xml is empty or white-space.

FormatException

xml is not well-formed XML.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

Load(string, Func<string, string?>, INotableDateAlgorithmRegistry?, ILogger?)

Loads and validates a notable-date document from its XML content, resolving imports through the supplied resolver and accepting custom algorithm keys registered in the supplied registry.

public static NotableDateResource Load(string xml, Func<string, string?> resourceResolver, INotableDateAlgorithmRegistry? algorithms, ILogger? logger = null)

Parameters

xml string

The notable-date document XML content.

resourceResolver Func<string, string>

A delegate mapping a resource name to its XML or JSON content, or null when missing.

algorithms INotableDateAlgorithmRegistry

A registry of custom algorithm keys to accept during validation, or null.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

xml or resourceResolver is null.

ArgumentException

xml is empty or white-space.

FormatException

xml is not well-formed XML.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

Load(string, Func<string, string?>, ILogger?)

Loads and validates a notable-date document from its XML content, resolving imports through the supplied resolver.

public static NotableDateResource Load(string xml, Func<string, string?> resourceResolver, ILogger? logger = null)

Parameters

xml string

The notable-date document XML content.

resourceResolver Func<string, string>

A delegate mapping a resource name to its XML or JSON content, or null when missing.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

xml or resourceResolver is null.

ArgumentException

xml is empty or white-space.

FormatException

xml is not well-formed XML.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

LoadBinary(Stream)

Loads a notable-date resource from a sealed binary rule pack.

public static NotableDateResource LoadBinary(Stream stream)

Parameters

stream Stream

The readable stream positioned at the start of a .bcal pack.

Returns

NotableDateResource

The loaded NotableDateResource.

Remarks

A binary pack is written from an already-validated resource (see NotableDateBinaryResource), so loading skips parsing and semantic validation entirely - the trim- and AOT-friendly load path. Integrity is still enforced: the payload digest and every structural bound are verified.

Exceptions

ArgumentNullException

stream is null.

NotableDateBinaryFormatException

The stream is not a notable-date binary rule pack, declares an unsupported format version, is truncated or corrupted, or carries a value outside the sealed format's tables.

LoadJson(Stream, ILogger?)

Loads and validates a notable-date document from a stream of JSON content.

public static NotableDateResource LoadJson(Stream stream, ILogger? logger = null)

Parameters

stream Stream

The stream containing the notable-date document JSON.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

The stream content is empty or white-space.

FormatException

The stream content is not well-formed JSON.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

LoadJson(string, ILogger?)

Loads and validates a notable-date document from its JSON content.

public static NotableDateResource LoadJson(string json, ILogger? logger = null)

Parameters

json string

The notable-date document JSON content.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

json is null.

ArgumentException

json is empty or white-space.

FormatException

json is not well-formed JSON.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

LoadJson(string, Func<string, string?>, ILogger?)

Loads and validates a notable-date document from its JSON content, resolving imports through the supplied resolver.

public static NotableDateResource LoadJson(string json, Func<string, string?> resourceResolver, ILogger? logger = null)

Parameters

json string

The notable-date document JSON content.

resourceResolver Func<string, string>

A delegate mapping a resource name to its XML or JSON content, or null when missing.

logger ILogger

The logger that receives load diagnostics. null selects Instance.

Returns

NotableDateResource

The loaded and validated NotableDateResource.

Exceptions

ArgumentNullException

json or resourceResolver is null.

ArgumentException

json is empty or white-space.

FormatException

json is not well-formed JSON.

NotableDateValidationException

The notable-date document produced one or more error diagnostics.

TryLoad(string, Func<string, string?>, INotableDateAlgorithmRegistry?, out NotableDateResource?, out IReadOnlyList<NotableDateValidationDiagnostic>)

Attempts to load and validate a notable-date document from XML content against a custom algorithm registry, collecting every diagnostic instead of throwing on validation failure.

public static bool TryLoad(string xml, Func<string, string?> resourceResolver, INotableDateAlgorithmRegistry? algorithms, out NotableDateResource? resource, out IReadOnlyList<NotableDateValidationDiagnostic> diagnostics)

Parameters

xml string

The notable-date document XML content.

resourceResolver Func<string, string>

A delegate mapping a resource name to its XML or JSON content, or null when missing.

algorithms INotableDateAlgorithmRegistry

The custom algorithm registry consulted when validating Algorithm strategy keys, or null for built-ins only.

resource NotableDateResource

The loaded resource, or null when the document does not validate.

diagnostics IReadOnlyList<NotableDateValidationDiagnostic>

Every diagnostic the parse, import resolution, and validation produced.

Returns

bool

true when the document loaded without error-severity diagnostics; otherwise false.

Exceptions

ArgumentNullException

xml or resourceResolver is null.

TryLoad(string, Func<string, string?>, out NotableDateResource?, out IReadOnlyList<NotableDateValidationDiagnostic>)

Attempts to load and validate a notable-date document from XML content, collecting every diagnostic - including warnings and informational messages - instead of throwing on validation failure.

public static bool TryLoad(string xml, Func<string, string?> resourceResolver, out NotableDateResource? resource, out IReadOnlyList<NotableDateValidationDiagnostic> diagnostics)

Parameters

xml string

The notable-date document XML content.

resourceResolver Func<string, string>

A delegate mapping a resource name to its XML or JSON content, or null when missing.

resource NotableDateResource

The loaded resource, or null when the document does not validate.

diagnostics IReadOnlyList<NotableDateValidationDiagnostic>

Every diagnostic the parse, import resolution, and validation produced.

Returns

bool

true when the document loaded without error-severity diagnostics; otherwise false.

Remarks

Unlike the throwing Load overloads, malformed XML is reported as a BODU-CAL-SYNTAX error diagnostic rather than a FormatException, so a caller can lint arbitrary input without exception handling. Argument errors still throw - the Try contract covers data, not usage.

Exceptions

ArgumentNullException

xml or resourceResolver is null.

TryLoadJson(string, Func<string, string?>, out NotableDateResource?, out IReadOnlyList<NotableDateValidationDiagnostic>)

Attempts to load and validate a notable-date document from JSON content, collecting every diagnostic instead of throwing on validation failure.

public static bool TryLoadJson(string json, Func<string, string?> resourceResolver, out NotableDateResource? resource, out IReadOnlyList<NotableDateValidationDiagnostic> diagnostics)

Parameters

json string

The notable-date document JSON content.

resourceResolver Func<string, string>

A delegate mapping a resource name to its XML or JSON content, or null when missing.

resource NotableDateResource

The loaded resource, or null when the document does not validate.

diagnostics IReadOnlyList<NotableDateValidationDiagnostic>

Every diagnostic the parse, import resolution, and validation produced.

Returns

bool

true when the document loaded without error-severity diagnostics; otherwise false.

Remarks

Malformed or empty JSON is reported as a BODU-CAL-SYNTAX error diagnostic rather than an exception.

Exceptions

ArgumentNullException

json or resourceResolver is null.

Applies to

Product	Versions
.NET	8, 10

See Also

NotableDateResource

NotableDateService

NotableDateValidationException

Building and extending the service (guide)