Allows sending requests and receiving replies. More...

Inheritance diagram for Requester< TReq, TRep >:

Public Member Functions
	Requester (RequesterParams params)
	Creates a Requester with parameters.

	Requester (DomainParticipant participant, String serviceName, TypeSupport requestTypeSupport, TypeSupport replyTypeSupport)
	Creates a Requester with the minimum set of parameters.

void	close ()
	Releases the internal entities created by this object.

void	sendRequest (TReq request)
	Sends a request.

void	sendRequest (WriteSample< TReq > request)
	Sends a request and gets back information about it that allows correlation with future replies.

boolean	receiveReply (Sample< TRep > reply, Duration_t maxWait)
	Waits for a reply and copies its contents into a Sample.

List< Sample< TRep > >	receiveReplies (List< Sample< TRep >> replies, int maxCount, Duration_t maxWait)
	Waits for multiple replies and copies them into a list.

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.

Sample.Iterator< TRep >	receiveReplies (Duration_t maxWait)
	Waits for multiple replies and provides a loaned iterator to access them.

Sample.Iterator< TRep >	receiveReplies (int minCount, int maxCount, Duration_t maxWait)
	Waits for multiple replies and provides a loaned iterator to access them.

boolean	takeReply (Sample< TRep > reply)
	Copies the contents of a reply into a Sample.

Sample.Iterator< TRep >	takeReplies ()
	Provides a loaned iterator to access the existing replies.

Sample.Iterator< TRep >	takeReplies (int maxCount)
	Provides a loaned iterator to access the existing replies.

List< Sample< TRep > >	takeReplies (List< Sample< TRep >> replies, int maxCount)
	Copies existing replies into a list.

boolean	takeReply (Sample< TRep > reply, SampleIdentity_t relatedRequestId)
	Copies the contents of a reply for a specific request.

Sample.Iterator< TRep >	takeReplies (SampleIdentity_t relatedRequestId)
	Provides a loaned iterator to access the existing replies for a specific request.

Sample.Iterator< TRep >	takeReplies (int maxCount, SampleIdentity_t relatedRequestId)
	Provides a loaned iterator to access the existing replies for a specific request.

List< Sample< TRep > >	takeReplies (List< Sample< TRep >> replies, int maxCount, SampleIdentity_t relatedRequestId)
	Copies existing replies for a specific request into a list.

boolean	readReply (Sample< TRep > reply)
	Copies the contents of a reply into a Sample.

Sample.Iterator< TRep >	readReplies ()
	Provides a loaned iterator to access the existing replies.

Sample.Iterator< TRep >	readReplies (int maxCount)
	Provides a loaned iterator to access the existing replies.

List< Sample< TRep > >	readReplies (List< Sample< TRep >> replies, int maxCount)
	Copies existing replies into a list.

boolean	readReply (Sample< TRep > reply, SampleIdentity_t relatedRequestId)
	Copies the contents of a reply for a specific request.

Sample.Iterator< TRep >	readReplies (SampleIdentity_t relatedRequestId)
	Provides a loaned iterator to access the existing replies for a specific request.

Sample.Iterator< TRep >	readReplies (int maxCount, SampleIdentity_t relatedRequestId)
	Provides a loaned iterator to access the existing replies for a specific request.

List< Sample< TRep > >	readReplies (List< Sample< TRep >> replies, int maxCount, SampleIdentity_t relatedRequestId)
	Copies existing replies for a specific request into a list.

boolean	waitForReplies (Duration_t maxWait)
	Waits for replies to any request.

boolean	waitForReplies (int minCount, Duration_t maxWait)
	Waits for replies to any request.

boolean	waitForReplies (int minCount, Duration_t maxWait, SampleIdentity_t relatedRequestId)
	Waits for replies to a specific request.

DataWriter	getRequestDataWriter ()
	Retrieves the underlying com.rti.dds.publication.DataWriter.

DataReader	getReplyDataReader ()
	Retrieves the underlying com.rti.dds.subscription.DataReader.

WriteSample< TReq >	createRequestSample ()
	Creates a WriteSample for sending requests.

WriteSample< TReq >	createRequestSample (TReq data)
	Creates a WriteSample for sending requests.

Sample< TRep >	createReplySample ()
	Creates a Sample for getting replies.

Sample< TRep >	createReplySample (TRep data)
	Creates a Sample for getting replies.

