|
|
||
|
The incoming message is an object that encapsulates the information about the message sender, routing and content.
Incoming message objects, as programming language entities, are always created by the agent and are used for the purpose of the callback into the user-provided object implementation. Incoming messages are provided as a parameter to the object callback when the new message is dispatched.
The user code can perform the following actions on the incoming message object:
Both reply and rejection can have assigned the priority attribute, which influences the ordering of frames in the respective communication channel's queue. These operations can be executed only once.
In the simplest scenario, when distinct message handlers are registered for each logical object name, the message is automatically routed to the proper handler based on the destination object name and the user code uses only the message name and its parameters to take decisions on how to process the given request. This scheme naturally reflects the object-based design approach and is used in all examples programs that are provided with the library.
The typical usage of incoming messages is synchronous in the sense that the message is fully handled in the single callback - that is, the message handler interprets the message, executes the requested action and either replies to or rejects the message. This process is complete and once the handler callback returns the control flow to the agent, there is no further interaction with the given message - this is very similar to a regular method invocation in the object-oriented system.
More advanced servers might prefer to process the incoming messages in the asynchronous way and instead of producing the result synchronously, they can take note of the incoming message and immediately return the control flow to the agent without actually completing the processing. The processing can be completed later on, in the server thread and outside of the callback invocation. In order to make this possible the incoming message object can be stored aside, or moved aside, so that there something to interact with (reply to or reject). Special care should be taken with regard to the lifetime of such incoming message objects - if the message is fully handled within the callback invocation initiated by the agent, then it is clear that the incoming message object has a scope that is smaller than that of the agent, whereas by extending the lifetime of the incoming message object outside of the callback, the risk is introduced that further interactions will take place when the agent is already terminated.
Note:
Asynchronous processing of incoming messages is not supported in Python.
In any case, if the callback handler code finishes with an exception, the incoming message is implicitly rejected with the reason description that is derived from the exception that was thrown. In this context the message rejection represents the general inability of the server to provide the requested service and is automatic if the message handler terminates abnormally.
Note:
If the parameters object is provided for the reply, it is completely serialized at the very beginning of the whole process, before the control returns back the user code - this guarantee is similar to the one for message sending. After the incoming message is replied to, there is no further association between the parameters object and the reply and the parameters object can be destroyed or reused without any impact on the transmission even if the response was not yet physically sent.
Note:
It is also possible to ignore the incoming message altogether, without replying to it nor rejecting it. In this case no notification will be sent to the originating agent and the sender will never see any of the ``completion'' statuses. This scenario is natural with one-way messages, but can be surprising with regular messages, so should be used with care.
The following sections present code examples for each programming language.