Entity Use Cases
[Programming How-To's]

Working with entities. More...

Enabling an entity

• To enable an com.rti.dds.infrastructure.Entity

          try {
              entity.enable();
          } catch (RETCODE_ERROR err) {
              System.out.println(
                  "*** Error: failed to enable entity");
          }
  

Checking if a status changed on an entity.

• Given an com.rti.dds.infrastructure.Entity and a com.rti.dds.infrastructure.StatusKind to check for, get the list of statuses that have changed since the last time they were respectively cleared.

          int status_changes_list = entity.get_status_changes(); 
  

• Check if status_kind was changed since the last time it was cleared. A plain communication status change is cleared when the status is read using the entity's get_<plain communication status>() method. A read communication status change is cleared when the data is taken from the middleware via a TDataReader_take() call [see Changes in Status for details].

          if ((status_changes_list & status_kind) != 0) {
              return true;  /* ... YES, status_kind changed ... */
          } else {
              return false;  /* ... NO, status_kind did NOT change ... */
          }        
  

Changing the QoS for an entity

The QoS for an entity can be specified at the entity creation time. Once an entity has been created, its QoS can be manipulated as follows.

• Get an entity's QoS settings using get_qos (abstract)

          try {
              entity.get_qos(qos);
          } catch (RETCODE_ERROR err) {
              System.out.println("***Error: failed to get qos\n");
          }    
  

• Change the desired qos policy fields

          /* Change the desired qos policies */
          /* qos.policy.field = ... */
  

• Set the qos using set_qos (abstract).

          try {
              entity.set_qos(qos);
          } catch (RETCODE_IMMUTABLE_POLICY immutable) {
              System.out.println(
                      "***Error: tried changing a policy that can only be" +
                      "          set at entity creation time\n");
          } catch (RETCODE_INCONSISTENT_POLICY inconsistent) {
              System.out.println(
                      "***Error: tried changing a policy to a value inconsistent" +
                      "          with other policy settings\n");
          } catch (RETCODE_ERROR other) {
              System.out.println(
                      "***Error: tried changing a policy that can only be" +
                      "          set at entity creation time\n");                   
          }   
  

Changing the listener and enabling/disabling statuses associated with it

The listener for an entity can be specified at the entity creation time. By default the listener is enabled for all the statuses supported by the entity.

Once an entity has been created, its listener and/or the statuses for which it is enabled can be manipulated as follows.

• User defines entity listener methods

          /* ... methods defined by EntityListener ... */
          public class MyEntityListener implements Listener {
              // ... methods defined by EntityListener ...
          }  
  

• Get an entity's listener using get_listener (abstract)

          entity_listener = entity.get_listener();    
  

• Enable status_kind for the listener

          enabled_status_list |= status_kind;
  

• Disable status_kind for the listener

          enabled_status_list &= ~status_kind;
  

• Set an entity's listener to entity_listener using set_listener (abstract). Only enable the listener for the statuses specified by the enabled_status_list.

            try {         
                entity.set_listener(entity_listener, enabled_status_list); 
            } catch (RETCODE_ERROR err) {
                // respond to failure
            }  
  

Enabling/Disabling statuses associated with a status condition

Upon entity creation, by default, all the statuses are enabled for the DDS_StatusCondition associated with the entity.

Once an entity has been created, the list of statuses for which the DDS_StatusCondition is triggered can be manipulated as follows.

• Given an entity, a status_kind, and the associated status_condition:

          statuscondition = entity.get_statuscondition();    
  

• Get the list of statuses enabled for the status_condition

          enabled_status_list = statuscondition.get_enabled_statuses();     
  

• Check if the given status_kind is enabled for the status_condition

          if ((enabled_status_list & status_kind) > 0) {
              /*... YES, status_kind is enabled ... */
          } else {
              /* ... NO, status_kind is NOT enabled ... */
          }    
  

• Enable status_kind for the status_condition

          try {
              statuscondition.set_enabled_statuses(enabled_status_list | status_kind);
          } catch (RETCODE_ERROR err) {
              // ... check for cause of failure
          }           
  

• Disable status_kind for the status_condition

          try {
              statuscondition.set_enabled_statuses(enabled_status_list & ~status_kind);
          } catch (RETCODE_ERROR err) {
              // ... check for cause of failure
          }