Developing an EMS Client Application : Working with Messages

Working with Messages
Messages are a self-contained units of information used by JMS applications to exchange data or request operations.
Creating Messages
As described in JMS Message Bodies, EMS works with the following types of messages:
There is a separate create method for each type of message.
The following examples show how to create a simple text message containing the string "Hello."
Java
Use the Session object’s createTextMessage() method to create a TextMessage:
   TextMessage message = session.createTextMessage("Hello");
See the tibjmsMsgProducer.java sample client for a working example.
C
Use the tibemsTextMsg_Create function to create a text message of type tibemsTextMsg:
   tibemsTextMsg message = "Hello";
   status = tibemsTextMsg_Create(&message);
See the tibemsMsgProducer.c sample client for a working example.
C#
Use the Session.CreateTextMessage method to create text message of type TextMessage:
   TextMessage message = session.CreateTextMessage("Hello");
See the csMsgProducer.cs sample client for a working example.
Setting and Getting Message Properties
Before a client sends a message, it can use a "set property" method to set the message properties described in EMS Message Properties. The client can check the message properties with a "get property" method.
Java
Use the Message object’s setBooleanProperty() method to set the JMS_TIBCO_PRESERVE_UNDELIVERED property to true:
   message.setBooleanProperty("JMS_TIBCO_PRESERVE_UNDELIVERED",
                               true);
Use the getStringProperty() method to get the user ID of the JMS_TIBCO_SENDER:
   userID = message.getStringProperty("JMS_TIBCO_SENDER");
C
Use the tibemsMsg_SetBooleanProperty function to set the JMS_TIBCO_PRESERVE_UNDELIVERED property to true:
   status = tibemsMsg_SetBooleanProperty(message,
                      "JMS_TIBCO_PRESERVE_UNDELIVERED", true);
Use the tibemsMsg_GetStringProperty function to get the user ID of the JMS_TIBCO_SENDER:
   char* userID = NULL;
   status = tibemsMsg_GetStringProperty(message,
                      "JMS_TIBCO_SENDER", &userID);
C#
Use the Message.SetBooleanProperty method to set the JMS_TIBCO_PRESERVE_UNDELIVERED property to true:
   message.SetBooleanProperty("JMS_TIBCO_PRESERVE_UNDELIVERED",
                            true);
Use the Message.GetStringProperty method to get the user ID of the JMS_TIBCO_SENDER:
   string userID = message.GetStringProperty("JMS_TIBCO_SENDER");
Sending Messages
You can use the Message Producer client, described in Creating a Message Producer, to send messages to a destination. You can either send a message to the destination specified by the Message Producer or, if the Message Producer specifies NULL as the destination, you can send a message to a specific destination. In either case, you can optionally set the JMSDeliveryMode, JMSExpiration, and JMSPriority message header fields described in JMS Message Header Fields when sending each message.
The following examples show two ways to send a text message in each language. The first example sends the message to the Message Producer, QueueSender, created in Creating a Message Producer. The second example uses a Message Producer, NULLsender, that specifies a destination of NULL and sends the message to the topic created in Dynamically Creating Topics and Queues.
See Chapter 2, Messages for more information about creating messages.
Java
Use the MessageProducer object’s send() method to send a message to the destination specified by the MessageProducer object:
   QueueSender.send(message);
Use the following form of the send() method to send a message to a specific destination:
   MessageProducer NULLsender = session.createProducer(null);
   ....
   NULLsender.send(topic, message);
See the tibjmsMsgProducer.java sample client for a working example.
C
Use the tibemsMsgProducer_Send function to send a message to the destination specified by the tibemsMsgProducer:
   status = tibemsMsgProducer_Send(QueueSender, message);
Use the tibemsMsgProducer_SendToDestination function to send the message to a specific destination:
   status = tibemsMsgProducer_SendToDestination(NULLsender,
                                            topic, message);
See the tibemsMsgProducer.c sample client for a working example.
Unlike the Java and C# APIs, in the C API, you can use the tibemsMsgProducer_SendToDestination function to specify the destination regardless of whether a destination is in the tibemsMsgProducer.
C#
Use the MessageProducer.Send method to send a message to the destination specified by the MessageProducer:
   QueueSender.Send(message);
Use the following form of the MessageProducer.Send method to send a message to a specific destination:
   MessageProducer NULLsender = session.CreateProducer(NULL);
   NULLsender.Send(topic, message);
See the csMsgProducer.cs sample client for a working example.
Receiving Messages
The Message Consumer created in Creating a Message Consumer receives messages from a destination and acknowledges the receipt of messages using the acknowledge mode established for the session, as described in Creating a Session.
Before receiving messages, the Message Consumer must start the connection to the EMS server. Before exiting, the Message Consumer must close the connection.
The following examples start the connection created in Connecting to the EMS Server; synchronously receive messages from the queue created in Dynamically Creating Topics and Queues, and then close the connection.
Java
Use the Connection object’s start() method to start the connection:
   connection.start();
Use the MessageConsumer object’s receive() method to receive a message. This is typically used in a loop for the duration the client wishes to receive messages:
   Message message = QueueReceiver.receive();
When the client has finished receiving messages, it uses the Close() method to close the connection:
   connection.close();
See the tibjmsMsgConsumer.java sample client for a working example.
C
Use the tibemsConnection_Start function to start the connection:
   status = tibemsConnection_Start(connection);
Use the tibemsMsgConsumer_Receive function to receive a message. This is typically used in a loop for the duration the client wishes to receive messages:
   tibemsMsg message = NULL;
   status = tibemsMsgConsumer_Receive(QueueReceiver,&message);
When the client has finished receiving messages, use the tibemsConnection_Close function to close the connection:
   status = tibemsConnection_Close(connection);
See the tibemsMsgConsumer.c sample client for a working example.
C#
Use the Connection.Start function to start the connection:
   connection.Start();
Use the MessageConsumer.Receive function to receive a message. This is typically used in a loop for the duration the client wishes to receive messages:
   Message message = QueueReceiver.receive();
When the client has finished receiving messages, use the Connection.Close function to close the connection:
   connection.Close();
See the csMsgConsumer.cs sample client for a working example.