Chapter 19 Working with Instances

Instances are a way for an application to represent unique objects within a Topic, by specifying one or more key fields that form a unique identifier for the instance. Examples include identifying unique commercial flights within a “Flight Status” Topic or a unique sensor measuring the temperature in a “Temperature” Topic.

Modeling data using instances can provide several benefits to a system, including:

  • An application can represent dynamic behavior of objects that come and go in a system, such as aircraft that may fly within range of a radar system and then fly out of range. See 19.1 Instance States for more details.
  • Many QoS policies are applied per instance. For example, the 47.12 HISTORY QosPolicy depth is applied per instance. This allows an application to specify: “Keep the last N samples for every instance this DataReader receives.” See 19.2.1 QoS Policies that are Applied per Instance for more examples.
  • An application can use DataReader methods such as read_instance() and take_instance() to process all the samples for an instance at once.
  • ContentFilteredTopics are more efficient when filtering instances. Using ContentFilteredTopics in combination with instances is a great way to allow applications to take advantage of writer-side filtering to only subscribe to logical subsets of a Topic by specifying the instances that they are interested in.

Instances are defined by key fields that make up a unique identifier of the object being represented. Key fields are similar to primary keys in a database—each unique combination of key field values represents a unique instance. Key fields are specified using the @key directive, as shown in Chapter 8 DDS Samples, Instances, and Keys.

Table 19.1 Example Keys and Instances

Instance
(object represented in data)

Key
(field/s uniquely identifying object)

Data type

Sample
(update to object)

Commercial flight being tracked

Airline name and flight number, such as:

Airline: "United Airlines"

Flight number: 901

 
@key string airline
@key int16 flight_num
float lat
float long

UA, 901, 37.7749, 122.4194

UA, 901, 37.7748, 122.4195

Sensor that is sending data, such as an individual temperature sensor

Unique identifier of that sensor, such as:

"Floor-08-South"

 
@key string sensor_id
int32 temperature

Floor-08-South, 78

Floor-08-South, 79

Car being monitored

Vehicle identification number (VIN) of the car

 
@key string VIN
float lat
float long

JH4DA9370MS016526, 37.7749, 122.4194

JH4DA9370MS016526, 37.7748, 122.4195

See the following sections:

See also more details on instances from the DataWriter and DataReader perspectives: