DynamicData Semantics
The purpose of this document is to record the semantics for DynamicData implementations (DynamicDataImpl
and DynamicDataAdapter
) based on what the spec contains and what makes sense for users.
DynamicData should behave like the generated code for the same type to the extent possible. The behavior of DynamicData should be the same for both the writing and reading side. Within the confines of the spec, DynamicData should follow the principle of least surprise and other good design principles.
The behavior described below assumes that the input to each function is valid, including conditions such as the member id being valid, the index being valid, the name being valid, etc..
This method always returns DDS::RETCODE_OK
. If the corresponding member has not been set, then the default value is returned.
This method always returns DDS::RETCODE_OK
. A subsequent get must return the value of the most recent set.
This method always returns DDS::RETCODE_OK
. Modifications of the returned value must be reflected in the DynamicData.
This method always returns DDS::RETCODE_OK
. A subsequent get must return the value of the most recent set.
Section 7.5.2.11.3 in the spec defines the clear operation. In general, values are reset to a default value or removed from a dynamic collection.
This method returns DDS::RETCODE_OK
if the member is present, i.e., has been set. Otherwise, this method returns DDS::RETCODE_NO_DATA
. The implementation does not need to initialize the return value to the default.
The method always returns DDS::RETCODE_OK
. It marks the member as being present and stores the value so that a subsequent get returns DDS::RETCODE_OK
and the stored value.
This method returns DDS::RETCODE_OK
if the member is present, i.e., has been set. Otherwise, this method returns DDS::RETCODE_NO_DATA
. The implementation does not need to initialize the return value to the default.
This method always returns DDS::RETCODE_OK
. A subsequent get must return the value of the most recent set.
Section 7.5.2.11.3 in the spec defines the clear operation.
The general approach is to make unions work like their C++ counterparts.
Setting a branch member should return DDS::RETCODE_OK
and set the discriminator to an appropriate value.
Getting the selected branch member works as follows:
If the member is not optional, get returns DDS::RETCODE_OK
and the value or the default.
If the member is optional, get returns DDS::RETCODE_NO_DATA
if the member has not been set or DDS::RETCODE_OK
if the member has been set.
Getting a member that is not the currently selected branch returns DDS::RETCODE_PRECONDITION_NOT_MET
.
Getting the discriminator should return DDS::RETCODE_OK
and the most recent set value or the default value.
Setting the discriminator will return DDS::RETCODE_OK
if the value corresponds to the selected branch. If the value does not correspond to the selected branch, then setting the discriminator returns DDS::RETCODE_PRECONDITION_NOT_MET
.
The XTypes Spec defines a default value for the discriminator and the branch that it selects if it selects one.
Dynamic Collection (sequence, map) members are treated as optional members. Thus, a get for a member that has not been added returns DDS::RETCODE_NO_DATA
. A "set" for a member that's not yet present in a map will add it. A "set" for a value that's not yet in a sequence adds it if its index is seq.length. The semantics for clearing a member are described in Section 7.5.2.11.3.
Strings can be treated as a sequence of characters.