Detailed Description

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 the rtiddsgen code generator, the DDS built-in types, and DynamicData.

For example:

Requester<Foo, Bar> requester;
Requester<DynamicData, Bar> requester;
Requester<Foo, Octets> requester;

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.

A Requester can send requests and receive replies. It does that using the following operations:

Sending requests (i.e. publishing request samples on the request topic)
Waiting for replies to be received by the middleware (for any request or for a specific request)
Getting those replies from the middleware. There are two ways to do this: take (the data samples are removed from the middleware), read (the data samples remain in the middleware and can be read or taken again).
A convenience operation, receive (which is a combination of wait and take).

In all cases, the middleware guarantees that a requester only receives reply samples that are associated with that requests that it sends.

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 reliable quality of service. The exact default configuration is described here: Configuring Request-Reply QoS profiles

Template Parameters

TReq	The data type for the request topic
TRep	The data type for the reply topic

See Also: com.rti.connext.requestreply.Replier<TReq,TRep>; Request-Reply Examples; Basic Requester example

Constructor & Destructor Documentation

Requester ( RequesterParams params )

Creates a Requester with parameters.

Parameters

params All the parameters that configure this requester. See com.rti.connext.requestreply.RequesterParams for the list of mandatory parameters.

Exceptions

One	of the Standard Return Codes

See Also: com.rti.connext.requestreply.RequesterParams; Creating a Requester

Requester	(	DomainParticipant	participant,
		String	serviceName,
		TypeSupport	requestTypeSupport,
		TypeSupport	replyTypeSupport
	)

