EventsCollection Class

The value of the "events" claim: the event statements a SET expresses, each a name/value pair whose name is the event identifier URI and whose value is the event's payload (RFC 8417 Section 2.2).

public sealed class EventsCollection : System.Collections.Generic.IReadOnlyCollection<System.Collections.Generic.KeyValuePair<string, System.Text.Json.Nodes.JsonObject>>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<string, System.Text.Json.Nodes.JsonObject>>, System.Collections.IEnumerable

Inheritance System.Object → EventsCollection

Implements System.Collections.Generic.IReadOnlyCollection<System.Collections.Generic.KeyValuePair<System.String,System.Text.Json.Nodes.JsonObject>>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<System.String,System.Text.Json.Nodes.JsonObject>>, System.Collections.IEnumerable

Remarks

The statements of one SET describe aspects of ONE state transition: RFC 8417 Section 2 says multiple identifiers "represent multiple aspects of the same state transition" and Section 2.2 that the claim "MUST NOT be used to express multiple independent logical events". That rule is about meaning, so no code can check it - it is the caller's to honour when adding a second statement.

Constructors

EventsCollection() Constructor

Creates an empty collection, to be filled through Add(string, JsonObject).

public EventsCollection();

EventsCollection(JsonObject) Constructor

The value of the "events" claim: the event statements a SET expresses, each a name/value pair whose name is the event identifier URI and whose value is the event's payload (RFC 8417 Section 2.2).

public EventsCollection(System.Text.Json.Nodes.JsonObject json);

Parameters

json System.Text.Json.Nodes.JsonObject

The JSON object holding the event statements, read and written in place, never copied.

Remarks

The statements of one SET describe aspects of ONE state transition: RFC 8417 Section 2 says multiple identifiers "represent multiple aspects of the same state transition" and Section 2.2 that the claim "MUST NOT be used to express multiple independent logical events". That rule is about meaning, so no code can check it - it is the caller's to honour when adding a second statement.

Properties

EventsCollection.Count Property

The number of event statements. RFC 8417 Section 2 requires at least one in a valid SET; whether that holds for a token read off the wire is the validation pipeline's question.

public int Count { get; }

Implements Count

Property Value

System.Int32

EventsCollection.Json Property

The underlying JSON object, in the exact shape the "events" claim carries on the wire.

public System.Text.Json.Nodes.JsonObject Json { get; }

Property Value

System.Text.Json.Nodes.JsonObject

Methods

EventsCollection.Add(string, JsonObject) Method

Adds an event statement.

public void Add(string eventType, System.Text.Json.Nodes.JsonObject? payload=null);

Parameters

eventType System.String

The event identifier URI. RFC 8417 Section 2.2 asks for stable values, such as a permanent URL of the event's specification.

payload System.Text.Json.Nodes.JsonObject

The event's payload. The parameter type already keeps Section 2.2's "the corresponding value MUST be a JSON object". Null stands for an event with no payload claims, which "SHALL be represented as the empty JSON object" (RFC 8417 Section 2) - the empty object is written here so no caller has to remember that rule.

Exceptions

System.ArgumentException
A statement with the same event identifier is already present - "Multiple event identifiers with the same value MUST NOT be used" (RFC 8417 Section 2.2) - or the payload is still attached to another JSON tree; pass a copy of a parsed node rather than the node itself.

EventsCollection.Contains(string) Method

Tells whether a statement with the given event identifier is present.

public bool Contains(string eventType);

Parameters

eventType System.String

The event identifier URI.

Returns

System.Boolean

EventsCollection.GetEnumerator() Method

Enumerates the event statements as (event identifier, payload) pairs.

public System.Collections.Generic.IEnumerator<System.Collections.Generic.KeyValuePair<string,System.Text.Json.Nodes.JsonObject>> GetEnumerator();

Implements GetEnumerator(), GetEnumerator()

Returns

System.Collections.Generic.IEnumerator<System.Collections.Generic.KeyValuePair<System.String,System.Text.Json.Nodes.JsonObject>>

Exceptions

System.InvalidOperationException
A statement's value is not a JSON object. RFC 8417 Section 2.2 forbids that shape, and this view refuses to invent a payload for it; the validation pipeline is where such a token gets its verdict.

EventsCollection.TryGetPayload(string, JsonObject) Method

Retrieves the payload of the statement with the given event identifier.

public bool TryGetPayload(string eventType, out System.Text.Json.Nodes.JsonObject payload);

Parameters

eventType System.String

The event identifier URI.

payload System.Text.Json.Nodes.JsonObject

The event's payload object when present and well-formed.

Returns

System.Boolean
True when the statement exists and its value is a JSON object, as RFC 8417 Section 2.2 requires; false when it is absent or malformed.