What is in a Message?

A message is composed of several parts, or properties. The most important property is the message data. All parts of a message can be accessed directly with the SmartSockets API. Almost all parts of a message can be specified using the API. With the exception of the message create method, which belongs to the TipcSvc factory class, all methods for working with messages are members of the TipcMsg class. Messages can be created with TipcSvc.createMsg and copied with TipcMsg.clone.

Figure 5 shows an example of the message that you constructed and sent in the previous lesson (Lesson 2: Publish-Subscribe). This message was a standard SmartSockets message type, INFO, and was sent to the /ss/tutorial/lesson2 subject. The data part of the message consisted of a single string field containing the string "Hello World!".

There are SmartSockets methods to get (access) and set (write) each part of the message.

A message is composed of several properties. The SmartSockets Java Class Library methods for setting and getting the message property are enclosed in parentheses.


Type	is the kind of message being manipulated (TipcMsg.setType, TipcMsg.getType).
Sender	is the name of the originator of a message (TipcMsg.setSender, TipcMsg.getSender). SmartSockets automatically fills this in for you when using RTserver to deliver the message.
Destination	is the name of the subject where a message is going (TipcMsg.setDest, TipcMsg.getDest).
Priority	is the level of importance of a message (TipcMsg.setPriority, TipcMsg.getPriority).
Delivery Mode	is the level of guarantee when a message is sent through a connection (TipcMsg.setDeliveryMode, TipcMsg.getDeliveryMode).
Delivery Timeout	is the number of seconds specifying how long to wait for acknowledgment of delivery of a message sent through a connection (TipcMsg.setDeliveryTimeout, TipcMsg.getDeliveryTimeout).
Load Balancing Mode	is the method of delivery for publish-subscribe operations, which allows a message to be delivered to one or to all subscribing RTclients (TipcMsg.setLbMode, TipcMsg.getLbMode).
Header String Encode	controls whether or not header strings are converted to four-byte integers when a message is sent through a connection. This field cannot be directly accessed by Java clients.
Reference Count	is the number of independent references to a message. This field cannot be directly accessed by Java clients.
Sequence Number	uniquely identifies a message for guaranteed message delivery (TipcMsg.getSeqNum). SmartSockets assigns this number and it cannot be manually set.
User-defined Property	is a user-defined value that can be used for any purpose (TipcMsg.setUserProp, TipcMsg.getUserProp). This field is not used internally by SmartSockets.
Read Only	controls whether or not a message can be modified (TipcMsg.getReadOnly). SmartSockets automatically sets this property and it cannot be manually set.
Data	is the instructions or value part of a message (TipcMsg.append, TipcMsg.next).

There are a large number of SmartSockets methods to build the data part of a message (TipcMsg.append*) and access the data part of a message (TipcMsg.next*). See the online Java documentation for a complete description of these methods.

Figure 6 shows an example of a more complex message. It is a SmartSockets standard NUMERIC_DATA message, and the data part of this message is a series of variable name-value pairs (voltage = 33.4534, switch_pos = 0). You construct a message similar to this one later in this lesson.

What is Automatic Data Translation?

One of the key features of SmartSockets is that it has structured messages. There is no need for you to figure out how to encode your messages. SmartSockets takes care of that for you and provides robust methods that allow you access to any part of the structure of a message. Because the messages are structured, SmartSockets knows how to automatically convert different data types when delivering the message across a heterogeneous network. This is all done transparently for you, using a receiver-makes-right approach in which the final receiver of the message does the translation. This is most efficient, as data translation is only done once.

Many other messaging products do not have the concept of a structured message type. They simply move a block of memory across the network. There is no API to help build and access the different fields of the message, and there is no automatic conversion of data. They leave these tasks up to you, increasing the amount of time it takes to build your application.