DataReader Use Cases
[Programming How-To's]

Working with data readers. More...

Setting up a data reader

• Set up subscriber

• Set up a topic

• Create a data reader, FooDataReader, of user data type Foo:

    DataReaderQos reader_qos = new DataReaderQos();
  
    // MyReaderListener is user defined and 
    // implements DataReaderListener
    DataReaderListener reader_listener
        = new MyReaderListener(); // or = null
  
    subscriber.get_default_datareader_qos(reader_qos);
  
    FooDataReader reader = null;
    try {
        reader = (FooDataReader) subscriber.create_datareader(topic,
                                                              reader_qos,
                                                              reader_listener,
                                                              StatusKind.STATUS_MASK_ALL);
    } catch (RETCODE_ERROR err) {
        // respond to exception
    }
  

Managing instances

• Given a data reader

   FooDataReader reader = ...;
  

• Getting an instance "key" value of user data type Foo

    Foo data = new Foo();     // user data of type Foo
    // ...
    try {
        reader.get_key_value(data, instance_handle);
    } catch (RETCODE_ERROR err) {
        // ... check for cause of failure
    }    
  

Set up reader to access received data

• Set up data reader

• Set up to handle the DATA_AVAILABLE_STATUS status, in one or both of the following two ways.

• Enable DATA_AVAILABLE_STATUS for the DataReaderListener associated with the data reader
  • The processing to handle the status change is done in the com.rti.dds.subscription.DataReaderListener.on_data_available method of the attached listener.
  • Typical processing will access the received data.

• Enable DATA_AVAILABLE_STATUS for the StatusCondition associated with the data reader
  • The processing to handle the status change is done when the data reader's attached status condition is triggered and the DATA_AVAILABLE_STATUS status on the data reader is changed.
  • Typical processing will access the received data.

Access received data via a reader

• Ensure reader is set up to access received data

• Access the received data, by either:
  • Taking the received data in the reader, OR
  • Reading the received data in the reader

Taking data

• Ensure reader is set up to access received data

• Take samples of user data type Foo. The samples are removed from the Service. The caller is responsible for deallocating the buffers.

    FooSeq        data_seq = new FooSeq();        // holder for sequence of user data type Foo
    SampleInfoSeq info_seq = new SampleInfoSeq(); // holder for sequence of DDS_SampleInfo
    int           max_samples;
    int           sample_state_mask = SampleStateMask.ANY_SAMPLE_STATE;
    int           view_state_mask = ViewStateMask.ANY_VIEW_STATE;
    int           instance_state_mask = InstanceStateMask.ANY_INSTANCE_STATE;
  
    try {  
        reader.take(data_seq, info_seq, 
                    max_samples,
                    sample_state_mask, 
                    view_state_mask,
                    instance_state_mask); 
    } catch (RETCODE_ERROR) {
        // ... check for cause of failure
    }
  

• Use the received data

    // Use the received data samples 'data_seq' and associated 
    // information 'info_seq'
    for (int i = 0; i < data_seq.size(); ++i) {
        // use... data_seq.get(i) ...
        // use... info_seq.get(i) ...
    }
  

• Return the data samples and the information buffers back to the middleware. IMPORTANT: Once this call returns, you must not retain any pointers to any part of any sample or sample info object.

    reader.return_loan(data_seq, info_seq); 
  

Reading data

• Ensure reader is set up to access received data

• Read samples of user data type Foo. The samples are not removed from the Service. It remains responsible for deallocating the buffers.

    FooSeq        data_seq = new FooSeq();        // holder for sequence of user data type Foo
    SampleInfoSeq info_seq = new SampleInfoSeq)_; // holder for sequence of DDS_SampleInfo
    int           max_samples;
    int           sample_state_mask = SampleStateMask.ANY_SAMPLE_STATE;
    int           view_state_mask = ViewStateMask.ANY_VIEW_STATE;
    int           instance_state_mask = InstanceStateMask.ANY_INSTANCE_STATE;
  
    try {  
        reader.read(data_seq, info_seq, 
                    max_samples,
                    sample_state_mask, 
                    view_state_mask,
                    instance_state_mask); 
    } catch (RETCODE_ERROR) {
        // ... check for cause of failure
    }
  

• Use the received data

    // Use the received data samples 'data_seq' and associated 
    // information 'info_seq'
    for (int i = 0; i < data_seq.size(); ++i) {
        // use... data_seq.get(i) ...
        // use... info_seq.get(i) ...
    }
  

• Return the data samples and the information buffers back to the middleware

    reader.return_loan(data_seq, info_seq); 
  

Tearing down a data reader

• Delete DDSDataReader:

    try {
        subscriber.delete_datareader(reader);
    } catch (RETCODE_ERROR err) {
        // ... check for cause of failure
    }