com.toc.coredx.DDS
Class FooDataReader

java.lang.Object
  com.toc.coredx.DDS.Entity
      com.toc.coredx.DDS.DomainEntity
          com.toc.coredx.DDS.DataReader
              com.toc.coredx.DDS.FooDataReader

public class FooDataReader
extends DataReader

The FooDataReader is an example specialized DataReader (generated by the coredx_ddl compiler) for reading data samples of type 'Foo'. The FooDataReader is an implementation of the base DataReader class that has been extended to support the 'Foo' data type.

Note: the FooDataReader is included here for documentation purposes only, and does not really exist in the com.toc.coredx.DDS package.

Constructor Summary

FooDataReader()

Method Summary

ReturnCode_t	get_key_value(Foo key_holder, InstanceHandle_t handle) This routine will populate the data structure indicated by key_holder with the key infomation identified by handle.
InstanceHandle_t	lookup_instance(Foo instance_data) Returns the handle that identifies the data instance provided in instance_data. The 'key' field values of the data are associated with a unique handle.
ReturnCode_t	read_instance(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, InstanceHandle_t handle, long sample_states, long view_states, long instance_states) This operation accesses a collection of data values (with associated SampleInfo), belonging to a particular instance, within the DataReader.
ReturnCode_t	read_next_instance_w_condition(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, InstanceHandle_t handle, ReadCondition condition) This operation accesses a collection of data values (with associated SampleInfo), instance by instance subject to a filter, within the DataReader.
ReturnCode_t	read_next_instance(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, InstanceHandle_t prev_handle, long sample_states, long view_states, long instance_states) This operation accesses a collection of data values (with associated SampleInfo), instance by instance, within the DataReader.
ReturnCode_t	read_next_sample(Foo received_data, SampleInfo sample_info) This operation accesses a data value (with associated SampleInfo) within the DataReader.
ReturnCode_t	read_w_condition(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, ReadCondition condition) This operation accesses a collection of data values (with associated SampleInfo), subject to a filter, within the DataReader.
ReturnCode_t	read(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, long sample_states, long view_states, long instance_states) This operation accesses a collection of data values (with associated SampleInfo) within the DataReader.
ReturnCode_t	return_loan(FooSeq received_data, SampleInfoSeq sample_infos) Returns data and sample_info values to a DataReader.
ReturnCode_t	take_instance(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, InstanceHandle_t handle, long sample_states, long view_states, long instance_states) This operation takes a collection of data values (with associated SampleInfo), belonging to a particular instance, from the DataReader.
ReturnCode_t	take_next_instance_w_condition(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, InstanceHandle_t handle, ReadCondition condition) This operation takes a collection of data values (with associated SampleInfo), instance by instance subject to a filter, from the DataReader.
ReturnCode_t	take_next_instance(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, InstanceHandle_t prev_handle, long sample_states, long view_states, long instance_states) This operation takes a collection of data values (with associated SampleInfo), instance by instance, from the DataReader.
ReturnCode_t	take_next_sample(Foo received_data, SampleInfo sample_info) This operation takes a data value (with associated SampleInfo) from the DataReader.
ReturnCode_t	take_w_condition(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, ReadCondition condition) This operation takes a collection of data values (with associated SampleInfo), subject to a filter, from the DataReader.
ReturnCode_t	take(FooSeq received_data, SampleInfoSeq sample_infos, int max_samples, long sample_states, long view_states, long instance_states) This operation takes a collection of data values (with associated SampleInfo) from the DataReader.

Methods inherited from class com.toc.coredx.DDS.DataReader

create_querycondition, create_readcondition, delete_contained_entities, delete_readcondition, enable, get_listener, get_liveliness_changed_status, get_matched_publication_data, get_matched_publications, get_qos, get_requested_deadline_missed_status, get_requested_incompatible_qos_status, get_sample_lost_status, get_sample_rejected_status, get_subscriber, get_subscription_matched_status, get_topicdescription, set_listener, set_qos, wait_for_historical_data

Methods inherited from class com.toc.coredx.DDS.Entity

get_instance_handle, get_status_changes, get_statuscondition

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FooDataReader

public FooDataReader()

Method Detail

get_key_value

public ReturnCode_t get_key_value(Foo key_holder,
                                  InstanceHandle_t handle)

