By using the SubscriptionKey QosPolicy, a DataReader can force its own key-list definition on data samples. More...

Inheritance diagram for org.opensplice.dds.core.policy.SubscriptionKeys:

Collaboration diagram for org.opensplice.dds.core.policy.SubscriptionKeys:

Public Member Functions
ServiceEnvironment	getEnvironment ()

Set< String >	getKey ()

SubscriptionKeys	withKey (Collection< String > keyList)
	Copy this policy and override the value of the property. More...

SubscriptionKeys	withKey (String keyList)
	Copy this policy and override the value of the property. More...

SubscriptionKeys	withKey (String... keyList)
	Copy this policy and override the value of the property. More...

Detailed Description

By using the SubscriptionKey QosPolicy, a DataReader can force its own key-list definition on data samples.

The consequences are that the DataReader will internally keep track of instances based on its own key list, instead of the key list dictated by the Topic. Operations that operate on instances or instance handles, such as org.omg.dds.sub.DataReader#lookupInstance(Object) or org.omg.dds.sub.DataReader#getKeyValue(org.omg.dds.core.InstanceHandle) , respect the alternative key-list and work as expected.

However, since the mapping of writer instances to reader instances is no longer trivial (one writer instance may now map to more than one matching reader instance and vice versa), a writer instance will no longer be able to fully determine the lifecycle of its matching reader instance, nor the value its org.omg.dds.sub.ViewState and org.omg.dds.sub.InstanceState.

In fact, by diverting from the conceptual 1 - 1 mapping between writer instance and reader instance, the writer can no longer keep an (empty) reader instance ALIVE by just refusing to unregister its matching writer instance. That means that when a reader takes all samples from a particular reader instance, that reader instance will immediately be removed from the reader's administration. Any subsequent reception of a message with the same keys will re-introduce the instance into the reader administration, setting its view_state back to NEW. Compare this to the default behavior, where the reader instance will be kept alive as long as the writer does not unregister it. That causes the view_state in the reader instance to remain NOT_NEW, even if the reader has consumed all of its samples prior to receiving an update.

Another consequence of allowing an alternative keylist is that events that are communicated by invalid samples (i.e. samples that have only initialized their keyfields) may no longer be interpreted by the reader to avoid situations in which uninitialized non-keyfields are treated as keys in the alternative keylist. This effectively means that all invalid samples (e.g. unregister messages and both implicit and explicit dispose messages) will be skipped and can no longer affect the InstanceState, which will therefore remain ALIVE. The only exceptions to this are the messages that are transmitted explicitly using the org.opensplice.dds.pub.DataWriter#writeDispose(Object) call, which always includes a full and valid sample and can therefore modify the InstanceState to NOT_ALIVE_DISPOSED.

By default, the SubscriptionKey QosPolicy is not used.

This QosPolicy is applicable to a DataReader only, and cannot be changed after the DataReader is enabled.

Definition at line 75 of file SubscriptionKeys.java.

Member Function Documentation

◆ getEnvironment()

ServiceEnvironment org.omg.dds.core.DDSObject.getEnvironment ( )

inherited

Returns: the org.omg.dds.core.ServiceEnvironment object that directly or indirectly was used to create this object.

◆ getKey()

Set<String> org.opensplice.dds.core.policy.SubscriptionKeys.getKey ( )

Returns: an unmodifiable collection of subscription keys.

Implemented in org.opensplice.dds.core.policy.SubscriptionKeysImpl.

◆ withKey() [1/3]

SubscriptionKeys org.opensplice.dds.core.policy.SubscriptionKeys.withKey ( Collection< String > keyList )

Copy this policy and override the value of the property.

Parameters

keyList A collection of strings with one or more names of topic fields acting as alternative keys.

Returns: a new SubscriptionKeys policy

Implemented in org.opensplice.dds.core.policy.SubscriptionKeysImpl.

◆ withKey() [2/3]

SubscriptionKeys org.opensplice.dds.core.policy.SubscriptionKeys.withKey ( String keyList )

Copy this policy and override the value of the property.

Parameters

keyList A strings with one name of topic fields acting as alternative key.

Returns: a new SubscriptionKeys policy

Implemented in org.opensplice.dds.core.policy.SubscriptionKeysImpl.

◆ withKey() [3/3]

SubscriptionKeys org.opensplice.dds.core.policy.SubscriptionKeys.withKey ( String... keyList )

Copy this policy and override the value of the property.

Parameters

keyList An arbitrary number of strings with one or more names of topic fields acting as alternative keys.

Returns: a new SubscriptionKeys policy

Implemented in org.opensplice.dds.core.policy.SubscriptionKeysImpl.

The documentation for this interface was generated from the following file:

java5/common/java/code/org/opensplice/dds/core/policy/SubscriptionKeys.java

Public Member Functions

Detailed Description

Member Function Documentation

◆ getEnvironment()

◆ getKey()

◆ withKey() [1/3]

◆ withKey() [2/3]

◆ withKey() [3/3]