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

// $Id$

#ifndef CCM_DDS_BASE_IDL
#define CCM_DDS_BASE_IDL

#include  <Components.idl>
#include "connectors/dds4ccm/idl/dds4ccm_DataListenerControl.idl"
#include "connectors/dds4ccm/idl/dds4ccm_StateListenerControl.idl"
#include "connectors/dds4ccm/idl/dds4ccm_PortStatusListener.idl"
#include "connectors/dds4ccm/idl/dds4ccm_ConnectorStatusListener.idl"
#include "connectors/dds4ccm/idl/dds4ccm_Connector.idl"

module CCM_DDS
{
  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;
                };
        };
};

#endif