Request-Reply Examples

Examples on how to use the request-reply API. More...

Examples on how to use the request-reply API.

Request-Reply code examples.

Request-Reply Examples

DDS Types

RTI Connext uses DDS data types for sending and receiving requests and replies. Valid types are those generated by the rtiddsgen code generator, the DDS built-in types, and DynamicData. Refer to the User's Manual and the following links for more information:

• Creating user data types using rtiddsgen,
• Using the DDS built-in types,
• Using DynamicData

Set up

• Create a DomainParticipant
• Create a requester
• Create a requester with parameters
• Create a replier

Requester: sending requests and receiving replies

• Basic Requester example
• Taking loaned samples
• Taking samples by copy
• Correlation between requests and replies

Replier: receiving requests and sending replies

• Basic Replier example
• SimpleReplier example
• Taking loaned samples
• Taking samples by copy

Error handling

• Error handling example

Creating a Requester

• Setting up a participant
• Creating a Requester

          
          // Note: error checking omitted for simplicity
          
          // Create a DomainParticipant
          DomainParticipant participant = 
                  DomainParticipantFactory.get_instance().create_participant(
                      domainId, DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT, 
                      null, StatusKind.STATUS_MASK_NONE);
                 
          // Create a Requester (if creation fails an exception is thrown)
          // Foo is the request type and FooTypeSupport is its DDS TypeSupport
          // Bar is the reply type and BarTypeSupport is its DDS TypeSupport
          Requester<Foo, Bar> requester = 
                  new Requester<Foo, Bar>(
                          participant, "TestService",
                          FooTypeSupport.get_instance(),
                          BarTypeSupport.get_instance());
          

• Finalizing a Requester

          requester.close();

  See also

  Creating a Requester with optional parameters

  Configuring Request-Reply QoS profiles

Creating a Requester with optional parameters

• Setting up a participant
• Creating a Requester with optional parameters

          
          // Note: error checking omitted for simplicity
          
          // Create a DomainParticipant
          DomainParticipant participant = 
                  DomainParticipantFactory.get_instance().create_participant(
                          0, DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT, 
                          null, StatusKind.STATUS_MASK_NONE);
          
          // Create a Requester with a QoS profile (located for example in
          // USER_QOS_PROFILES.xml, in the current working directory)
          Requester<Foo, Bar> requester = 
                  new Requester<Foo, Bar>(
                      new RequesterParams(
                          participant,
                          FooTypeSupport.get_instance(),
                          BarTypeSupport.get_instance())
                      .setServiceName("TestService")
                      .setQosProfile("RequestReplyExampleProfiles", 
                                     "RequesterExampleProfile"));
          

  See also

  Creating a Requester

Basic Requester example

• Creating a Requester
• Creating a Requester with optional parameters
• Basic Requester example

          
          // Send request
          Foo request = new Foo();
          request.message = "A request";
          requester.sendRequest(request);
          
          // Create reply Sample
          Sample<Bar> reply = requester.createReplySample();
          
          // Receive reply (wait for it and get the sample)
          boolean received = requester.receiveReply(reply , MAX_WAIT);
          
          if (received) {
              if (reply.getInfo().valid_data) {
                  System.out.println("Received reply: " + reply.getData().message);
              } else {
                  System.out.println("Received invalid reply");
              }
          } else {
              System.out.println("Reply not received");
          }
          

• Basic Requester example using the String built-in type

          
          // Create a requester using the String 
          // type with the DDS StringTypeSupport
          Requester<String, String> requester = 
                  new Requester<String, String>(
                      new RequesterParams(
                          participant,
                          StringTypeSupport.get_instance(),
                          StringTypeSupport.get_instance())
                      .setServiceName("TestServiceString")
                      .setQosProfile("MyLibrary", "RequesterProfile"));
          
          // Send request
          requester.sendRequest("A request");
          
          // Create reply Sample
          Sample<String> reply = requester.createReplySample();
          
          // Receive reply (wait for it and get the sample)
          boolean received = requester.receiveReply(reply , MAX_WAIT);
          
          if (received && reply.getInfo().valid_data) {
              System.out.println("Received reply: " + reply.getData());
          }
          

