Introduction

Class, struct and record can be used as a request. Request name should be a verb that describes the requested action.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson(Object record);

Requests must be immutable, or used as such.

record PrintAsJson_
{
    public readonly Object Record;
}

If request type is class or struct then Hash-equals must be implemented explicitly.

    /// <summary>Request to print record-like object as json-string</summary>
    public class PrintAsJson
    {
        /// <summary>Record to print</summary>
        public readonly object record;

        /// <summary>Create request to print <paramref name="record"/></summary>
        public PrintAsJson(object record) => this.record = record;

        /// <summary>Compare to <paramref name="obj"/></summary>
        public override bool Equals(object? obj) => obj is PrintAsJson casted ? casted.record.Equals(this.record) : false;
        /// <summary>Request specific hashcode</summary>
        public override int GetHashCode() => record.GetHashCode() ^ 213;
    }
}

Hash-equals comparable struct can be used as request. Small stucts are very applicable requests, because they can be created without heap-allocation.

/// <summary>Request to print record-like object as json-string</summary>
public struct PrintAsJson
{
    /// <summary>Record to print</summary>
    public readonly object record;

    /// <summary>Create request to print <paramref name="record"/></summary>
    public PrintAsJson(object record) => this.record = record;

    /// <summary>Compare to <paramref name="obj"/></summary>
    public override bool Equals(object? obj) => obj is PrintAsJson casted ? casted.record.Equals(this.record) : false;
    /// <summary>Request specific hashcode</summary>
    public override int GetHashCode() => record.GetHashCode() ^ 213;
}

Any value-type can be used for requesting. They are, however, usually suitable only for narrow-purposed services as the type doesn't indicate the requested verb. The verb must be known from the context.

// Handler that doubles value
Action<IQuery<int, int>> h = q => q.Response.SetValue(q.Request * 2);
// Create service
IService<int, int> doubleService = Services.Create<int, int>(h);
// Double value
int x = doubleService.GetRequired(10);

[IgnoreDataMember] indicates that field or property shouls not be considered as field of request.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson : IRequestNotToBeCached
{
    /// <summary></summary>
    public object Record { get; init; }
    /// <summary>Print info</summary>
    [IgnoreDataMember]
    public String Info => $"Prints {Record} as json.";
}

[DataMember] instructs explicit order and name.

public record MyRequest : IRequestNotToBeCached
{
    [DataMember(Name = "FieldName", Order = 1)]
    public String SomeField { get; init; }

    [DataMember(Name = "FieldName2", Order = 2)]
    public object AnotherField { get; init; }
}

IRequestFor<T>

IRequestFor<T> indicates result type of the request.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson(Object record) : IRequestFor<string>;

Another way to indicate with property IRequestForType.ResultType.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson(Object record) : IRequestForType
{
    Type? IRequestForType.ResultType => typeof(string);
}

IRequestToBeCached

IRequestToBeCached indicates that request is to be cached.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson(Object record) : IRequestToBeCached;

IRequestNotToBeCached indicates that request is not to be cached.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson(Object record) : IRequestNotToBeCached;

IRequestToBeCached

/// <summary>Indicates that the request is to be cached. Requires <see cref="CachePolicies.Default"/>, <see cref="CachePolicies.DefaultYes"/> or <see cref="CachePolicies.UseInterface"/>.</summary>
public interface IRequestToBeCached : IRequest { }

IRequestNotToBeCached

/// <summary>Indicates that the request is not to be cached. Requires <see cref="CachePolicies.Default"/>, <see cref="CachePolicies.DefaultYes"/> or <see cref="CachePolicies.UseInterface"/>.</summary>
public interface IRequestNotToBeCached : IRequest { }

IRequestToBeDisposed

IRequestToBeDisposed indicates that the result object from this request is to be disposed along service or its cache. Note that, this is however default behaviour with default entry policy, even without the interface.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson(Object record) : IRequestToBeDisposed;

IRequestNotToBeDisposed indicates that the result object from this request is not to be disposed. This overrides the default behaviour.

/// <summary>Request to print record-like object as json-string</summary>
public record PrintAsJson(Object record) : IRequestNotToBeDisposed;

IRequestNotToBeDisposed and IRequestToBeDisposed require that EntryPolicies.Default or EntryPolicies.UseInterface are used, and they are applied with default settings.

IRequestToBeDisposed

/// <summary>Indicates that if the result of this request is cached and is disposable, then it is to be disposed. Requires <see cref="EntryPolicies.Default"/> or <see cref="EntryPolicies.UseInterface"/> entry policy.</summary>
public interface IRequestToBeDisposed : IRequest { }

IRequestNotToBeDisposed

// Copyright (c) Toni Kalajainen 2015-2021
namespace Avalanche.Service
{
    // <IRequestToBeDisposed>
    /// <summary>Indicates that the result of this request is not to be disposed. Requires <see cref="EntryPolicies.Default"/> or <see cref="EntryPolicies.UseInterface"/>.</summary>
    public interface IRequestNotToBeDisposed : IRequest { }
    // </IRequestToBeDisposed>
}

Interfaces

IRequest and its sub-interfaces are optional. They indicate different properties of request type.

