1. Declaration Management
1. Introduction

This chapter introduces the RTIambassador service and FederateAmbassador callback methods that support declaration management. Declaration management includes publication, subscription and supporting control functions. Federates that produce objects (or object parts) or that produce interactions must declare exactly what they are able to publish (i.e., generate). Federates that consume objects (or object parts) or that consume interactions must declare their subscription interests.

The RTI keeps track of what participating federates can produce and what they are interested in consuming and sends control signals to throttle what is produced based on consumer interest. As depicted in Figure 7-1, the RTI uses control signals to inform producers exactly what they should transmit. The goal is to keep traffic off the communications network.



Figure 7-1. Control Signal Schema

2. Object Vocabulary Review

It's worth a moment to review some basic HLA terminology.

Object classes are comprised of attributes. Object classes describe types of things that can persist. For example, "tank" might be an object class. Objects of type "tank" have certain attributes (e.g., size, weight, and range). Actual, real tanks are instances of the object class tank. The term "object" standing alone is sometimes used to describe an instance of a particular object class, but sometimes refers to the type information. Object classes may be related to cookie cutters and object instances to the cookies produced using the cookie cutters.

Interaction classes are comprised of parameters. Interaction classes describe types of events. Interaction instances are specific events. It's fair to say, "Objects are similar to interactions in so much as objects are comprised of attributes and interactions are comprised of parameters." The HLA recognizes this inherent symmetry and leverages it when appropriate. The primary difference between objects and interactions is persistence. Objects persist, interactions do not.

Would a missile be described by an object class or an interaction class? The answer depends on the simulation and the persistence of missile instances. A simulation that focuses on missile launchers and their targets may perceive missiles (or missile launches) as events. The launcher fires a missile, which effects some damage. The time that the missile is in the air may be trivial with respect to the simulation. Here, the missile could be modeled as an interaction – possibly between the launcher and the target. Another simulation may focus on the in-flight characteristics of missiles. The fact that the missile launches or impacts may be incidental. Here, the missile persists and should be modeled as an object.

3. Object Hierarchies

Figure 7-2 illustrates a class hierarchy and accompanying Venn diagram. Object classes and interaction classes can be constructed hierarchically. For example, assume that objects of type W are comprised of the attributes "a," "b," "c," and "d" – abbreviated "{a, b, c, d}." It is possible to define object classes that extend object class W. Object class W is extended to produce the object classes X and Z. Object class X is further extended to produce the object class Y.



Figure 7-2. Class Hierarchy – Venn Diagram

Object-oriented programming enthusiasts will recognize such hierarchical representations. Various communities use different phrases to describe object hierarchies. Some examples include:

X extends W. W is a base type. X is derived from W. Y is a descendant of W. W is the parent of Z.

Y inherits from X. W is an ancestor of Z. X is a child of W. Y and Z are leaf objects.

The basic idea is that when an object class is extended to produce a new object class, the new object class contains all the attributes of the class being extended and possibly more. The object diagram and Venn diagram (Figure 7-2) illustrate the relationship between the object classes W, X, Y, and Z. Object class W has the four attributes {a, b, c, d}, class X adds the attributes {e, f, g} so instances of class X have attributes {a, b, c, d, e, f, g}.

4. Publishing and Subscribing Objects

Each federate must publish the object classes and interaction classes it plans to produce. It is possible for a federate to publish a subset of the available attributes for a given class.

1. Object Publication

The object class Y contains the attributes {a, b, c, d, e, f, g, h}. A federate can create instances of object class Y, without specifying all of the attributes associated with Y. For example, Y might be a particular kind of aircraft. A given federate may know some information about aircraft instances (e.g., position information), but rely on other federates to "fill in" the missing pieces (e.g., intelligence about the aircraft). In such a case, the federate would indicate that it can publish particular attributes associated with Y. In Figure 7-3, Federate #1 indicates that it can publish attributes {b, e, f, g, h} for object class Y.

Each federate must indicate explicitly which attributes it can produce (i.e., introduce or update) on a per class basis. Multiple federates may be able to publish Y instances. Federate #3 might publish all of the attributes associated with object class Y. Federate #7 may be able to publish attributes {a, c, f} for Y.

An implicit attribute, known by the name "privilegeToDelete," is included whenever a publication capability is registered for an object class. Only the federate that created a particular object instance is allowed to delete the instance unless the privilege to delete is conveyed to another Federate. Chapter 9, Ownership Management, explores the ability to exchange attribute update and object deletion responsibility among federates.



Figure 7-3. Object Publishing