• Basic Requester example using DynamicData.

          
          // Instantiate DynamicData type support. For simplicity we create them
          // from existing, generated TypeCode objects (Foo and Bar)
          DynamicDataTypeSupport fooDynamicTypeSupport = new DynamicDataTypeSupport(
                  FooTypeCode.VALUE, new DynamicDataTypeProperty_t());
          DynamicDataTypeSupport barDynamicTypeSupport = new DynamicDataTypeSupport(
                  BarTypeCode.VALUE, new DynamicDataTypeProperty_t());
          
          // Create a requester using a DynamicData type support
          Requester<DynamicData, DynamicData> requester = 
                  new Requester<DynamicData, DynamicData>(
                          participant, "TestService",
                          fooDynamicTypeSupport,
                          barDynamicTypeSupport);
          
          // Create a Foo instance
          DynamicData foo = (DynamicData) fooDynamicTypeSupport.create_data();
          foo.set_string("message", DynamicData.MEMBER_ID_UNSPECIFIED, 
                  "A dynamic request");
          
          // Send request
          requester.sendRequest(foo);
          
          // Create reply Sample
          Sample<DynamicData> reply = requester.createReplySample();
          
          // Receive reply (wait for it and get the sample)
          boolean received = requester.receiveReply(reply , MAX_WAIT);
          
          if (received && reply.getInfo().valid_data) {
              System.out.println("Received reply: " + 
                  reply.getData().get_string("message", DynamicData.MEMBER_ID_UNSPECIFIED));
          }
          

  See also

  Basic Replier example

Taking loaned samples

• Get iterator to loaned replies (no copies)

          
          // Take loaned samples
          // Unlike receiveReplies(), takeReplies() doesn't block. It returns an
          // empty collection if there are no replies at that moment.
          // (before that we can call requester.wait_for_replies)
          Sample.Iterator<Bar> replies = requester.takeReplies();
  
          try {
              while (replies.hasNext()) {
                  Sample<Bar> reply = replies.next();
                  System.out.println("Received: " + reply.getData().message);
              }
          } finally {
              replies.close();
          }
          

  A more compact version using a try-with-resources block (since Java 7):

try (Sample.Iterator<String> replies = requester.getReplies()) {
    while (replies.hasNext()) {
        Sample<String> reply = replies.next();
        System.out.println("Received: " + reply.getData());
    }
}

See also

Basic Requester example

Basic Replier example

Taking samples by copy

Taking samples by copy

• Get copies of the replies:

          
          ArrayList<Sample<Bar>> replies = new ArrayList<Sample<Bar>>();
          
          // Add to existing list, reusing and overwriting any existing elements
          requester.takeReplies(replies, 10);
          for (Sample<Bar> reply : replies) {
              System.out.println("Received: " + reply.getData().message);
          }
                  
          // Get replies in a newly created list
          List<Sample<Bar>> newList = requester.takeReplies(null, 10);
          for (Sample<Bar> reply : newList) {
              System.out.println("Received: " + reply.getData().message);
          }
          

  See also

  Basic Replier example

  Taking loaned samples

Correlating requests and replies

• Creating a Requester
• Example 1) Waiting for a reply for a specific request

          
          // Create requests
          WriteSample<Foo> request1 = requester.createRequestSample();
          request1.getData().message = "Request 1";
          WriteSample<Foo> request2 = requester.createRequestSample();
          request2.getData().message = "Request 2";
          
          // Send requests using WriteSample
          requester.sendRequest(request1);
          requester.sendRequest(request2);
  
          // Wait for a reply to the second request
          Sample<Bar> reply = requester.createReplySample();
          requester.waitForReplies(1, MAX_WAIT, request2.getIdentity());
          requester.takeReply(reply, request2.getIdentity());
          
          assert reply.getRelatedIdentity().equals(request2.getIdentity());
          System.out.println("Received reply: " + reply.getData().message);
  
          // Wait for a reply to the first request
          requester.waitForReplies(1, MAX_WAIT, request1.getIdentity());
          requester.takeReply(reply, request1.getIdentity());
          
          assert reply.getRelatedIdentity().equals(request1.getIdentity());
          System.out.println("Received reply: " + reply.getData().message);
          

