Namespaces

• SaffronLibrary.Prime.Systems.Requests: Request, RequestDispatcher, Response, RequestStatus, RequestTracker.
• SaffronLibrary.Prime.Systems.Requests.Interfaces: IRequest, IRequestHandler.
• SaffronLibrary.Prime.Systems.Bus.Requests: RequestBus.

Request

Public sealed class. Derives from Message and implements IRequest. TargetDomain and Params are inherited from Message and are not documented here.

public sealed class Request : Message, IRequest

Properties

public int Id { get; private set; }

The ID assigned by the request system when the request is sent. Read-only from outside the class.

public int Verb { get; }

What the request asks for, as a domain-specific verb.

public Message Payload { get; }

The message the receiving system acts on if it accepts, usually a command.

Constructor

public Request(Domain targetDomain, int verb, Message payload = null, Action<Response> onResponse = null)

Creates a request for the given domain and verb, wrapping the given payload. onResponse is optional and runs when the receiving system replies.

Internal members

internal void SetId(int requestId)

Assigns the request's ID. Called by RequestTracker.Track.

internal Action<Response> GetResponseCallback()

Returns the response callback, or null if none was given. Called by RequestDispatcher.Reply.

RequestDispatcher

Public class. The entry point of the request system.

public class RequestDispatcher

Methods

public void Register(Domain domain, Action<IRequest> handler)

Registers or replaces the handler for a domain. Requests queued for that domain are released.

public void Unregister(Domain domain)

Removes the handler registered for a domain.

public void Ask(Request request)

Assigns the request an ID, tracks it until answered, and routes it to the handler for its target domain.

public void Reply(Response response)

Finds the pending request that the response answers, stops tracking it, and invokes its response callback. Logs a warning if no pending request has the response's ID.

RequestStatus

Public enum. Outcome of a request, decided by the receiving system.

public enum RequestStatus
{
    Accepted = 0,
    Rejected = 1
}

• Accepted: the receiving system accepted the request and is carrying it out.
• Rejected: the receiving system refused the request. The response's reason explains why.

IRequest

Public interface. A request sent to the system that owns its target domain.

public interface IRequest
{
    int Id { get; }
    Domain TargetDomain { get; }
    int Verb { get; }
    Params Params { get; }
    Message Payload { get; }
}

• Id: the ID assigned when the request was sent. The response carries the same ID.
• TargetDomain: the domain the request is sent to. The request bus routes by this value.
• Verb: what the request asks for, as a domain-specific verb.
• Params: extra data for the receiving system, stored as typed params.
• Payload: the message the receiving system acts on if it accepts.

IRequestHandler

Public interface. Implemented by systems that receive requests for their domain.

public interface IRequestHandler
{
    void HandleRequest(IRequest req);
}

Handles a request sent to the system's domain. The handler answers by calling RequestDispatcher.Reply with an accepted or rejected Response.

Response

Public class. The answer a receiving system sends back for a request. Created only through the static factory methods below.

public class Response

Static methods

public static Response Accepted(IRequest request)

Creates a response accepting the given request.

public static Response Rejected(IRequest request, string reason)

Creates a response rejecting the given request, with the reason.

Instance methods

public int GetRequestId()

Returns the ID of the request this response answers.

public RequestStatus GetRequestStatus()

Returns whether the request was accepted or rejected.

public string GetReason()

Returns why the request was rejected, or null if it was accepted.

Internal members

These types are not public, but they are part of the request system's implementation.

RequestTracker

internal class RequestTracker

public void Track(Request request)

Assigns the request a new ID and stores it until its response arrives.

public bool TryResolve(Response response, out Request request)

Finds and removes the pending request that the response answers. Returns false if no pending request has the response's ID.

RequestBus

internal class RequestBus : MessageBus<IRequest, Domain>

public void Send(IRequest request)

Sends a request to the handler registered for its target domain. Requests for a domain with no handler, or one that is not ready, are queued.

protected override Domain GetRoutingKey(IRequest request)

Returns the TargetDomain of the request.