Creates a Requester with the minimum set of parameters.

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`

Exceptions

One	of the Standard Return Codes

Member Function Documentation

void close ( )

Releases the internal entities created by this object.

Among other internal resources, it deletes the underlying DataReader and DataWriter.

See Also: com.rti.dds.subscription.Subscriber.delete_datareader; com.rti.dds.publication.Publisher.delete_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>).

Parameters

request The request to be sent

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: sendRequest(WriteSample<TReq>)

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.

Parameters

request <<inout>> Contains the request and optional write parameters. When this call ends succesfully, com.rti.connext.infrastructure.WriteSample<T> contains a valid identity that can be used for correlation with future replies.

Exceptions

One	of the Standard Return Codes ; RETCODE_TIMEOUT may be reported in the same conditions as in com.rti.ndds.example.FooDataWriter.write.

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.SampleData<T>.getIdentity(); createRequestSample(); waitForReplies(int,Duration_t,SampleIdentity_t); takeReplies(int,SampleIdentity_t); Correlating requests and replies

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>).

MT Safety:: Same restrictions as waitForReplies(int,Duration_t)

See Also: com.rti.connext.infrastructure.Sample<T>; waitForReplies(int,Duration_t); takeReply(Sample<TRep>); Basic Requester example

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

MT Safety:: See waitForReplies(int,Duration_t)

See Also: com.rti.connext.infrastructure.Sample<T>; receiveReplies(List<Sample<TRep>>,int,Duration_t)

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).

MT Safety:: See waitForReplies(int,Duration_t)

See Also: com.rti.connext.infrastructure.Sample<T>; waitForReplies(int,Duration_t); 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

MT Safety:: See waitForReplies(int,Duration_t)

See Also: com.rti.connext.infrastructure.Sample<T>.Iterator<T>; receiveReplies(int,int,Duration_t)

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).

MT Safety:: See waitForReplies(int,Duration_t)

Exceptions

One	of the Standard Return Codes

See Also: com.rti.connext.infrastructure.Sample<T>.Iterator<T>; waitForReplies(int,Duration_t); takeReplies(int)

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).

Parameters

reply The sample where the reply data and the related SampleInfo are copied

Returns: true if there was a reply to get. If this operation returns false, the contents of reply remain unchanged, except com.rti.dds.subscription.SampleInfo.valid_data becomes false.

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>; waitForReplies(int,Duration_t)

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.

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>.Iterator<T>; takeReplies(int)

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

Parameters

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

Returns: A iterator with up to maxCount elements. May be empty if there were no replies to get.

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>; com.rti.connext.infrastructure.Sample<T>.Iterator<T>; com.rti.connext.infrastructure.Sample<T>.Iterator<T>.close(); waitForReplies(int,Duration_t); com.rti.ndds.example.FooDataReader.take (for a more detailed description on how QoS and other parameters affect the underlying DataReader); Taking loaned samples; Taking samples by copy

List<Sample<TRep> > takeReplies	(	List< Sample< TRep >>	replies,
		int	maxCount
	)

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).

Parameters

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.

Returns: Returns replies if it's not null. Otherwise it returns a new list.

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>; waitForReplies(int,Duration_t); takeReplies(int); Taking loaned samples

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.

Parameters

reply	The sample where a reply is copied into
relatedRequestId	The identity of a request previously sent by this Requester

Returns: true if there was a reply to get. If this operation returns false, the contents of reply remain unchanged, except com.rti.dds.subscription.SampleInfo.valid_data becomes false.

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>; takeReply(Sample<TRep>); sendRequest(WriteSample<TReq>); Correlating requests and replies

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

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>.Iterator<T>; takeReplies(int,SampleIdentity_t)

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.

Parameters

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

MT Safety:: SAFE

See Also: takeReplies(int); com.rti.connext.infrastructure.Sample<T>.Iterator<T>; Taking samples by copy; Correlating requests and replies

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.

Parameters

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

Returns: replies if it is not null. Otherwise it returns a new List.

MT Safety:: SAFE

See Also: waitForReplies(int,Duration_t); takeReplies(List<Sample<TRep>>,int); Taking loaned samples; Correlating requests and replies

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.

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.

List<Sample<TRep> > readReplies	(	List< Sample< TRep >>	replies,
		int	maxCount
	)

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.

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.

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.

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.

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.

See Also: waitForReplies(int,Duration_t)

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.

Parameters

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.

Returns: true if at least minCount replies were available before maxWait elapsed, or false otherwise.

MT Safety:: Concurrent calls to this operation on the same object are not allowed. However, waiting for replies for specific requests in parallel is supported (see waitForReplies(int,Duration_t,SampleIdentity_t)).

See Also: takeReplies(int)

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.

Parameters

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

Returns: true if at least minCount replies for the related request were available before maxWait elapsed, or false otherwise.

Exceptions

One	of the Standard Return Codes

MT Safety:: SAFE

See Also: waitForReplies(int,Duration_t)

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:

Finding matching subscriptions (e.g., Repliers)
Setting a DataWriter listener
Getting DataWriter protocol or cache statuses

MT Safety:: SAFE

See Also: com.rti.dds.publication.DataWriter; com.rti.ndds.example.FooDataWriter; com.rti.dds.publication.DataWriter.get_matched_subscriptions; com.rti.dds.publication.DataWriter.get_matched_subscription_data; com.rti.dds.publication.DataWriter.set_listener; com.rti.dds.publication.DataWriter.get_datawriter_protocol_status

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:

Finding matching publications (e.g., Repliers)
Setting a DataReader listener
Getting DataReader protocol or cache statuses

MT Safety:: SAFE

See Also: com.rti.dds.subscription.DataReader; com.rti.ndds.example.FooDataReader; com.rti.dds.subscription.DataReader.get_matched_publications; com.rti.dds.subscription.DataReader.get_matched_publication_data; com.rti.dds.subscription.DataReader.set_listener; com.rti.dds.subscription.DataReader.get_datareader_protocol_status

WriteSample<TReq> createRequestSample ( )

Creates a WriteSample for sending requests.

Returns: A new WriteSample with data of type TReq initialized with default values and default write parameters.

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.WriteSample<T>; sendRequest(WriteSample<TReq>)

WriteSample<TReq> createRequestSample ( TReq data )

Creates a WriteSample for sending requests.

Returns: A new WriteSample with the specified data and default write parameters.

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.WriteSample<T>; sendRequest(WriteSample<TReq>)

Sample<TRep> createReplySample ( )

Creates a Sample for getting replies.

Returns: A new Sample with default data of type TRep and invalid SampleInfo.

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>; receiveReply(Sample<TRep>,Duration_t); takeReply(Sample<TRep>); takeReply(Sample<TRep>,SampleIdentity_t)

Sample<TRep> createReplySample ( TRep data )

Creates a Sample for getting replies.

Returns: A new Sample with default data of type TRep and invalid SampleInfo.

MT Safety:: SAFE

See Also: com.rti.connext.infrastructure.Sample<T>; receiveReply(Sample<TRep>,Duration_t); takeReply(Sample<TRep>); takeReply(Sample<TRep>,SampleIdentity_t)

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation