Messages

Message is a data packet that is passed between agents. Messages can model various objects of the real world. For example, they can represent agents – parts, products, people, trucks, etc., or data packets being passed in a network, or commands and signals in a control system.

Messages are instances of arbitrary Java classes. Usually, a message carries some data. To define such a message, you need to define a Java class with necessary member variables and, may be methods. All Java classes you define in your model can be reused in other models as well.

If you need just to signal an object, there is no need in defining new Java class as you can use an instance of the class Object as a message not carrying any data.

Sending messages

How to send a message?

To send a message, you should simply call the method send() of a port, providing the instance of a message class as a parameter. Defining your own message classes is described in section. If you need to just signal an object, you can send an instance of class Object that does not carry any data by calling the method send() with omitted parameter.

For example, you can type the following line of code in the Startup Code code section of an agent to send a message of Message type via its portA port at the model startup.

portA.send( new Message() );

Defining message sending handler

You can define the message sending handler in the On Send property of the port. This code is executed each time a message is sent. In that code you can use a local variable msg, which is a reference of type Object to a just sent message. If true is returned, the message is processed further as defined by message sending rules. The same happens by default when On Send is left blank. If false is returned or if you write any code and return nothing, the default processing is omitted.

Receiving Messages

To react to a received message, you can choose one of the ways described below.

Defining message reception handler

You can define the message reception handler in the On Receive property of the port. This code is executed each time a message is received. In that code you can use a local variable msg, which is a reference to a just received message. The code may contain return statement returning true or false. If true is returned, the message is forwarded further as defined by message routing rules. The same happens by default when On Receive is left blank. If false is returned or if you write any code and return nothing, the default processing is omitted – i.e., the received message is not forwarded further.

Generating events for a statechart

You can forward the received message to a statechart. Then all messages accepted by the port are placed into the statechart queue as message events.

Message Routing Rules

When you send a message via a port, it is forwarded along all port connections outside the agent this port belongs to.

When a message is received at a port, it is forwarded to all connected statecharts and along all port connections inside the agent this port belongs to.

When a message arrives at a port, it is processed depending on the direction the message is going.

When a message arrives at a statechart, it is received by the statechart and the method receiveMessage() of the statechart is called.

The message routing rules are illustrated on the figure below:


Filtering Messages by Type

Sometimes you may need to filter incoming and/or outcoming messages by message type – i.e., send and receive only messages of the certain type and discard other ones. Message type checking is implemented by specifying the type of messages that are allowed to be sent and received by the port. Those messages that cannot be cast to the specified message type are discarded.

To make a port filter incoming/outcoming messages by type

  1. Select the port in a graphical editor.
  2. Go to the Advanced section of the Properties view.
  3. Specify the type of messages that are allowed to be sent and received by the port in the In message type and Out message type edit boxes correspondingly. Use combo boxes to choose from all known message classes of this model. If you leave Object here, message type checking will not be performed.

Filtering Messages by Contents

Sometimes you may need to filter incoming in a port messages by contents – i.e. accept only messages containing the required information, or matching the specified format, and discard other ones.

In AnyLogic you can easily implement any message contents checking mechanism in the On Receive property of the port. Here you can specify your own contents checking code and ignore or accept the arrived message by writing return false; or return true; statement correspondingly.

To make a port filter incoming messages by contents

  1. For instance, we have a client-server model, where a server processes only valid client requests containing customer name and address. (Request is represented with Java class Request with String fields name and address). We want requests with some of the required fields unfilled to be ignored.
  2. Select the port, whose incoming messages you want to filter by contents.
  3. Specify Request as port's In message type.
  4. >Define message contents checking operations in the On Receive property of the port. In our case your code should look like this:

    if ( msg.name==null || msg.address==null )
    return false;
    else {
    // process the request
    return true;
    }

Note that returning false we prohibit the default processing of the message. Thus received messages will not be forwarded further according to the message routing rules.


Related topics

Message passing

Ports