IRequest
├── IRequestForType
├── IRequestForT
│   └── IRequestFor<Response>
│       └── IRequestForInvocation
│
├── IRequestToBeDisposed
├── IRequestNotToBeDisposed
├── IRequestToBeCached
└── IRequestNotToBeCached

IRequest

/// <summary>
/// Interface that signals that class is a service requests.
/// 
/// Request implementations must be immutable.
/// 
/// See sub-interfaces:
///     <see cref="IRequestForType"/>
///     <see cref="IRequestFor{Value}"/>
///     <see cref="IRequestInvocation"/>
///     <see cref="IRequestToBeCached"/>
///     <see cref="IRequestNotToBeCached"/>
/// </summary>
public interface IRequest
{
}

IRequestFor

/// <summary>
/// Indicates that there is a specific result type.
/// 
/// The implementing class implements either <see cref="IRequestForType"/> or <see cref="IRequestFor{ResultType}"/>.
/// </summary>
public interface IRequestFor : IRequest { }

/// <summary>Indicates that there is a specific result type.</summary>
public interface IRequestForType : IRequestFor
{
    /// <summary>Get Result Type, if available</summary>
    Type? ResultType { get; }
}

/// <summary>
/// Indicates that there is a specific result type in subinterface <see cref="IRequestFor{ResultType}"/>.
/// 
/// This implementing class implements <see cref="IRequestFor{ResultType}"/>.
/// </summary>
public interface IRequestForT : IRequestFor { }

/// <summary>Indicates expected result type.</summary>
/// <typeparam name="ResultType"></typeparam>
public interface IRequestFor<out ResultType> : IRequest, IRequestForT { }

/// <summary>Request to invocate action. </summary>
public interface IRequestInvocation : IRequestFor<Avalanche.Void> { }

Full Example

Full example

using System;
using System.Runtime.Serialization;
using Avalanche.Service;

public class request_index
{
    public static void Run()
    {
        {
            // <5>
            // Handler that doubles value
            Action<IQuery<int, int>> h = q => q.Response.SetValue(q.Request * 2);
            // Create service
            IService<int, int> doubleService = Services.Create<int, int>(h);
            // Double value
            int x = doubleService.GetRequired(10);
            // </5>
        }
        

    }

    static class _1
    {
        // <1>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson(Object record);
        // </1>
    }


    // <2>
    record PrintAsJson_
    {
        public readonly Object Record;
    }
    // </2>

    static class _3
    {
        // <3>
        /// <summary>Request to print record-like object as json-string</summary>
        public class PrintAsJson
        {
            /// <summary>Record to print</summary>
            public readonly object record;

            /// <summary>Create request to print <paramref name="record"/></summary>
            public PrintAsJson(object record) => this.record = record;

            /// <summary>Compare to <paramref name="obj"/></summary>
            public override bool Equals(object? obj) => obj is PrintAsJson casted ? casted.record.Equals(this.record) : false;
            /// <summary>Request specific hashcode</summary>
            public override int GetHashCode() => record.GetHashCode() ^ 213;
        }
    }
    // </3>

    static class _4
    {
        // <4>
        /// <summary>Request to print record-like object as json-string</summary>
        public struct PrintAsJson
        {
            /// <summary>Record to print</summary>
            public readonly object record;

            /// <summary>Create request to print <paramref name="record"/></summary>
            public PrintAsJson(object record) => this.record = record;

            /// <summary>Compare to <paramref name="obj"/></summary>
            public override bool Equals(object? obj) => obj is PrintAsJson casted ? casted.record.Equals(this.record) : false;
            /// <summary>Request specific hashcode</summary>
            public override int GetHashCode() => record.GetHashCode() ^ 213;
        }
        // </4>
    }


    static class _6
    {
        // <6>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson : IRequestNotToBeCached
        {
            /// <summary></summary>
            public object Record { get; init; }
            /// <summary>Print info</summary>
            [IgnoreDataMember]
            public String Info => $"Prints {Record} as json.";
        }
        // </6>
    }

    static class _7
    {
        // <7>
        public record MyRequest : IRequestNotToBeCached
        {
            [DataMember(Name = "FieldName", Order = 1)]
            public String SomeField { get; init; }

            [DataMember(Name = "FieldName2", Order = 2)]
            public object AnotherField { get; init; }
        }
        // </7>
    }

    static class _11
    {
        // <11>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson(Object record) : IRequestFor<string>;
        // </11>
    }
    static class _12
    {
        // <12>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson(Object record) : IRequestForType
        {
            Type? IRequestForType.ResultType => typeof(string);
        }
        // </12>
    }

    static class _21
    {
        // <21>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson(Object record) : IRequestToBeCached;
        // </21>
    }

    static class _22
    {
        // <22>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson(Object record) : IRequestNotToBeCached;
        // </22>
    }
    
    static class _31
    {
        // <31>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson(Object record) : IRequestToBeDisposed;
        // </31>
    }

    static class _32
    {
        // <32>
        /// <summary>Request to print record-like object as json-string</summary>
        public record PrintAsJson(Object record) : IRequestNotToBeDisposed;
        // </32>
    }


}