This routine will populate the data structure indicated by key_holder with the key infomation identified by handle.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

lookup_instance

public InstanceHandle_t lookup_instance(Foo instance_data)

Returns the handle that identifies the data instance provided in instance_data. The 'key' field values of the data are associated with a unique handle.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

return_loan

public ReturnCode_t return_loan(FooSeq received_data,
                                SampleInfoSeq sample_infos)

Returns data and sample_info values to a DataReader. When an application calls DataReader read() or take() operations, these routines 'loan' data and SampleInfo values to the application. [This is an optimization that avoids extra copies of data.] The appliction must return this 'loaned' data to the DataReader. The return_loan() routine indicates to the DataReader that the application no longer requires access to the data and sample_infos.

A call to return_loan() operation must be made only if previous read() or take() calls 'loaned' data to the application. See read() for a discussion of when data is 'loaned'.

If the received_data or sample_infos parameters provided do not identify data obtained from DataReader dr, then the error RETCODE_PRECONDITION_NOT_MET will be returned.

A DataReader cannot be deleted if any 'loans' are outstanding.

See Also:

read()

read

public ReturnCode_t read(FooSeq received_data,
                         SampleInfoSeq sample_infos,
                         int max_samples,
                         long sample_states,
                         long view_states,
                         long instance_states)

This operation accesses a collection of data values (with associated SampleInfo) within the DataReader. This routine, and the related take(), provide the interface for an application to access published data. There are several varieties of read() and take(), to facilitate different access patterns or approaches.

The primary difference between read() and take() is that take() removes all returned data samples from the DataReader while read() does not. Sequential read() calls will return the same data samples each time (if nothing else changes); while sequential take() calls will return data samples for only the first call. Subsequent take() calls will return an empty collection (if no new data arrives).

The specific behavior of read() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data. First, the received_data and sample_infos arguments affect the following:

• how many samples are returned, and
• whether the returned data should be 'loaned' or copied.

The argument max_samples is used to further limit the number of samples returned.

