path: root/modules/CIAO/connectors/dds4ccm/docs/ccm_dds.idl

// $Id$

#include "dds_rtf2_dcps.idl"

module CCM_DDS {

        // ===================================================================================
        // Non-typed part
        //      (here are placed all the constructs that are not dependent on the data type)
        // ===================================================================================
        // ---------------------------
        // Enums, structs and Typedefs
        // ---------------------------
        typedef unsigned long                   DataNumber_t;   // count or index of data
        typedef sequence<DataNumber_t>          DataNumberSeq;

        const DataNumber_t UNLIMITED = 0;

        enum AccessStatus {
                FRESH_INFO,
                ALREADY_SEEN
                };

        enum InstanceStatus {           // at sample time, as perceived by the component
                INSTANCE_CREATED,
                INSTANCE_FILTERED_IN,
                INSTANCE_UPDATED,
                INSTANCE_FILTERED_OUT,
                INSTANCE_DELETED
                };

        struct ReadInfo {
                DDS::InstanceHandle_t           instance_handle;
                DDS::Time_t                     source_timestamp;
                AccessStatus                    access_status;
                InstanceStatus                  instance_status;
                };
        typedef sequence<ReadInfo>              ReadInfoSeq;

        struct QueryFilter {
                string                          query;
                DDS::StringSeq                  query_parameters;
                };

        // Data Listener control
        // ---------------------
        enum ListenerMode {
                NOT_ENABLED,
                ONE_BY_ONE,
                MANY_BY_MANY
                };

        // ----------
        // Exceptions
        // ----------
        exception AlreadyCreated {
                DataNumberSeq indexes;  // of the erroneous
                };

        exception NonExistent{
                DataNumberSeq indexes;  // of the erroneous
                };

        exception InternalError{
                DDS::ReturnCode_t error_code;   // DDS codes that are relevant:
                                                // ERROR (1);
                                                // UNSUPPORTED (2);
                                                // BAD_PARAMETER (3)
                                                // PRECONDITION_NOT_MET (4)
                                                // OUT_OF_RESOURCE (5)
                DataNumber_t index;             // of the erroneous
                };

        exception NonChangeable {};

        // ----------
        // Interfaces
        // ----------

        // Listener Control
        // ----------------
        local interface DataListenerControl {
                attribute ListenerMode          mode;                   // default NOT_ENABLED
                attribute DataNumber_t          max_delivered_data;     // default 0 (no limit)
                };

        local interface StateListenerControl : DataListenerControl {
                attribute boolean               is_filter_interpreted;  // default FALSE
                };

        // Status Access
        // -------------
        local interface PortStatusListener {    // status that are relevant to the component
                void on_requested_deadline_missed(
                        in DDS::DataReader                      the_reader,
                        in DDS::RequestedDeadlineMissedStatus   status);
                void on_sample_lost(
                        in DDS::DataReader                      the_reader,
                        in DDS::SampleLostStatus                status);
                };

        local interface ConnectorStatusListener { // status that are relevant system-wide
                void on_inconsistent_topic(
                        in DDS::Topic                           the_topic,
                        in DDS::InconsistentTopicStatus         status);
                void on_requested_incompatible_qos(
                        in DDS::DataReader                      the_reader,
                        in DDS::RequestedIncompatibleQosStatus  status);
                void on_sample_rejected(
                        in DDS::DataReader                      the_reader,
                        in DDS::SampleRejectedStatus            status);
                void on_offered_deadline_missed(
                        in DDS::DataWriter                      the_writer,
                        in DDS::OfferedDeadlineMissedStatus     status);
                void on_offered_incompatible_qos(
                        in DDS::DataWriter                      the_writer,
                        in DDS::OfferedIncompatibleQosStatus    status);
                void on_unexpected_status (
                        in DDS::Entity                          the_entity,
                        in DDS::StatusKind                      status_kind);
                };

        // ---------------
        // Connector bases
        // ---------------
        connector DDS_Base {
                uses ConnectorStatusListener                    error_listener;
                attribute DDS::DomainId_t                       domain_id
                        setraises (NonChangeable);
                attribute string                                qos_profile     // File URL or XML string
                        setraises (NonChangeable);
                };

        connector DDS_TopicBase : DDS_Base {
                attribute string                                topic_name
                        setraises (NonChangeable);
                attribute DDS::StringSeq                        key_fields
                        setraises (NonChangeable);
                };

        // ===================================================================================
        // Typed sub-part
        //      (here are placed all the construct that are depending on the data type
        //       either directly or indirectly)
        // ===================================================================================