A federate must explicitly state every object class it intends to produce via the RTIambassador's publishObjectClass() method. A separate call to publishObjectClass() is required for every object class including objects that appear in class hierarchies. If Federate #9 wishes to produce instances of object classes W, X, Y, and Z, it must say so explicitly using four publication calls.

2. Interaction Publication

As with object classes, each federate must state explicitly which interaction classes it intends to produce using the publishInteractionClass() method. Interactions are produced as "all or nothing." It isn't possible to specify which parameters in an interaction will be published. If a federate indicates that it intends to publish an interaction, it should be capable of specifying all parameters associated with the interaction.

3. Object Subscription

Whenever a federate expresses a subscription interest in a particular object class, the RTI presumes that the federate is interested in instances of the descendant classes as well. A federate subscribing to class W would see external instances of classes X, Y, and Z as instances of class W. This can be a useful tool. Class W might represent all aircraft. Class X might represent military aircraft, while class Y represents commercial aircraft. A federate may wish to know about all aircraft, but not care about the details – including the military v. commercial designation.

A federate can subscribe to multiple classes in a class hierarchy. If a federate subscribed to class W and X, the following would be true:

• Instances of object class W would be seen without promotion.

1. Interaction Subscription

As with object classes, each federate subscribes to the interaction classes it wishes to receive. It is not possible to subscribe to individual parameters of an interaction class. Again, interactions are "all or nothing." As with object classes, a federate is informed about a new interaction instance if (a) the federate has subscribed to the interaction class of the instance or (b) the instance can be promoted (i.e., up the hierarchy) to a subscribed interaction class. When an interaction instance is promoted, only the parameters of the subscribed class are presented to the receiving federate.

2. Control Signals

In Figure 7-3, above, Federate #1 indicated that it was capable of producing Y instances, but could only provide the attributes {b, e, f, g, h}. In that same figure, Federate #2 subscribes to attributes {a, b, c, d, e} for object class X. The Y instances produced by Federate #1 are discovered as X instances by Federate #2.

1. Object Publication and Subscription

1. Throttling Publications

The LRC signals a federate to start or stop registering object instances for all published object classes and generating interactions for all published interaction classes.

2. FoodFight Object Declaration

The following code excerpts demonstrate publication and subscription to the object class "Student" which has attributes "LunchMoney," "Cleanliness," and "AmmoAmount." The class name and attribute names would appear in the FED file. The student object class also has the hidden attribute "privilegeToDelete."

1. Excerpt from Student.h

The following excerpt is taken from the declaration of the C++ class "Student." In this example, a C++ class is used to realize the HLA object class "Student." This is but one possible way of realizing an HLA object class. Information about students could be maintained in a database or a C structure.

1. :
2. class Student
3. {
4. friend ostream& operator<< (ostream&, const Student&);
6. public:
7. // In the following enumeration, ATTRIBUTE_COUNT denotes the end of the
8. // enumeration and is equal to the total number of attributes.
9. enum AttributeNames { PRIVILEGE_TO_DELETE = 0, LUNCH_MONEY,
10. CLEANLINESS, AMMO_AMOUNT, ATTRIBUTE_COUNT };
12. static const char* attribute_names[];
14. // Variables to store class handles.
15. static RTI::ObjectClassHandle class_handle;
17. // Array to store attribute/parameter handles.
18. static RTI::AttributeHandle attributes[];
20. static RTI::AttributeHandleSet* p_all_attribute_vector;
22. static void RegisterObject ();
24. :
25. :
27. // Student Characteristics
28. RTI::ObjectHandle getId () const { return id_self; }
29. double getLunchMoney () const { return lunch_money; }
30. double getCleanliness () const { return cleanliness; }
31. long getAmmoAmount () const { return ammo_amount; }
33. protected:
34. static const int BUY_AMMO_CHANCE;
35. static const double AMMO_COST_MEAN;
36. static const double AMMO_COST_ADJ;
37. static const int ATTEMPT_LAUNCH_CHANCE;
39. RTI::ObjectHandle id_self; // RTI ID by which this student is known.
40. double lunch_money; // Funds for new ammo.
41. double cleanliness; // Food damage the student has sustained.
42. unsigned long ammo_amount; // Launchable food possessed.
44. :
45. };

The static function Student::RegisterObject() will eventually contain the code that registers this federate's publication and subscription requests with regard to the object class Student. To support this static registration process, several static variables are declared. The Student::AttributeNames enumeration provides an identifier for each attribute in the HLA object class Student. The static handle Student::class_handle will contain the LRC's internal representation of the Student object class (type). The static array Student:: attribute_names will hold the string representation of each attribute in Student. The static array Student::attributes will house the LRC's internal handle for each Student attribute. Eventually, the pointer Student::p_all_attribute_vector will identify a free-store allocated attribute handle set containing all the attribute handles we wish to publish and subscribe.