• Example 2) Correlate reply after receiving it

          
          // Create requests
          WriteSample<Foo> request1 = requester.createRequestSample();
          request1.getData().message = "Request 1";
          WriteSample<Foo> request2 = requester.createRequestSample();
          request2.getData().message = "Request 2";
          
          // Send requests using WriteSample
          requester.sendRequest(request1);
          requester.sendRequest(request2);
  
          // Wait for two replies
          boolean received = requester.waitForReplies(2, MAX_WAIT);
          if (!received) {
              System.out.println("Replies not received");
              return;
          }
          
          Sample.Iterator<Bar> replies = requester.takeReplies();
          try {
              while(replies.hasNext()) {
                  Sample<Bar> reply = replies.next();
                  if (reply.getRelatedIdentity().equals(
                          request1.getIdentity())) {
                      System.out.println(
                          "Received reply for request 1: " + reply.getData().message);
                  } else if (reply.getRelatedIdentity().equals(
                          request2.getIdentity())) {
                      System.out.println(
                          "Received reply for request 2: " + reply.getData().message);
                  } else {
                      // Should not happen
                      System.out.println("Received unexpected reply");
                  }
              }
          } finally {
              // Return the loan
              replies.close();
          }
          

  See also

  Basic Requester example

  Basic Replier example

Creating a Replier

• Setting up a participant
• Creating a Replier

          
          // Create a DomainParticipant
          DomainParticipant participant = 
                  DomainParticipantFactory.get_instance().create_participant(
                          domain_id, DomainParticipantFactory.PARTICIPANT_QOS_DEFAULT, 
                          null, StatusKind.STATUS_MASK_NONE);
          
          // Create a Replier
          Replier<Foo, Bar> replier = 
                  new Replier<Foo, Bar>(
                          participant, "TestService",
                          FooTypeSupport.get_instance(),
                          BarTypeSupport.get_instance());
          

• Finalizing a Replier

          replier.close();

Basic Replier example

• Creating a Replier
• Basic Replier example

          
          // Create a Sample for reading
          Sample<Foo> request = replier.createRequestSample();
          
          // Receive one request
          boolean received = replier.receiveRequest(request, MAX_WAIT);
          
          if (!received) {
              System.out.println("Request not received");
              return false;
          }
          
          if (request.getInfo().valid_data) {
              // Send a reply for that request
              Bar reply = new Bar();
              reply.message = "Reply for " + request.getData().message;
              replier.sendReply(reply, request.getIdentity());
          }
          
          // Note: a replier can send more than one reply for the same request
          

  See also

  Basic Requester example

SimpleReplier example

• Implement a listener

      class MySimpleReplierListener implements SimpleReplierListener<Foo, Bar> {
  
          private Bar reply = new Bar();
          
          public Bar onRequestAvailable(Sample<Foo> request) {
              if (request.getInfo().valid_data) {
                  // Return a reply
                  reply.message = "Simple reply for " + request.getData().message; 
                  return reply;
              } else {
                  // Do not reply to dispose/unregister samples
                  return null;
              }
          }
  
          public void returnLoan(Bar reply) {
              // nothing to do
          }
          
      }

• And create a SimpleReplier with the listener:

          
          // Create a SimpleReplier using a DomainParticipant, service name and
          // the a SimpleReplierListener implementation
          SimpleReplier<Foo, Bar> replier = 
                  new SimpleReplier<Foo, Bar>(
                          participant, "TestService",
                          new MySimpleReplierListener(),
                          FooTypeSupport.get_instance(), 
                          BarTypeSupport.get_instance());
          
          // After creation the SimpleReplier is already active and may call
          // the listener
          

  See also

  Basic Requester example

Error handling example

• Catching an exception from the request-reply API

  
          // All the operations in the request-reply API
          // throw exceptions in case of error.
  
          // You can also set the verbosity level to warning for
          // additional information
          Logger.get_instance().set_verbosity(
                  LogVerbosity.NDDS_CONFIG_LOG_VERBOSITY_WARNING);
  
  
          //
          // For example, this replier is sending a reply for a nonexistent request
          //
          WriteSample<Bar> reply = replier.createReplySample();
          SampleIdentity_t invalidRequestId = new SampleIdentity_t();
          
          
          try {
              replier.sendReply(reply, invalidRequestId);
          } catch (RETCODE_BAD_PARAMETER ex) { 
              // You can also catch RETCODE_ERROR, which is more generic
              System.out.println("Exception while sending reply: " + ex);
          }
  

Configuring Request-Reply QoS profiles

