|
|
||
|
The following example is an extract from the calculator server that accepts the message from the client and computes the sum and difference of two numbers provided in the message payload. The message handler needs to be registered in the server-side agent so that incoming messages can be properly routed to it.
with YAMI.Incoming_Messages; use YAMI.Incoming_Messages;
with YAMI.Parameters; use YAMI.Parameters;
-- ...
type Calculator_Message_Handler is
new Message_Handler with null record;
overriding
procedure Call
(H : in out Calculator_Message_Handler;
Message : in out Incoming_Message'Class) is
procedure Process
(Content : in out Parameters_Collection) is
A : YAMI_Integer;
B : YAMI_Integer;
Reply_Params : Parameters_Collection := Make_Parameters;
begin
A := Content.Get_Integer ("a");
B := Content.Get_Integer ("b");
Reply_Params.Set_Integer ("sum", A + B);
Reply_Params.Set_Integer ("difference", A - B);
Message.Reply (Reply_Params);
end Process;
begin
Message.Process_Content (Process'Access);
end Call;
In the above example the Call operation is a callback implementation that is invoked by the agent whenever there is an incoming message addressed to the logical object for which the handler was registered.
The Message parameter of this operation is an object that refers to internal agent's structures and that allows to initiate further communication that is needed to send the reply or rejection to the originating client program.
Several operations can be executed on this message object and in this example a local procedure is used to inspect the parameters object that was received as part of this message's payload.
Within the local Process procedure the Content parameters object is inspected and the reply is prepared based on the incoming parameters - in this example the server reads two values and computes their sum and difference and inserts both result values into a single parameters object that becomes the reply payload.
After the Reply operation is called on the incoming message object, the processing is completed and the agent can proceed with transmission of the reply to the client.
The above pattern is the most fundamental idiom for server-side processing of incoming messages and can be characterized by the fact that the complete message processing is contained in the scope of the Call callback invocation.
It is also possible to move the state of incoming message to another freshly created incoming message instance with the help of the Move operation. This allows the server to process the incoming message asynchronously and outside of the handler callback.