RTI Connext Java API
Version 7.0.0
|
Allows sending requests and receiving replies. More...
Public Member Functions | |
Requester (RequesterParams params) | |
Creates a Requester with parameters. More... | |
Requester (DomainParticipant participant, String serviceName, TypeSupport requestTypeSupport, TypeSupport replyTypeSupport) | |
Creates a Requester with the minimum set of parameters. More... | |
void | close () |
Releases the internal entities created by this object. More... | |
void | sendRequest (TReq request) |
Sends a request. More... | |
void | sendRequest (WriteSample< TReq > request) |
Sends a request and gets back information about it that allows correlation with future replies. More... | |
boolean | receiveReply (Sample< TRep > reply, Duration_t maxWait) |
Waits for a reply and copies its contents into a Sample. More... | |
List< Sample< TRep > > | receiveReplies (List< Sample< TRep >> replies, int maxCount, Duration_t maxWait) |
Waits for multiple replies and copies them into a list. More... | |
List< Sample< TRep > > | receiveReplies (List< Sample< TRep >> replies, int minCount, int maxCount, Duration_t maxWait) |
Waits for multiple replies and copies them into a list. More... | |
Sample.Iterator< TRep > | receiveReplies (Duration_t maxWait) |
Waits for multiple replies and provides a loaned iterator to access them. More... | |
Sample.Iterator< TRep > | receiveReplies (int minCount, int maxCount, Duration_t maxWait) |
Waits for multiple replies and provides a loaned iterator to access them. More... | |
boolean | takeReply (Sample< TRep > reply) |
Copies the contents of a reply into a Sample. More... | |
Sample.Iterator< TRep > | takeReplies () |
Provides a loaned iterator to access the existing replies. More... | |
Sample.Iterator< TRep > | takeReplies (int maxCount) |
Provides a loaned iterator to access the existing replies. More... | |
List< Sample< TRep > > | takeReplies (List< Sample< TRep >> replies, int maxCount) |
Copies existing replies into a list. More... | |
boolean | takeReply (Sample< TRep > reply, SampleIdentity_t relatedRequestId) |
Copies the contents of a reply for a specific request. More... | |
Sample.Iterator< TRep > | takeReplies (SampleIdentity_t relatedRequestId) |
Provides a loaned iterator to access the existing replies for a specific request. More... | |
Sample.Iterator< TRep > | takeReplies (int maxCount, SampleIdentity_t relatedRequestId) |
Provides a loaned iterator to access the existing replies for a specific request. More... | |
List< Sample< TRep > > | takeReplies (List< Sample< TRep >> replies, int maxCount, SampleIdentity_t relatedRequestId) |
Copies existing replies for a specific request into a list. More... | |
boolean | readReply (Sample< TRep > reply) |
Copies the contents of a reply into a Sample. More... | |
Sample.Iterator< TRep > | readReplies () |
Provides a loaned iterator to access the existing replies. More... | |
Sample.Iterator< TRep > | readReplies (int maxCount) |
Provides a loaned iterator to access the existing replies. More... | |
List< Sample< TRep > > | readReplies (List< Sample< TRep >> replies, int maxCount) |
Copies existing replies into a list. More... | |
boolean | readReply (Sample< TRep > reply, SampleIdentity_t relatedRequestId) |
Copies the contents of a reply for a specific request. More... | |
Sample.Iterator< TRep > | readReplies (SampleIdentity_t relatedRequestId) |
Provides a loaned iterator to access the existing replies for a specific request. More... | |
Sample.Iterator< TRep > | readReplies (int maxCount, SampleIdentity_t relatedRequestId) |
Provides a loaned iterator to access the existing replies for a specific request. More... | |
List< Sample< TRep > > | readReplies (List< Sample< TRep >> replies, int maxCount, SampleIdentity_t relatedRequestId) |
Copies existing replies for a specific request into a list. More... | |
boolean | waitForReplies (Duration_t maxWait) |
Waits for replies to any request. More... | |
boolean | waitForReplies (int minCount, Duration_t maxWait) |
Waits for replies to any request. More... | |
boolean | waitForReplies (int minCount, Duration_t maxWait, SampleIdentity_t relatedRequestId) |
Waits for replies to a specific request. More... | |
DataWriter | getRequestDataWriter () |
Retrieves the underlying com.rti.dds.publication.DataWriter. More... | |
DataReader | getReplyDataReader () |
Retrieves the underlying com.rti.dds.subscription.DataReader. More... | |
WriteSample< TReq > | createRequestSample () |
Creates a WriteSample for sending requests. More... | |
WriteSample< TReq > | createRequestSample (TReq data) |
Creates a WriteSample for sending requests. More... | |
Sample< TRep > | createReplySample () |
Creates a Sample for getting replies. More... | |
Sample< TRep > | createReplySample (TRep data) |
Creates a Sample for getting replies. More... | |
Allows sending requests and receiving replies.
A requester is an entity with two associated topics: a request topic and a reply topic. It can send requests by publishing samples of the request topic and receive replies to those requests by subscribing to the reply topic.
Valid types for these topics (TReq
and TRep
)are: those generated by rtiddsgen, the DDS built-in types, and com.rti.dds.dynamicdata.DynamicData.
For example:
A Replier and a Requester communicate when they use the same topics for requests and replies (see com.rti.connext.requestreply.RequesterParams.setServiceName(String)) on the same domain ID.
A Requester can send requests and receive one or multiple replies. It does that using the following operations:
In all cases, the middleware guarantees that a requester only receives reply samples that are associated with those requests that it sends.
For multi-reply scenarios, in which a Requester receives multiple replies from a Replier for a given request, the Requester can check if a reply is the last reply of a sequence of replies. To do so, see if the bit com.rti.dds.infrastructure.SampleFlagBits.INTERMEDIATE_REPLY_SEQUENCE_SAMPLE is set in com.rti.dds.subscription.SampleInfo.flag after receiving each reply. This indicates it is NOT the last reply.
A requester has an associated com.rti.dds.domain.DomainParticipant, which can be shared with other requesters or RTI Connext routines. All the other RTI Connext entities required for the request-reply interaction, including a com.rti.dds.publication.DataWriter for writing requests and a com.rti.dds.subscription.DataReader for reading replies, are automatically created when the requester is constructed.
Quality of Service for the underlying DataWriter and DataReader can be configured (see com.rti.connext.requestreply.RequesterParams.setQosProfile(String,String)). By default, they are created with com.rti.dds.infrastructure.ReliabilityQosPolicyKind.RELIABLE_RELIABILITY_QOS. The exact default configuration is described here: Configuring Request-Reply QoS profiles
TReq | The data type for the request topic |
TRep | The data type for the reply topic |
Requester | ( | RequesterParams | params | ) |
Creates a Requester with parameters.
params | All the parameters that configure this requester. See com.rti.connext.requestreply.RequesterParams for the list of mandatory parameters. |
One | of the Standard Return Codes |
References Requester< TReq, TRep >.getRequestDataWriter(), DataWriterQos.protocol, and DataWriterProtocolQosPolicy.virtual_guid.
Requester | ( | DomainParticipant | participant, |
String | serviceName, | ||
TypeSupport | requestTypeSupport, | ||
TypeSupport | replyTypeSupport | ||
) |
Creates a Requester with the minimum set of parameters.
participant | The DomainParticipant this requester uses to join a DDS domain |
serviceName | The service name. See com.rti.connext.requestreply.RequesterParams.setServiceName(String) |
requestTypeSupport | The type support for type TReq |
replyTypeSupport | The type support for type TReq |
One | of the Standard Return Codes |
References RequesterParams.setServiceName().
void close | ( | ) |
Releases the internal entities created by this object.
Among other internal resources, it deletes the underlying DataReader and DataWriter.
void sendRequest | ( | TReq | request | ) |
Sends a request.
If a future reply needs to be correlated to exactly this request, use com.rti.connext.requestreply.Requester<TReq,TRep>.sendRequest(WriteSample<TReq>).
request | The request to be sent |
One | of the Standard Return Codes |
void sendRequest | ( | WriteSample< TReq > | request | ) |
Sends a request and gets back information about it that allows correlation with future replies.
After calling this operation, the sample contains a valid identity that can be used for correlation with future replies.
See example code in Correlating requests and replies.
request | <<inout>> Contains the request and optional write parameters. When this call ends successfully, com.rti.connext.infrastructure.WriteSample<T> contains a valid identity that can be used for correlation with future replies. |
One | of the Standard Return Codes ; com.rti.dds.infrastructure.RETCODE_TIMEOUT may be reported in the same conditions as in com.rti.ndds.example.FooDataWriter.write. |
References SampleIdentity_t.AUTO_SAMPLE_IDENTITY, SampleData< T >.getData(), and WriteSample< T >.getInfo().
boolean receiveReply | ( | Sample< TRep > | reply, |
Duration_t | maxWait | ||
) |
Waits for a reply and copies its contents into a Sample.
This operation is equivalent to using waitForReplies(int,Duration_t) and takeReply(Sample<TRep>).
List<Sample<TRep> > receiveReplies | ( | List< Sample< TRep >> | replies, |
int | maxCount, | ||
Duration_t | maxWait | ||
) |
Waits for multiple replies and copies them into a list.
This operation is equivalent to using receiveReplies(List<Sample<TRep>>,int,int,Duration_t) with min_count = 0
Referenced by Requester< TReq, TRep >.receiveReplies().
List<Sample<TRep> > receiveReplies | ( | List< Sample< TRep >> | replies, |
int | minCount, | ||
int | maxCount, | ||
Duration_t | maxWait | ||
) |
Waits for multiple replies and copies them into a list.
This operation is equivalent to using waitForReplies(int,Duration_t) and takeReplies(List<Sample<TRep>>,int).
Sample.Iterator<TRep> receiveReplies | ( | Duration_t | maxWait | ) |
Waits for multiple replies and provides a loaned iterator to access them.
This operation is equivalent to using receiveReplies(int,int,Duration_t) with min_count=1
and max_count=com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED
References ResourceLimitsQosPolicy.LENGTH_UNLIMITED, and Requester< TReq, TRep >.receiveReplies().
Sample.Iterator<TRep> receiveReplies | ( | int | minCount, |
int | maxCount, | ||
Duration_t | maxWait | ||
) |
Waits for multiple replies and provides a loaned iterator to access them.
This operation is equivalent to using waitForReplies(int,Duration_t) and takeReplies(int).
One | of the Standard Return Codes |
boolean takeReply | ( | Sample< TRep > | reply | ) |
Copies the contents of a reply into a Sample.
Takes a reply sample from the Requester and makes a copy.
This operation may be used after a call to waitForReplies(int,Duration_t).
To avoid copies, you can use takeReplies(int).
reply | The sample where the reply data and the related SampleInfo are copied |
reply
remain unchanged, except com.rti.dds.subscription.SampleInfo.valid_data becomes false. One | of the Standard Return Codes |
Sample.Iterator<TRep> takeReplies | ( | ) |
Provides a loaned iterator to access the existing replies.
Equivalent to using takeReplies(int) with max_count=com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED
.
References ResourceLimitsQosPolicy.LENGTH_UNLIMITED.
Referenced by Requester< TReq, TRep >.takeReplies().
Sample.Iterator<TRep> takeReplies | ( | int | maxCount | ) |
Provides a loaned iterator to access the existing replies.
Takes all the existing replies up to maxCount
and provides a loaned iterator to access them.
This operation does not make a copy of the data.
The loan is returned with com.rti.connext.infrastructure.Sample<T>.Iterator<T>.close()
Since Sample.Iterator<T>
implements java.io.Closeable
, the loan is automatically returned when the iterator is enclosed in a try-with-resources
block (since Java 7)
This operation may be used after a call to waitForReplies(int,Duration_t)
See an example here: Taking loaned samples
maxCount | The maximum number of samples that are taken at a time. The special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED may be used. This value will read up to the limit specified by com.rti.dds.infrastructure.DataReaderResourceLimitsQosPolicy.max_samples_per_read |
One | of the Standard Return Codes |
Copies existing replies into a list.
Takes all the existing replies up to maxCount
and copies them into a list.
If the first argument is null, a new list containing the copies is created and returned.
If a non-null list is passed as the first argument, the copies are inserted into that list. The list may already contain some elements. Any existing elements are overwritten. If the list contains less elements, samples are inserted at the end; if it contains more elements, the excess samples are removed from the end.
This operation may be used after a call to waitForReplies(int,Duration_t).
replies | The list where the samples are copied or null to create a new list. |
maxCount | The maximum number of samples that are taken at a time. The special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED may be used. |
replies
if it's not null
. Otherwise it returns a new list. One | of the Standard Return Codes |
boolean takeReply | ( | Sample< TRep > | reply, |
SampleIdentity_t | relatedRequestId | ||
) |
Copies the contents of a reply for a specific request.
This operation is analogous to takeReply(Sample<TRep>) except the reply corresponds to a specific request.
reply | The sample where a reply is copied into |
relatedRequestId | The identity of a request previously sent by this Requester |
reply
remain unchanged, except com.rti.dds.subscription.SampleInfo.valid_data becomes false. References SampleStateKind.ANY_SAMPLE_STATE, and SampleIdentity_t.sequence_number.
Sample.Iterator<TRep> takeReplies | ( | SampleIdentity_t | relatedRequestId | ) |
Provides a loaned iterator to access the existing replies for a specific request.
Equivalent to using takeReplies(int,SampleIdentity_t) with max_count=com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED
References ResourceLimitsQosPolicy.LENGTH_UNLIMITED, and Requester< TReq, TRep >.takeReplies().
Sample.Iterator<TRep> takeReplies | ( | int | maxCount, |
SampleIdentity_t | relatedRequestId | ||
) |
Provides a loaned iterator to access the existing replies for a specific request.
This operation is analogous to takeReplies(int) except the replies this operation provides correspond to a specific request.
maxCount | The maximum number of samples that are taken at a time. The special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED may be used. |
relatedRequestId | The identity of a request previously sent by this Requester |
References SampleStateKind.ANY_SAMPLE_STATE, and SampleIdentity_t.sequence_number.
List<Sample<TRep> > takeReplies | ( | List< Sample< TRep >> | replies, |
int | maxCount, | ||
SampleIdentity_t | relatedRequestId | ||
) |
Copies existing replies for a specific request into a list.
This operation is analogous to takeReplies(List<Sample<TRep>>,int) except the replies correspond to a specific request.
replies | The list where the samples are copied or null to create a new List. |
maxCount | The maximum number of samples that are taken at a time. The special value com.rti.dds.infrastructure.ResourceLimitsQosPolicy.LENGTH_UNLIMITED may be used. |
relatedRequestId | The identity of a request previously sent by this Requester |
replies
if it is not null
. Otherwise it returns a new List
. References SampleStateKind.ANY_SAMPLE_STATE, and SampleIdentity_t.sequence_number.
boolean readReply | ( | Sample< TRep > | reply | ) |
Copies the contents of a reply into a Sample.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReply(Sample<TRep>) except the reply remains in the Requester and can be read or taken again.
Sample.Iterator<TRep> readReplies | ( | ) |
Provides a loaned iterator to access the existing replies.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReplies() except the replies remain in the Requester and can be read or taken again.
References ResourceLimitsQosPolicy.LENGTH_UNLIMITED.
Referenced by Requester< TReq, TRep >.readReplies().
Sample.Iterator<TRep> readReplies | ( | int | maxCount | ) |
Provides a loaned iterator to access the existing replies.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReplies(int) except the replies remain in the Requester and can be read or taken again.
Copies existing replies into a list.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReplies(List<Sample<TRep>>,int) except the replies remain in the Requester and can be read or taken again.
boolean readReply | ( | Sample< TRep > | reply, |
SampleIdentity_t | relatedRequestId | ||
) |
Copies the contents of a reply for a specific request.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReply(Sample<TRep>,SampleIdentity_t) except the reply remains in the Requester and can be read or taken again.
References SampleStateKind.ANY_SAMPLE_STATE, and SampleIdentity_t.sequence_number.
Sample.Iterator<TRep> readReplies | ( | SampleIdentity_t | relatedRequestId | ) |
Provides a loaned iterator to access the existing replies for a specific request.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReplies(SampleIdentity_t) except the replies remain in the Requester and can be read or taken again.
References ResourceLimitsQosPolicy.LENGTH_UNLIMITED, and Requester< TReq, TRep >.readReplies().
Sample.Iterator<TRep> readReplies | ( | int | maxCount, |
SampleIdentity_t | relatedRequestId | ||
) |
Provides a loaned iterator to access the existing replies for a specific request.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReplies(int,SampleIdentity_t) except the replies remain in the Requester and can be read or taken again.
References SampleStateKind.ANY_SAMPLE_STATE, and SampleIdentity_t.sequence_number.
List<Sample<TRep> > readReplies | ( | List< Sample< TRep >> | replies, |
int | maxCount, | ||
SampleIdentity_t | relatedRequestId | ||
) |
Copies existing replies for a specific request into a list.
This operation is equivalent to com.rti.connext.requestreply.Requester<TReq,TRep>.takeReplies(List<Sample<TRep>>,int,SampleIdentity_t) except the replies remain in the Requester and can be read or taken again.
References SampleStateKind.ANY_SAMPLE_STATE, and SampleIdentity_t.sequence_number.
boolean waitForReplies | ( | Duration_t | maxWait | ) |
Waits for replies to any request.
This operation is equivalent to using waitForReplies(int,Duration_t) with min_count=1
.
boolean waitForReplies | ( | int | minCount, |
Duration_t | maxWait | ||
) |
Waits for replies to any request.
This operation waits for minCount requests to be available for up to maxWait .
If this operation is called several times but the available replies are not taken (with takeReplies(int)), this operation may return immediately and will not wait for new replies. New replies may replace existing ones if they are not taken, depending on the com.rti.dds.infrastructure.HistoryQosPolicy used to configure this Requester.
minCount | Minimum number of replies that need to be available for this operation to unblock. |
maxWait | Maximum waiting time after which this operation unblocks, regardless of how many replies are available. |
boolean waitForReplies | ( | int | minCount, |
Duration_t | maxWait, | ||
SampleIdentity_t | relatedRequestId | ||
) |
Waits for replies to a specific request.
This operation is analogous to waitForReplies(int,Duration_t) except this operation waits for replies for a specific request.
minCount | Minimum number of replies for the related request that need to be available for this operation to unblock. |
maxWait | Maximum wait time after which this operation unblocks, regardless of how many replies are available. |
relatedRequestId | The identity of a request previously sent by this Requester |
One | of the Standard Return Codes |
References SampleStateKind.ANY_SAMPLE_STATE, SampleStateKind.NOT_READ_SAMPLE_STATE, and SampleIdentity_t.sequence_number.
DataWriter getRequestDataWriter | ( | ) |
Retrieves the underlying com.rti.dds.publication.DataWriter.
Accessing the request DataWriter may be useful for a number of advanced use cases, such as:
Referenced by Requester< TReq, TRep >.Requester().
DataReader getReplyDataReader | ( | ) |
Retrieves the underlying com.rti.dds.subscription.DataReader.
Accessing the reply DataReader may be useful for a number of advanced use cases, such as:
WriteSample<TReq> createRequestSample | ( | ) |
Creates a WriteSample for sending requests.
TReq
initialized with default values and default write parameters. WriteSample<TReq> createRequestSample | ( | TReq | data | ) |
Creates a WriteSample for sending requests.
Sample<TRep> createReplySample | ( | ) |
Creates a Sample for getting replies.
TRep
and invalid SampleInfo. Sample<TRep> createReplySample | ( | TRep | data | ) |
Creates a Sample for getting replies.
TRep
and invalid SampleInfo. References InstanceStateKind.ANY_INSTANCE_STATE, ViewStateKind.ANY_VIEW_STATE, SequenceNumber_t.AUTO_SEQUENCE_NUMBER, ReadCondition.get_sample_state_mask(), SampleInfo.related_original_publication_virtual_sequence_number, SequenceNumber_t.SEQUENCE_NUMBER_MAX, SequenceNumber_t.SEQUENCE_NUMBER_UNKNOWN, and SequenceNumber_t.SEQUENCE_NUMBER_ZERO.