Class Message

Base class for all messages that are executed by the agents.

Inheritance

Object

Message

ExceptionMessage

InitializeMessage

MessageDecorator

MessagesAggregated<T>

Implements

IDisposable

Namespace: Agents.Net

Assembly: Agents.Net.dll

Syntax

public abstract class Message : IEquatable<Message>, IDisposable

Remarks

Each message knows its predecessors. Predecessors are the messages, that led to this message.

Self disposing: The message is self disposing. The message board sets the number of uses of the message equal to the number of consuming agents. Whenever an agent executed the message the Agent base class marks the message as used. Once the message is completely used up it calls the Dispose() method. The message containers MessageCollector<T1, T2> and MessageAggregator<T> do delay the disposal until the container is executed.

Currently there is a memory leak because the predecessors are strongly referenced. Therefore all messages produced by the system are kept in memory. See https://github.com/agents-net/agents.net/issues/75 for more information and timeline.

Constructors

Message(Message)

Initializes a new instances of this class with a single predecessor message.

Declaration

protected Message(Message predecessorMessage)

Parameters

Type	Name	Description
Message	predecessorMessage	The predecessor message that led to this message.

Message(IEnumerable<Message>)

Initializes a new instances of this class with multiple predecessor messages.

Declaration

protected Message(IEnumerable<Message> predecessorMessages)

Parameters

Type	Name	Description
IEnumerable<Message>	predecessorMessages	The predecessor messages that led to this message.

Properties

Id

The id of the agent.

Declaration

public Guid Id { get; }

Property Value

Type	Description
Guid

Remarks

The id is only used for logging.

MessageDomain

The message domain in which the message was created.

Declaration

public MessageDomain MessageDomain { get; }

Property Value

Type	Description
MessageDomain

Remarks

For more information about message domains see MessageDomain.

Methods

DataToString()

The method which should be overriden to provide a string representation of the carried data.

Declaration

protected abstract string DataToString()

Returns

Type	Description
String	The string representation.

Remarks

If used, it should provide a short string as it is logged multiple times. To much data would slow down the application.

DelayDispose()

This delays the self disposal of the message until the returned object is disposed.

Declaration

public IDisposable DelayDispose()

Returns

Type	Description
IDisposable	The object which will release the message on dispose.

Remarks

This method should only be used, if there is a custom message container that stores this message.

This regards the self disposing mechanism of the message. See the description for the type Message.

Dispose()

Declaration

public void Dispose()

Dispose(Boolean)

Dispose any resources that are stored in the message.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
Boolean	disposing	If true it was called from the Dispose() method.

Equals(Message)

Declaration

public bool Equals(Message other)

Parameters

Type	Name	Description
Message	other

Returns

Type	Description
Boolean

Equals(Object)

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj

Returns

Type	Description
Boolean

Get<T>()

Looks for the specified message type and returns it.

Declaration

public T Get<T>()
    where T : Message

Returns

Type	Description
T	The message of the specified type or null if it was not found.

Type Parameters

Name	Description
T	The message type that needs to be searched.

Remarks

This method is necessary because there can be a hierarchy of messages. In this case the whole stack needs to be searched for the message.

Examples

protected override void ExecuteCore(Message messageData)
{
    //This will not work if the message is decorated
    SpecificMessage message = (SpecificMessage)messageData;

    //This will work either way
    SpecificMessage message = messageData.Get<SpecificMessage>();
}

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32

Is<T>()

Checks whether this message is the specified type.

Declaration

public bool Is<T>()
    where T : Message

Returns

Type	Description
Boolean	true, if this message is of the specified type.

Type Parameters

Name	Description
T	The message type that needs to be searched.

Remarks

This method is necessary because there can be a hierarchy of messages. In this case the whole stack needs to be searched for the message.

ReplaceWith(Message)

Replace this message with the given message.

Declaration

public void ReplaceWith(Message message)

Parameters

Type	Name	Description
Message	message	The message which replaces this message.

Remarks

This method is intended of the use case, that an InterceptorAgent wants to replace a, message with a different message. How to do this see the example.

Examples

This example shows the use case how to replace a message using an InterceptorAgent

protected override InterceptionAction InterceptCore(Message messageData)
{
    Message replacingMessage = GenerateNewMessage();
    messageData.ReplaceWith(replacingMessage);
    OnMessage(replacingMessage);
    return InterceptionAction.DoNotPublish;
}

SetChild(Message)

this is an internal method used by the MessageDecorator. It should not be used outside of that.

Declaration

protected void SetChild(Message childMessage)

Parameters

Type	Name	Description
Message	childMessage	The new child message.

ToMessageLog()

This is used to log the message. It creates the serializable class MessageLog.

Declaration

public MessageLog ToMessageLog()

Returns

Type	Description
MessageLog	The MessageLog instance.

Remarks

This method is mostly used internally.

ToString()

Declaration

public override string ToString()

Returns

Type	Description
String

TryGet<T>(out T)

Tries to looks for the specified message type and returns it.

Declaration

public bool TryGet<T>(out T result)
    where T : Message

Parameters

Type	Name	Description
T	result	The message of the specified type.

Returns

Type	Description
Boolean	true, if the message was found; otherwise false.

Type Parameters

Name	Description
T	The message type that needs to be searched.

Remarks

This method is necessary because there can be a hierarchy of messages. In this case the whole stack needs to be searched for the message.

Examples

protected override void ExecuteCore(Message messageData)
{
    //This will not execute if the message was decorated
    if(messageData is SpecificMessage message)
    {
        //...
    }

    //This will work either way
    if(messageData.TryGet(out SpecificMessage message))
    {
        //...
    }
}

Operators

Equality(Message, Message)

Determines whether both messages are equal or not.

Declaration

public static bool operator ==(Message left, Message right)

Parameters

Type	Name	Description
Message	left	The left message
Message	right	The right message

Returns

Type	Description
Boolean	true, if both messages are equal; otherwise false.

Inequality(Message, Message)

Determines whether both messages are not equal or not.

Declaration

public static bool operator !=(Message left, Message right)

Parameters

Type	Name	Description
Message	left	The left message
Message	right	The right message

Returns

Type	Description
Boolean	true, if both messages are not equal; otherwise false.

Implements

IDisposable