Student.cxx

Definitions for Student static variables are as follows.

46. :
47. const char* Student::attribute_names[Student::ATTRIBUTE_COUNT] = {
48. "privilegeToDelete", "LunchMoney", "Cleanliness", "AmmoAmount" };
50. RTI::ObjectClassHandle Student::class_handle
51. = RTI::ObjectClassHandle(); // Default constructor provides null handle.
53. RTI::AttributeHandle Student::attributes[Student::ATTRIBUTE_COUNT];
55. RTI::AttributeHandleSet* Student::p_all_attribute_vector = 0;
56. :

 

The publish and subscribe registration process is conducted by the static function Student::RegisterObject().

57. void
58. Student::RegisterObject ()
59. {
60. // Abstract
61. // Register the class. Then, register each attribute recording the
62. // corresponding handle in the vector of all attributes (e.g.,
63. // p_all_attribute_vector).
65. const char* object_name = "Student";
66. cout << "Registering '" << object_name << "'." << endl;
68. class_handle = ::rtiAmb.getObjectClassHandle(object_name);
70. if (p_all_attribute_vector) delete p_all_attribute_vector;
72. p_all_attribute_vector
73. = RTI::AttributeHandleSetFactory::create(Student::ATTRIBUTE_COUNT);
75. for (int i = 0; i < ATTRIBUTE_COUNT; i++ )
76. {
77. cout << "\tGetting attribute handle for '" << attribute_names[i]
78. << "'." << endl;
80. RTI::AttributeHandle handle = ::rtiAmb.getAttributeHandle(
81. attribute_names[i],
82. class_handle);
84. // Here, we maintain an array of handles and an attribute vector
85. // that contains all the handles for this class.
86. attributes[i] = handle;
87. p_all_attribute_vector->add(handle);
88. }
90. // Publish and subscribe to all attributes.
91. ::rtiAmb.publishObjectClass(class_handle, *p_all_attribute_vector);
92. ::rtiAmb.subscribeObjectClassAttributes(
93. class_handle,
94. *p_all_attribute_vector);
96. // NB: For now, not bothering to delete p_all_attribute_vector. It will
97. // live as long as the program does.
98. }

RegisterObject() closely follows the interactions identified in Figure 7.4, Object Publication and Subscription.

1. Dynamic Object Publication and Subscription

1. Publishing and Subscribing Interactions

1. class Splat
2. {
3. friend ostream& operator<< (ostream& os, const Splat& splat);
5. public:
6. enum ParameterNames { ENSUING_MESS, TARGET, PARAMETER_COUNT};
8. static const char* parameter_names[];
10. // Variables to store class handles.
11. static RTI::InteractionClassHandle interaction_handle;
13. // Array to store attribute/parameter handles.
14. static RTI::ParameterHandle parameters[];
16. static void RegisterInteraction ();
17. :



Figure 7-5. Declaring Interactions

Splat.cxx

18. const char* Splat::parameter_names[Splat::PARAMETER_COUNT] = {
19. "EnsuingMess", "Target" };
21. RTI::InteractionClassHandle Splat::interaction_handle
22. = RTI::InteractionClassHandle(); // Null handle.
24. RTI::ParameterHandle Splat::parameters[Splat::PARAMETER_COUNT];
25. :
26. :
27. void
28. Splat::RegisterInteraction ()
29. {
30. const char* interaction_name = "Splat";
31. cout << "Registering '" << interaction_name << "'." << endl;
33. // Register the interaction.
34. interaction_handle = ::rtiAmb.getInteractionClassHandle(interaction_name);
36. for (int i = 0; i < PARAMETER_COUNT; i++ )
37. {
38. cout << "\tGetting parameter handle for '" << parameter_names[i]
39. << "'." << endl;
41. parameters[i] = ::rtiAmb.getParameterHandle(
42. parameter_names[i],
43. interaction_handle);
44. }
46. // Publish and subscribe interaction.
47. ::rtiAmb.publishInteractionClass(interaction_handle);
48. ::rtiAmb.subscribeInteractionClass(interaction_handle);
49. }

As with object class declaration, interaction interest can be declared dynamically. Each call to publishInteractionClass() and subscribeInteractionClass() for an interaction class replaces previous calls. The methods unpublishInteractionClass() and unsubscribeInteractionClass() should be called when a federate is no longer interested in an interaction class.