MicroMessage

chrfrantz edited this page May 16, 2016 · 2 revisions

The MicroMessage is the unified message structure for social interaction in µ². It extends Java's native HashMap implementation and provides numerous setters and getters for predefined fields used by the micro-agent framework. However, the developer is free to define custom fields (using a dedicated setter and getter). The use of the message entries is largely left to the developer.

Message fields and according setters/getters

  • Sender - setSender()/getSender()
    • Specifies the message sender. It is automatically set by the platform upon sending. So in most cases the developer will not need to deal with setting the sender manually. For a recipient the getSender() functionality might be of central concern to figure out the eventual sender. To override the setting of the sender field by the platform (e.g. in case of forwarding messages or any case where the sender field should remain unchanged), set the instance variable sendUnchanged to true (see further information below).
  • Recipient - setRecipient()/getRecipient()
    • Specifies the recipient of a message. If direct addressing is used the developer fills the field himself. In case of dynamic binding this field is automatically filled by the platform.
  • Performative - setPerformative()/getPerformative()
    • Specifies the performative of a message.
  • Content - setContent()/getContent()
    • Specifies potential String content. No further special meaning.
  • Intent - setIntent()/getIntent()
    • Specifies the intent request sent for processing by another agent via dynamic binding.
    • The method containsIntent() indicates if a message contains an intent (without directly retrieving it).
  • Event - setEvent()/getEvent()
    • Specifies an event in a message, be it either for subscription or raising. For event subscription management ensure to use the according agent methods (subscribe()/unsubscribe()/clearSubscriptions()). Events are raised by simply setting an event and sending the message.
    • The method containsEvent() indicates if a message contains an event (without directly retrieving it).
  • ExecutionEnvironment - setExecutionEnvironment()/getExecutionEnvironment()
    • Specifies the execution environment which should receive the message (if useful in an application). Currently this mainly refers to the decision whether to dispatch a message to a Clojure role implementation or a Java role implementation. It is particularly useful if the message (e.g. the content field) holds executable code.
  • ConversationID - setConversationID()/getConversationID()
    • Specifies the conversation ID for a message. This is particularly useful when considering long-running and managed conversations (e.g. by conversation policy)
  • MessageID - setMessageID()/getMessageID()
    • Specifies the message ID in a conversation to keep track of a message order. Similar to the conversation ID the use of the message ID is entirely optional.
  • CustomField - setCustomField()/getCustomField()
    • Specifies a custom field. The application developer can use these methods to implement further fields as the setter both takes key and value for the according field. Extension of a message structure should always be undertaken using this function in order to ensure unified use.

Special methods of the MicroMessage

  • startNewConversation()
    • This helper method resets conversation ID and message ID field. When passing an existing MicroMessage as parameter its fields are copied into the new message (where applicable (e.g. not the conversation ID, ...)).
  • createReply()
    • This helper method returns a MicroMessage instance which is a reply to the instance this method is called on. Operations include the exchange of sender and receiver and incrementing the message ID if applicable
  • getSenderNode()
    • This method returns the node (in case of distributed execution) the message is sent from to allow distinct addressing of a particular agent. (Agent names must be unique on a single platform but can be redundant (at least the short name) across several platform instances.)

Special (boolean) variables of the MicroMessage

  • globalValidation
    • Indicates if MicroMessages should be globally validated using the specified Message Validator.
  • validation
    • Indicates if this particular MicroMessage instance should be validated with the Message Validator. Malformed messages are indicated in console but processed.
  • strictValidation
    • Indicates if the platform should take severe actions upon detecting invalid messages (e.g. stop the system). The actual action is implemented in the according Message Validator.
  • sendUnchanged
    • As mentioned above this indicates that the sender field of the message is not to be changed by the platform upon sending.

Constructors

Apart from the default constructor (MicroMessage()) the MicroMessage class has three further constructors

  • MicroMessage(Intent)
    • Creates a MicroMessage with an intent. It equals an instantiation of the default constructor followed by a setIntent() call.
  • MicroMessage(Event)
    • Creates a MicroMessage with an event. It equals an instantiation of the default constructor followed by a setEvent() call.
  • MicroMessage(Performative)
    • Creates a MicroMessage with a performative. It equals an instantiation of the default constructor followed by a setPerformative() call.

Those constructors allow a significantly less code when using the dynamic binding or event subscription mechanisms.

MicroMessage semantics

In order to be successfully sent MicroMessages at least need to provide either of those:

  • Recipient
  • Intent
  • Event

The sender field is automatically filled by the platform upon sending. If only an intent is provided, the recipient is resolved and the message field in fact filled with this. However, from the sender point of view only the intent is provided. The same is the case for messages only containing an event.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.