|
RTI Connext Java API Version 7.4.0
|
com.rti.dds.subscription.TopicQuery and associated elements. More...
Classes | |
| interface | TopicQuery |
| <<extension>> Allows a com.rti.dds.subscription.DataReader to query the sample cache of its matching com.rti.dds.publication.DataWriter. More... | |
| class | TopicQueryData |
| <<extension>> Provides information about a com.rti.dds.subscription.TopicQuery More... | |
| class | TopicQueryHelper |
| Helpers to provide utility operations related to com.rti.dds.subscription.TopicQuery. More... | |
| class | TopicQuerySelection |
| <<extension>> Specifies the data query that defines a com.rti.dds.subscription.TopicQuery More... | |
| class | TopicQuerySelectionKind |
| Kinds of TopicQuerySelection. More... | |
Variables | |
| static final TopicQuerySelection | TOPIC_QUERY_SELECTION_USE_READER_CONTENT_FILTER |
| Special value for creating a com.rti.dds.subscription.TopicQuery that applies the same filter as the DataReader's com.rti.dds.topic.ContentFilteredTopic. More... | |
| static final TopicQuerySelection | TOPIC_QUERY_SELECTION_SELECT_ALL |
| Special value for creating a com.rti.dds.subscription.TopicQuery that selects all the samples in a com.rti.dds.publication.DataWriter cache. More... | |
com.rti.dds.subscription.TopicQuery and associated elements.
TopicQueries allow a com.rti.dds.subscription.DataReader to query the sample cache of its matching com.rti.dds.publication.DataWriter. A user can create a com.rti.dds.subscription.TopicQuery with the com.rti.dds.subscription.DataReader.create_topic_query API. When a DataReader
creates a TopicQuery, DDS will propagate it to other DomainParticipants and their DataWriters. When a DataWriter matching with the DataReader that created the TopicQuery receives it, it will send the cached samples that pass the TopicQuery's filter.
To configure how to dispatch a TopicQuery, the com.rti.dds.publication.DataWriterQos includes the com.rti.dds.infrastructure.TopicQueryDispatchQosPolicy policy. By default, a DataWriter ignores TopicQueries unless they are explicitly enabled using this policy.
The delivery of TopicQuery samples occurs in a separate RTPS channel. This allows DataReaders to receive TopicQuery samples and live samples in parallel. This is a key difference with respect to the Durability QoS policy.
Late-joining DataWriters will also discover existing TopicQueries. To delete a TopicQuery you must use com.rti.dds.subscription.DataReader.delete_topic_query.
After deleting a TopicQuery, new DataWriters won't discover it and existing DataWriters currently publishing cached samples may stop before delivering all of them.
By default, a TopicQuery queries the samples that were in the DataWriter's queue at the time the DataWriter received the TopicQuery. These TopicQueries are snapshot TopicQueries. However, a TopicQuery can be created in "continuous" mode; in this case, a DataWriter will continue delivering samples that pass a continuous TopicQuery filter until the DataReader application explicitly deletes it. These TopicQueries are continuous TopicQueries.
The samples received in response to a TopicQuery are stored in the associated DataReader's cache. Any of the read/take operations can retrieve TopicQuery samples. The field com.rti.dds.subscription.SampleInfo.topic_query_guid associates each sample to its TopicQuery. If the read sample is not in response to a TopicQuery then this field will be com.rti.dds.infrastructure.GUID_t.GUID_UNKNOWN. Note that the same data may be received several times, depending on how many TopicQueries the DataReader creates and their TopicQuerySelection.
You can choose to read or take only TopicQuery samples, only live samples, or both. To support this ReadConditions and QueryConditions provide the com.rti.dds.subscription.DataReader.create_querycondition_w_params and com.rti.dds.subscription.DataReader.create_readcondition_w_params APIs.
Each TopicQuery is identified by a GUID that can be accessed using the com.rti.dds.subscription.TopicQuery.get_guid method.
A snapshot TopicQuery queries the samples that are in a DataWriter's queue when the DataWriter receives the TopicQuery.
When a DataWriter receives a snapshot TopicQuery, it registers the last sequence number available in the DataWriter queue (known as the cut-off SN). Then, the DataWriter applies the TopicQuery expression to all the samples up to the cut-off SN. If a sample with a SN smaller than or equal to the cut-off SN passes the filter expression, it will be included in the TopicQuery response.
When a DataWriter responds to a snapshot TopicQuery, it doesn't create any copies of the samples that are part of the response. As a result, a sample that passes the TopicQuery expression and should have been included in the response may be removed from the DataWriter queue before it reaches the DataReader that issued the TopicQuery. This can result in incomplete TopicQueries, which may or may not be necessary for your application to detect.
For instance, your application may issue a TopicQuery on a keyed topic using a filter on key-only fields and expect to receive the latest value for an instance that passes the filter. However, if the latest value for the instance is replaced with a newer value before the sample is delivered to the DataReader, it is important to detect this situation and re-issue the TopicQuery.
On the other hand, some applications may not care about which samples are returned in response to a TopicQuery, and are only interested in a snapshot of the DataWriter's queue. In such cases, the concept of incomplete TopicQueries can be ignored.
The application can detect incomplete TopicQueries by checking the com.rti.dds.infrastructure.SampleFlagBits.INCOMPLETE_SNAPSHOT_TOPIC_QUERY bit in the com.rti.dds.subscription.SampleInfo.flag field of the last sample received for a snapshot TopicQuery.
To reduce the probability of receiving incomplete responses, DataWriters configured with com.rti.dds.infrastructure.HistoryQosPolicyKind.HistoryQosPolicyKind.KEEP_LAST_HISTORY_QOS recalculate the cut-off SN for a snapshot TopicQuery if a sample is replaced in the DataWriter queue due to KEEP_LAST replacement before the complete TopicQuery response is published.
Snapshot TopicQueries are not automatically deleted once the DataWriters that respond to the TopicQuery have finished delivering the samples included in the response. It is the responsibility of the user to delete the TopicQuery when it is no longer needed. To detect the end of a snapshot TopicQuery response, check for the com.rti.dds.infrastructure.SampleFlagBits.INTERMEDIATE_TOPIC_QUERY_SAMPLE flag in the com.rti.dds.subscription.SampleInfo.flag field of the samples included in the response. For more information on how to use this flag, see Reading TopicQuery Samples.
A TopicQuery response is the set of samples published by a DataWriter in response to a TopicQuery. Because multiple DataWriters may respond to a TopicQuery, a DataReader may receive multiple responses for a single TopicQuery.
Responses can be proxied by Routing Service DataWriters by setting <topic_query_proxy>/<mode> to PROPAGATION. These DataWriters forward a TopicQuery response, but they are not considered to be responding to the TopicQuery.
Samples that a DataReader receives in response to a TopicQuery have a value for com.rti.dds.subscription.SampleInfo.topic_query_guid different than com.rti.dds.infrastructure.GUID_t.GUID_UNKNOWN.
In addition, the virtual GUID of the DataWriter(s) that responded to a TopicQuery is set in com.rti.dds.subscription.SampleInfo.source_guid.
Intermediate samples, not the final sample, have the flag com.rti.dds.infrastructure.SampleFlagBits.INTERMEDIATE_TOPIC_QUERY_SAMPLE set in com.rti.dds.subscription.SampleInfo.flag for a given response to a snapshot TopicQuery.
If two DataWriters respond to a snapshot TopicQuery, you should expect two final samples, one per unique com.rti.dds.subscription.SampleInfo.source_guid responding to the TopicQuery, assuming that at least one sample passes the TopicQuery filter for each DataWriter.
The com.rti.dds.subscription.SampleInfo.flag field of the last sample received for a snapshot TopicQuery may have the com.rti.dds.infrastructure.SampleFlagBits.INCOMPLETE_SNAPSHOT_TOPIC_QUERY bit set if the TopicQuery response is incomplete, which may or may not be necessary for your application to detect. See Snapshot TopicQueries for more information.
There are a number of ways in which to gain more insight into what is happening in an application that is creating Topic Queries.
TopicQueries are communicated to publishing applications through a built-in com.rti.dds.topic.builtin.ServiceRequest channel. The ServiceRequest channel is designed to be generic so that it can be used for many different purposes, one of which is TopicQueries.
When a DataReader creates a TopicQuery, a com.rti.dds.topic.builtin.ServiceRequest message is sent containing the TopicQuery information. Just as there are built-in DataReaders for com.rti.dds.domain.builtin.ParticipantBuiltinTopicData, com.rti.dds.subscription.builtin.SubscriptionBuiltinTopicData, and com.rti.dds.publication.builtin.PublicationBuiltinTopicData, there is a fourth built-in DataReader for ServiceRequests.
The new built-in DataReader can be retrieved using the built-in subscriber and com.rti.dds.subscription.Subscriber.lookup_datareader. The topic name is com.rti.dds.topic.builtin.ServiceRequestTypeSupport.SERVICE_REQUEST_TOPIC_NAME. Installing a listener with the com.rti.dds.subscription.DataReaderListener.on_data_available callback implemented will allow a publishing application to be notified whenever a TopicQuery has been received from a subscribing application.
The builtin.ServiceRequest.service_id of a com.rti.dds.topic.builtin.ServiceRequest corresponding to a com.rti.dds.subscription.TopicQuery will be com.rti.dds.topic.builtin.ServiceRequest.TOPIC_QUERY_SERVICE_ID and the builtin.ServiceRequest.instance_id will be equal to the GUID of the com.rti.dds.subscription.TopicQuery (see com.rti.dds.subscription.TopicQuery.get_guid).
The builtin.ServiceRequest.request_body is a sequence of bytes containing more information about the TopcQuery. This information can be retrieved using the com.rti.dds.subscription.TopicQueryHelper.topic_query_data_from_service_request function. The resulting com.rti.dds.subscription.TopicQueryData contains the com.rti.dds.subscription.TopicQuerySelection that the com.rti.dds.subscription.TopicQuery was created with, the GUID of the original DataReader that created the TopicQuery, and the topic name of that DataReader. Note: When TopicQueries are propagated through one or more Routing Services, the last DataReader that issued the TopicQuery will be a Routing Service DataReader. The com.rti.dds.subscription.TopicQueryData.original_related_reader_guid, however, will be that of the first DataReader to have created the TopicQuery.
It is possible that a com.rti.dds.topic.builtin.ServiceRequest for a com.rti.dds.subscription.TopicQuery is received but is not immediately dispatched to a DataWriter. This can happen, for example, if a DataWriter was not matching with a DataReader at the time that the TopicQuery was received by the publishing application. The com.rti.dds.publication.DataWriterListener.on_service_request_accepted callback notifies a DataWriter when a ServiceRequest has been dispatched to that DataWriter. The com.rti.dds.publication.ServiceRequestAcceptedStatus provides information about how many ServiceRequests have been accepted by the DataWriter since the last time that the status was read. The status also includes the com.rti.dds.publication.ServiceRequestAcceptedStatus.last_request_handle, which is the com.rti.dds.infrastructure.InstanceHandle_t of the last ServiceRequest that was accepted. This instance handle can be used to read samples per instance from the built-in ServiceRequest DataReader and correlate which ServiceRequests have been dispatched to which DataWriters.
|
static |
Special value for creating a com.rti.dds.subscription.TopicQuery that applies the same filter as the DataReader's com.rti.dds.topic.ContentFilteredTopic.
If the com.rti.dds.subscription.DataReader that creates the com.rti.dds.subscription.TopicQuery uses a com.rti.dds.topic.ContentFilteredTopic, this com.rti.dds.subscription.TopicQuerySelection value indicates that the TopicQuery should use the same filter.
Otherwise it behaves as com.rti.dds.subscription.DataReader.TOPIC_QUERY_SELECTION_SELECT_ALL.
|
static |
Special value for creating a com.rti.dds.subscription.TopicQuery that selects all the samples in a com.rti.dds.publication.DataWriter cache.