Examples of the Use of the Messaging Framework

This section contains a number of simplified examples that illustrate the use of the messaging framework to accomplish common messaging tasks using generic features. In this example, a datagram message is being sent to an existing queue and a reply is not expected.

To send a datagram message

Create an instance of the JadeMessagingFactory class. This class encapsulates the behavior for creating and opening queues.
Create and open a queue by calling the openQueue method on the JadeMessagingFactory instance created in the previous step. The method returns an instance of the JadeGenericQueue class configured for the specified transport.
Create an empty message by calling the createMessage method on the JadeGenericQueue instance created in the previous step. The method returns an instance of the JadeGenericMessage class configured for the specified transport.
Optionally set properties for the message object.
Optionally assign the payload (that is, the content) of the message. The other way of sending information is by setting user properties.
Insert the message in the queue by calling the putMessage method on the JadeGenericQueue instance.

The following example shows a datagram message being sent using the JadeMQ message transport.

vars
    factory : JadeMessagingFactory;
    queue : JadeGenericQueue;
    message : JadeGenericMessage;
begin
    // Step 1 - create the factory object
    create factory transient;
    // Step 2 - create and open the queue
    queue := factory.openQueue("JadeMQ://localnode/MainQ", "MustExist");
    // Step 3 - create the message
    message := queue.createMessage(true);
    // Step 4 - optionally set message properties
    message.type := JadeGenericMessage.Type_Datagram;
    // Step 5 - set message content
    message.body := "Hello World".Binary;
    // Step 6 - insert message in queue
    queue.putMessage(message, "");
epilog
    delete message;
    delete queue; // implicitly closes the queue
    delete factory;
end;

To retrieve a message from an existing queue

Create an instance of the JadeMessagingFactory class. This class encapsulates the behavior for creating and opening queues.
Create and open the queue containing the message, by calling the openQueue method on the JadeMessagingFactory instance created in the previous step. The method returns an instance of the JadeGenericQueue class.
Create an empty message, by calling the createMessage method on the JadeGenericQueue instance created in the previous step. The method returns an instance of the JadeGenericMessage class.
Retrieve the message in the queue, by calling the getMessage method on the JadeGenericQueue instance. The payload of the message can be cast to the type of data it contains.

The following example shows a message being retrieved from a JadeMQ message queue.

vars
    factory : JadeMessagingFactory;
    queue : JadeGenericQueue;
    message : JadeGenericMessage;
begin
    // Step 1 - create the factory object
    create factory transient;
    // Step 2 - create and open the queue
    queue := factory.openQueue("JadeMQ://localnode/MainQ", "MustExist");
    // Step 3 - create a message object
    message := queue.createMessage(false);
    // Step 4 - retrieve a message
    queue.getMessage(message, "");
    write message.body.String;
epilog
    delete message;
    delete queue; // implicitly closes the queue
    delete factory;
end;

To reply to a message

In the example in this section, a message is received that has the replyQueueFullName property set. This property is set to instruct the receiver of the message to send any reply to the specified queue. To assist the sender of the original message in matching the original message with the reply message, the correlationID property of the reply message is set to the messageID property of the original message.

Create and open the reply queue, by calling the openQueue method.
Create an empty message, by calling the createMessage method on the JadeGenericQueue instance created in the previous step. The method returns an instance of the JadeGenericMessage class.
Set properties for the reply message object.
Assign the payload (that is, the content) of the reply.
Insert the reply in the queue, by calling the putMessage method on the JadeGenericQueue instance.

The following code fragment shows a reply message being constructed and sent.

// Step 1 - create and open the reply queue
replyQueue := factory.openQueue(message.replyQueueFullName,"MustExist");
// Step 2 - create the reply message object
reply := replyQueue.createMessage(true);
// Step 3 - set correlationID and message type properties
reply.correlationID := message.messageID;
reply.type := JadeGenericMessage.Type_Reply;
// Step 4 - set reply message payload
reply.appendString("Acknowledging receipt");
// Step 5 - insert reply message in reply queue
replyQueue.putMessage(reply, "");