        module Typed <typename T, sequence<T> TSeq> {
        // Gathers all the constructs that are dependent on the data type (T),
        // either directly -- interfaces making use of T or TSeq,
        // or indirectly -- porttypes using or providing those intefaces.
        // TSeq is passed as a second parameter to avoid creating a new sequence type.

                // -------------------------------------
                // Interfaces to be 'used' or 'provided'
                // -------------------------------------

                // Data access - publishing side
                // -----------------------------

                // -- InstanceHandle Manager
                abstract interface InstanceHandleManager {
                        DDS::InstanceHandle_t register_instance (in T datum)
                                raises (InternalError);
                        void unregister_instance (in T datum, in DDS::InstanceHandle_t instance_handle)
                                raises (InternalError);
                        };

                // -- Writer: when the instance lifecycle is not a concern
                local interface Writer : InstanceHandleManager {
                        void write_one (in T datum, in DDS::InstanceHandle_t instance_handle)
                                raises (InternalError);
                        void write_many (in TSeq data)
                                raises (InternalError);
                        attribute boolean is_coherent_write;            // FALSE by default
                        // behavior
                        // ---------
                        // - the handle is exactly managed as by DDS (cf. DDS spec for more details)
                        // - attempt to write_many is stopped at the first error
                        // - if is_coherent_write, DDS write orders issued by a write_many
                        //       are placed between begin/end coherent updates (even if an error occurs)
                        };

                // -- Updater: when the instance lifecycle is a concern
                local interface Updater : InstanceHandleManager {
                        void create_one (in T datum)
                                raises (AlreadyCreated,
                                        InternalError);
                        void update_one (in T datum, in DDS::InstanceHandle_t instance_handle)
                                raises (NonExistent,
                                        InternalError);
                        void delete_one (in T datum,in DDS::InstanceHandle_t instance_handle)
                                raises (NonExistent,
                                        InternalError);

                        void create_many (in TSeq data)
                                raises (AlreadyCreated,
                                        InternalError);
                        void update_many (in TSeq data)
                                raises (NonExistent,
                                        InternalError);
                        void delete_many (in TSeq data)
                                raises (NonExistent,
                                        InternalError);

                        readonly attribute boolean is_global_scope;                     // FALSE by default
                        attribute boolean is_coherent_write;                            // FALSE by default

                        // behavior
                        // --------
                        // - the handle is exactly managed as by DDS (cf. DDS spec for more details)
                        // - exceptions AlreadyCreated or NonExistent are raised at least if a local
                        //       conflict exists; in addition if is_global_scope is true, the test on
                        //       existence attempts to take into account the instances created outside
                        //              - note: this check requires to previously attempt to read (not free)
                        //              - note: this check is not 100% guaranteed as a creation or a deletion
                        //                may occur in the short time between the check and the DDS order
                        // - For *-many operations:
                        //              - global check is performed before actual write or dispose
                        //                (in case of error, all the erroneous instances are reported
                        //                in the exception)
                        //              - attempt to DDS write or dispose is stopped at the first error
                        //              - if is_coherent_write, DDS orders resulting from a *_many operation
                        //                are placed between begin/end coherent updates (even if an error
                        //                occurs)
                        };

                // Data access - subscribing side
                // ------------------------------

                // -- Reader: to simply access to the available data (no wait)
                local interface Reader {
                        void read_last (out TSeq data, out ReadInfoSeq infos)
                                raises (InternalError);
                        void read_all (out TSeq data, out ReadInfoSeq infos)
                                raises (InternalError);
                        void read_one_last (inout T datum, out ReadInfo info,
                                        in DDS::InstanceHandle_t instance_handle)
                                raises (NonExistent,
                                        InternalError);
                        void read_one_all (in T datum, out TSeq data, out ReadInfoSeq infos,
                                        in DDS::InstanceHandle_t instance_handle)
                                raises (NonExistent,
                                        InternalError);
                        attribute QueryFilter filter
                                setraises (InternalError);
                        // behavior
                        // --------
                        // - read operations are performed with the following parameters
                        //              - READ or NO_READ
                        //              - NEW or NOT_NEW
                        //              - ALIVE
                        //              - through the query as specified in the filter ("" means no query)
                        // - data returned:
                        //              - read_last returns for each living instance, its last sample
                        //              - read_all returns all the samples of all instances
                        //                ordered by instance first and then by sample
                        //              - read_one_last returns the last sample of the given instance
                        //              - read_one_all returns all the samples for the given instance
                        //      - read_one operations use the instance_handle the same way
                        //        the Writer or Updater *_one operations do
                        };