The sample_states, view_states, and instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired 'states' for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special 'ANY' constants (e.g.: DDS.ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection.

The order of samples in the returned collections is determined by the PRESENTATION and DESTINATION_ORDER QoS policies.

The returned collection is held in recieved_data and samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in received_data has a corresponding entry in sample_infos that provides associated 'meta-data'. See SampleInfo for a description of this meta-data.

In CoreDX DDS, the returned sequences contain 'loaned' data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is 'loaned' to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling return_loan().

The read() operation will set the SampleInfo.sample_state to DDS.READ_SAMPLE_STATE.

The read() operation may set the SampleInfo.view_state to DDS.NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is read.

If there is no data found, then the read() will return RETCODE_NO_DATA.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

take

public ReturnCode_t take(FooSeq received_data,
                         SampleInfoSeq sample_infos,
                         int max_samples,
                         long sample_states,
                         long view_states,
                         long instance_states)

This operation takes a collection of data values (with associated SampleInfo) from the DataReader. This routine, and the related read(), provide the interface for an application to access published data. There are several varieties of read() and take(), to facilitate different access patterns or approaches.

The primary difference between read() and take() is that take() removes all returned data samples from the DataReader while read() does not. Sequential read() calls will return the same data samples each time (if nothing else changes); while sequential take() calls will return data samples for only the first call. Subsequent take() calls will return an empty collection (if no new data arrives).

The specific behavior of take() depends on several things: input paramters, the QoS settings of the DataReader, and the state of recieved data. First, the received_data and sample_infos arguments affect the following:

• how many samples are returned, and
• whether the returned data should be 'loaned' or copied.

The argument max_samples is used to further limit the number of samples returned.

The sample_states, view_states, and instance_states arguments are used to selectively add data samples to the returned collections. These arguments indicate the desired 'states' for data samples and instances. These state arguments are bit masks; they can be the bit-wise OR of several individual state flags or they may use the special 'ANY' constants (e.g.: DDS.ANY_SAMPLE_STATE). Only samples that have a matching state for all three categories are added to the returned collection.

The order of samples in the returned collections is determined by the PRESENTATION and DESTINATION_ORDER QoS policies.

The returned collection is held in recieved_data and samples_infos. These two sequences operate together to represent a sequence of pairs (data, SampleInfo). Each data item in received_data has a corresponding entry in sample_infos that provides associated 'meta-data'. See SampleInfo for a description of this meta-data.

In CoreDX DDS, the returned sequences contain 'loaned' data. This provides zero-copy access to the data, and provides a very efficient data access mechanism. Becuase the data is 'loaned' to the application, the application is required to indicate when it is finished accessing the data. This is accomplished by calling return_loan().

The take() operation will set the SampleInfo.sample_state to DDS.READ_SAMPLE_STATE.

The take() operation may set the SampleInfo.view_state to DDS.NOT_NEW_VIEW_STATE, if a sample of the most recent generation of the instance is taken.

If there is no data found, then the take() will return RETCODE_NO_DATA.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

read_w_condition

public ReturnCode_t read_w_condition(FooSeq received_data,
                                     SampleInfoSeq sample_infos,
                                     int max_samples,
                                     ReadCondition condition)

This operation accesses a collection of data values (with associated SampleInfo), subject to a filter, within the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

read()

take_w_condition

public ReturnCode_t take_w_condition(FooSeq received_data,
                                     SampleInfoSeq sample_infos,
                                     int max_samples,
                                     ReadCondition condition)

This operation takes a collection of data values (with associated SampleInfo), subject to a filter, from the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

take()

read_next_sample

public ReturnCode_t read_next_sample(Foo received_data,
                                     SampleInfo sample_info)

This operation accesses a data value (with associated SampleInfo) within the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

read()

take_next_sample

public ReturnCode_t take_next_sample(Foo received_data,
                                     SampleInfo sample_info)

This operation takes a data value (with associated SampleInfo) from the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

take()

read_instance

public ReturnCode_t read_instance(FooSeq received_data,
                                  SampleInfoSeq sample_infos,
                                  int max_samples,
                                  InstanceHandle_t handle,
                                  long sample_states,
                                  long view_states,
                                  long instance_states)

This operation accesses a collection of data values (with associated SampleInfo), belonging to a particular instance, within the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

read()

take_instance

public ReturnCode_t take_instance(FooSeq received_data,
                                  SampleInfoSeq sample_infos,
                                  int max_samples,
                                  InstanceHandle_t handle,
                                  long sample_states,
                                  long view_states,
                                  long instance_states)

This operation takes a collection of data values (with associated SampleInfo), belonging to a particular instance, from the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

take()

read_next_instance

public ReturnCode_t read_next_instance(FooSeq received_data,
                                       SampleInfoSeq sample_infos,
                                       int max_samples,
                                       InstanceHandle_t prev_handle,
                                       long sample_states,
                                       long view_states,
                                       long instance_states)

This operation accesses a collection of data values (with associated SampleInfo), instance by instance, within the DataReader. To start,pass HANDLE_NIL for parameter prev_handle. After the last instance (in order) has been taken, this routine will return RETCODE_NO_DATA.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

read()

take_next_instance

public ReturnCode_t take_next_instance(FooSeq received_data,
                                       SampleInfoSeq sample_infos,
                                       int max_samples,
                                       InstanceHandle_t prev_handle,
                                       long sample_states,
                                       long view_states,
                                       long instance_states)

This operation takes a collection of data values (with associated SampleInfo), instance by instance, from the DataReader. To start,pass HANDLE_NIL for parameter prev_handle. After the last instance (in order) has been taken, this routine will return RETCODE_NO_DATA.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

take()

read_next_instance_w_condition

public ReturnCode_t read_next_instance_w_condition(FooSeq received_data,
                                                   SampleInfoSeq sample_infos,
                                                   int max_samples,
                                                   InstanceHandle_t handle,
                                                   ReadCondition condition)

This operation accesses a collection of data values (with associated SampleInfo), instance by instance subject to a filter, within the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

read()

take_next_instance_w_condition

public ReturnCode_t take_next_instance_w_condition(FooSeq received_data,
                                                   SampleInfoSeq sample_infos,
                                                   int max_samples,
                                                   InstanceHandle_t handle,
                                                   ReadCondition condition)

This operation takes a collection of data values (with associated SampleInfo), instance by instance subject to a filter, from the DataReader.

This routine is data type specific. The generated type specific DataReader includes an implementation of this routine which should be used to support type-safety.

See Also:

take()