Table of Contents

Interface IUpcastingPipeline

Namespace
Excalibur.Dispatch
Assembly
Excalibur.Dispatch.Abstractions.dll

Manages automatic message version migration for ALL message types using registered upcasters.

public interface IUpcastingPipeline
Extension Methods

Remarks

The pipeline builds a directed graph of version transformations and uses breadth-first search to find shortest paths between any two versions. Paths are computed once and cached for O(1) lookup performance.

Supports all message types:

Thread Safety: Implementations must be thread-safe for concurrent reads and safe for concurrent registration during application startup.

Methods

CanUpcast(string, int, int)

Checks if a path exists between two versions for a message type.

bool CanUpcast(string messageType, int fromVersion, int toVersion)

Parameters

messageType string

The logical message type name.

fromVersion int

The source version.

toVersion int

The target version.

Returns

bool

True if a path exists (including multi-hop); otherwise false.

Remarks

This method can be used to validate upcasting capability before attempting the operation, or to provide diagnostic information about registered paths.

GetLatestVersion(string)

Gets the latest registered version for a message type.

int GetLatestVersion(string messageType)

Parameters

messageType string

The logical message type name.

Returns

int

The highest version number, or 0 if no versions registered.

Register<TOld, TNew>(IMessageUpcaster<TOld, TNew>)

Registers a generic message upcaster for a specific version transition.

void Register<TOld, TNew>(IMessageUpcaster<TOld, TNew> upcaster) where TOld : IDispatchMessage, IVersionedMessage where TNew : IDispatchMessage, IVersionedMessage

Parameters

upcaster IMessageUpcaster<TOld, TNew>

The upcaster instance.

Type Parameters

TOld

The old message type.

TNew

The new message type.

Remarks

Registration should typically happen during application startup via dependency injection. Multiple upcasters can be registered to form a chain (v1→v2→v3→v4).

After registration, paths are automatically computed using BFS.

Upcast(IDispatchMessage)

Upcasts a message to the latest registered version for its type.

IDispatchMessage Upcast(IDispatchMessage message)

Parameters

message IDispatchMessage

The message to upcast (any version, any type).

Returns

IDispatchMessage

The message upcasted to the version that was latest when the call observed the registered upcasters, or the original message if it was already there.

Remarks

If no upcasters are registered for the message type, returns the original message unchanged.

"Latest" is observed once, at the start of the call. An implementation reads the registered upcasters a single time and both chooses the target version and resolves the chain against that one observation — which is what makes the result explicable by a single set of registrations. The visible consequence is that a Register<TOld, TNew>(IMessageUpcaster<TOld, TNew>) completing on another thread DURING this call does not retroactively raise this call's target: the returned message may be at a version that is no longer the latest by the time you inspect it. That is the correct and intended behaviour, equivalent to the registration having happened immediately after this call returned, and it is stated here because the method name alone implies otherwise.

Callers that need the newest version after a concurrent registration should call again. Callers that need a specific version should use UpcastTo(IDispatchMessage, int), which takes the target explicitly.

UpcastTo(IDispatchMessage, int)

Upcasts a message to a specific target version.

IDispatchMessage UpcastTo(IDispatchMessage message, int targetVersion)

Parameters

message IDispatchMessage

The message to upcast.

targetVersion int

The desired version.

Returns

IDispatchMessage

The message at the target version.

Exceptions

InvalidOperationException

Thrown when no path exists to the target version, or when attempting to downcast (target version is lower than source version).