If you do not specify your own quality of service parameters (in com.rti.connext.requestreply.RequesterParams and com.rti.connext.requestreply.ReplierParams<TReq,TRep>), a com.rti.connext.requestreply.Requester<TReq,TRep> and com.rti.connext.requestreply.Replier<TReq,TRep> are created using a default configuration. That configuration is equivalent to the one in the following QoS profile called "default":

<?xml version="1.0"?>
<!-- 
Description
XML QoS Profile for HelloWorld

(c) Copyright, Real-Time Innovations, 2012.  All rights reserved.
RTI grants Licensee a license to use, modify, compile, and create derivative
works of the software solely for use with RTI Connext DDS. Licensee may
redistribute copies of the software provided that all such copies are
subject to this license. The software is provided "as is", with no warranty
of any type, including any warranty for fitness for any purpose. RTI is
under no obligation to maintain or support the software. RTI shall not be
liable for any incidental or consequential damages arising out of the use
or inability to use the software.

The QoS configuration of the DDS entities in the generated example is loaded 
from this file.

This file is used only when it is in the current working directory or when the
environment variable NDDS_QOS_PROFILES is defined and points to this file.

The profile in this file inherits from the builtin QoS profile 
BuiltinQosLib::Generic.StrictReliable. That profile, along with all of the 
other built-in QoS profiles can be found in the 
BuiltinProfiles.documentationONLY.xml file located in the 
$NDDSHOME/resource/xml/ directory.

You may use any of these QoS configurations in your application simply by 
referring to them by the name shown in the 
BuiltinProfiles.documentationONLY.xml file.

Also, following the QoS Profile composition pattern you can use QoS Snippets
to easily create your final QoS Profile. For further information visit:
https://community.rti.com/best-practices/qos-profile-inheritance-and-composition-guidance

There is a QoS Snippet library that contains a collection of
QoS Snippets that set some specific features or configurations. You can find
them in the BuiltinProfiles.documentationONLY.xml file as well.

You should not edit the file BuiltinProfiles.documentationONLY.xml directly.
However, if you wish to modify any of the values in a built-in profile, the
recommendation is to create a profile of your own and inherit from the built-in
profile you wish to modify. The NDDS_QOS_PROFILES.example.xml file (contained in 
the same directory as the BuiltinProfiles.documentationONLY.xml file) shows how
to inherit from the built-in profiles. 

For more information about XML QoS Profiles see the "Configuring QoS with
XML" chapter in the RTI Connext DDS Core Libraries User's Manual.
-->

<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="file:////rti/jenkins/workspace/connextdds_htmldocs_release_connextdrive_3.0.0/build/nddsgen.2.0/resource/schema/rti_dds_qos_profiles.xsd">
    <!-- QoS Library containing the QoS profile used in the generated example.

        A QoS library is a named set of QoS profiles.
    -->
    <qos_library name="HelloWorld_Library">

        <!-- QoS profile used to configure reliable communication between the DataWriter 
             and DataReader created in the example code.

             A QoS profile groups a set of related QoS.
        -->
        <qos_profile name="HelloWorld_Profile" base_name="BuiltinQosLib::Generic.StrictReliable" is_default_qos="true">
            <!-- QoS used to configure the data writer created in the example code -->                
            <datawriter_qos>
                <publication_name>
                    <name>HelloWorldDataWriter</name>
                </publication_name>
            </datawriter_qos>

            <!-- QoS used to configure the data reader created in the example code -->                
            <datareader_qos>
                <subscription_name>
                    <name>HelloWorldDataReader</name>
                </subscription_name>
            </datareader_qos>
            <domain_participant_qos>
                <!--
                The participant name, if it is set, will be displayed in the
                RTI tools, making it easier for you to tell one
                application from another when you're debugging.
                -->
                <participant_name>
                    <name>HelloWorldParticipant</name>
                    <role_name>HelloWorldParticipantRole</role_name>
                </participant_name>

            </domain_participant_qos>
        </qos_profile>

    </qos_library>
</dds>

You can use the profile called "RequesterExampleProfile", which modifies some parameters from the default. The example Creating a Requester with optional parameters shows how to create a com.rti.connext.requestreply.Requester<TReq,TRep> using this profile.

See also

Creating a Requester with optional parameters

Configuring QoS Profiles with XML