                // -- Getter: to get new data (and wait for)
                local interface Getter {
                        boolean get_one (out T datum, out ReadInfo info)
                                raises (InternalError);
                        boolean get_many (out TSeq data, out ReadInfoSeq infos)
                                raises (InternalError);
                        attribute DDS::Duration_t time_out;
                        attribute DataNumber_t    max_delivered_data;     // default 0 (no limit)
                        // behavior
                        // --------
                        // - get operations are performed with the following parameters
                        //              - NO_READ
                        //              - NEW or NOT_NEW
                        //              - ALIVE or NOT_ALIVE
                        //              - through the query as specified in the associated Reader
                        //              - within the time limit specified in time_out
                        // - all operations returns TRUE if data are provided
                        //       or FALSE if time-out occurred
                        // - data returned:
                        //              - get_one returns each read sample one by one
                        //      - get_many returns all available samples within the
                        //                max_delivered_data limit
                        };

                // -- Listener: similar to a Getter but in push mode
                local interface Listener {
                        void on_one_data (in T datum, in ReadInfo info);
                        void on_many_data (in TSeq data, in ReadInfoSeq infos);
                        // behavior
                        // --------
                        // - on_one_data() trigered is the mode of the associated listener control
                        //       is ONE_BY_ONE (then similar to a get_one(), except that in push mode
                        //       instead of pull mode)
                        // - on_many_data() triggered if the listener mode is MANY_BY_MANY (then
                        //       similar to get_many() but in push mode)
                        // - query filter (if any) in the associated Reader
                        };

                // -- StateListener: listener to be notified based on the instance lifecycle
                local interface StateListener {
                        void on_creation (in T datum, in ReadInfo info);
                        void on_one_update (in T datum, in ReadInfo info);
                        void on_many_updates (in TSeq data, in ReadInfoSeq infos);
                        void on_deletion (in T datum, in ReadInfo info);
                        // behavior
                        // --------
                        // - no operations are trigerred if the mode of the associated listener
                        //       control is NOT_ENABLED
                        // - on_creation() is triggered if the instance is considered as new in the
                        //       component scope; note that in case there is a filter and the attribute
                        //       is_filter_interpreted of the listener control is TRUE, this gathers also
                        //       the case when the instance is filtered-in.
                        // - on_delation() is triggered if the instance is no more existing; note
                        //       that in case there is a filter  and the attribute
                        //       is_filter_interpreted of the listener control is TRUE, this gathers
                        //       also the case when the instance is filtered-out
                        // - on_one_update() is trigrered if neither on_creation() nor on_deletion()
                        //       are triggered and the mode of the associated listener control is
                        //       ONE_BY_ONE
                        // - on_many_updates()is triggered if neither on_creation() nor on_deletion()
                        //       are triggered and the mode of the associated listener control is
                        //       MANY_BY_MANY; the number of returned samples is within the limits of
                        //       max_delivered_data attribute of the associated listener control.
                        // - query filter (if any) in the associated Reader
                        };


                // ---------
                // DDS Ports
                // ---------

                porttype DDS_Write {
                        uses Writer                     data;
                        uses DDS::DataWriter            dds_entity;
                        };

                porttype DDS_Update {
                        uses Updater                    data;
                        uses DDS::DataWriter            dds_entity;
                        };

                porttype DDS_Read {
                        uses Reader                     data;
                        uses DDS::DataReader            dds_entity;
                        provides PortStatusListener     status;
                        };

                porttype DDS_Get {
                        uses Reader                     data;
                        uses Getter                     fresh_data;
                        uses DDS::DataReader            dds_entity;
                        provides PortStatusListener     status;
                        };

                porttype DDS_Listen {
                        uses Reader                     data;
                        uses DataListenerControl        data_control;
                        provides Listener               data_listener;
                        uses DDS::DataReader            dds_entity;
                        provides PortStatusListener     status;
                        };

                porttype DDS_StateListen {
                        uses Reader                     data;
                        uses StateListenerControl       data_control;
                        provides StateListener          data_listener;
                        uses DDS::DataReader            dds_entity;
                        provides PortStatusListener     status;
                        };

                // ----------------------------
                // Connectors
                // (Correspond to DDS patterns)
                // ----------------------------

                connector DDS_State : DDS_TopicBase {
                        mirrorport DDS_Update           observable;
                        mirrorport DDS_Read             passive_observer;
                        mirrorport DDS_Get              pull_observer;
                        mirrorport DDS_Listen           push_observer;
                        mirrorport DDS_StateListen      push_state_observer;
                        };

                connector DDS_Event : DDS_TopicBase {
                        mirrorport DDS_Write            supplier;
                        mirrorport DDS_Get              pull_consumer;
                        mirrorport DDS_Listen           push_consumer;
                        };
                };
        };