#include "dds_dcps.idl"

module DDS {


// Type definitions
// =================

// Scope of action
// ---------------

enum ReferenceScope {
	SIMPLE_CONTENT_SCOPE,           // only the reference content
	REFERENCED_CONTENTS_SCOPE       // + referenced contents
	};

enum ObjectScope {
	SIMPLE_OBJECT_SCOPE,            // only the object
	CONTAINED_OBJECTS_SCOPE,        // + contained objects
	RELATED_OBJECTS_SCOPE           // + all related objects
	};

// State of the underlying infrastructure
// --------------------------------------

enum DCPSState {
    INITIAL,
    REGISTERED,
    ENABLED
    };

// Usage of the Cache
// ------------------

enum CacheUsage {
    READ_ONLY,
    WRITE_ONLY,
    READ_WRITE
    };

// States of an object
// -------------------

typedef unsigned short ObjectSubState;

// Primary object state
const ObjectSubState OBJECT_NEW        = 0x0001 << 0;
const ObjectSubState OBJECT_MODIFIED   = 0x0001 << 1;
const ObjectSubState OBJECT_READ       = 0x0001 << 2;
const ObjectSubState OBJECT_DELETED    = 0x0001 << 3;

// Secondary object state 
const ObjectSubState OBJECT_CREATED    = 0x0001 << 8;
const ObjectSubState OBJECT_CHANGED    = 0x0001 << 9;
const ObjectSubState OBJECT_WRITTEN    = 0x0001 << 10;
const ObjectSubState OBJECT_DESTROYED  = 0x0001 << 11;


// OID
// ---

struct DLRLOid {
    unsigned long creator_id;
    unsigned long local_id;
    };

// Time-out
// --------

typedef long TimeOutDuration;
const TimeOutDuration INFINITE_TIME_OUT = -1;


// Miscellanous
// ------------

typedef sequence<long>      LongSeq;

typedef string          ClassName;
typedef string          CacheName;
typedef string          RelationName;


// Exceptions
// ==========

exception DCPSError {};
exception BadHomeDefinition {};
exception BadParameter {};
exception NotFound {};
exception ReadOnlyMode {};
exception WriteOnlyMode {};
exception AlreadyExisting {};
exception AlreadyClonedInWriteMode {};
exception ExpiredTimeOut {};


// DLRL Entities
// =============

/********************
 * Forward References
 ********************/

valuetype ObjectRoot;
typedef sequence<ObjectRoot> ObjectRootSeq;

local interface ObjectHome;
typedef sequence<ObjectHome> ObjectHomeSeq;

local interface ObjectListener;
typedef sequence<ObjectListener> ObjectListenerSeq;

local interface Selection;
typedef sequence<Selection> SelectionSeq;

local interface CacheAccess;
typedef sequence<CacheAccess> CacheAccessSeq;

local interface CacheListener;
typedef sequence<CacheListener> CacheListenerSeq;

local interface Cache;


/*****************
 * ObjectReference
 *****************/

struct ObjectReference {
    DLRLOid         oid;
    unsigned long   home_index;
    };
typedef sequence<ObjectReference> ObjectReferenceSeq;


/*****************************************************
 * ObjectListener : Root for Listeners to be attached to 
 *      Home objects
 *****************************************************/

local interface ObjectListener {
    boolean on_object_created (
        in ObjectReference  ref);

    /**** will be generated with the proper Foo type* in the derived 
		*	FooListener
		*  boolean on_object_modified (    
		*		in ObjectReference ref,    
		*		in ObjectRoot old_value);
		****/

    boolean on_object_deleted (
        in ObjectReference  ref);
    };

/**********************************************************
 * SelectionListener : Root for Listeners to be attached to 
 *      Selection objects
 **********************************************************/

local interface SelectionListener {
    /***
     * will be generated with the proper Foo type 
     * in the derived FooSelectionListener
     *
    void on_object_in (
        in ObjectRoot the_object);
    void on_object_modified (
        in ObjectRoot the_object);
     *
     ***/
    void on_object_out (
        in ObjectReference the_ref);
    };
    

/********************************************************
 * CacheListener : Listener to be associated with a Cache
 ********************************************************/

local interface CacheListener {
    void begin_updates (
        in long update_round);
    void end_updates (
        in long update_round);
    };



/******************************************
 * ObjectRoot : Root fot the shared objects
 ******************************************/
enum RelationKind {
    REF_RELATION,
    LIST_RELATION,
    INT_MAP_RELATION,
    STR_MAP_RELATION};

valuetype RelationDescription {
    public RelationKind    kind;
    public RelationName    name;
    };
valuetype ListRelationDescription : RelationDescription {
    public long index;
    };
valuetype IntMapRelationDescription : RelationDescription {
    public long key;
    };
valuetype StrMapRelationDescription : RelationDescription {
    public string key;
    };
typedef sequence<RelationDescription> RelationDescriptionSeq;

typedef short   RelatedObjectDepth;
const RelatedObjectDepth UNLIMITED_RELATED_OBJECTS  = -1;

valuetype ObjectRoot {

    // State
    // -----
    private DLRLOid     m_oid;
    private ClassName   m_class_name;
    
    // Attributes
    // ----------
    readonly attribute  DLRLOid             oid;
    readonly attribute  ObjectSubState      primary_state;
    readonly attribute  ObjectSubState      secondary_state;
    readonly attribute  ObjectHome          object_home;
    readonly attribute  ClassName           class_name;
    readonly attribute  CacheAccess         cache_access;
    readonly attribute  ObjectReference     ref;

    // Operations
    // ---------- 
    void destroy ()
        raises (
            DCPSError,
            ReadOnlyMode);
    boolean is_modified (
        in ObjectScope scope);
    RelationDescriptionSeq which_contained_modified ();
    
    ObjectReference clone (
        in CacheAccess          access,
        in ObjectScope          scope,
        in RelatedObjectDepth   depth)
        raises (
            AlreadyClonedInWriteMode);
    ObjectRoot clone_object (
        in CacheAccess          access,
        in ObjectScope          scope,
        in RelatedObjectDepth   depth)
        raises (
            AlreadyClonedInWriteMode);
    };

/***********************************************
 * ObjectFilter: Root of all the objects filters 
 ***********************************************/
enum MembershipState {
    UNDEFINED_MEMBERSHIP,
    ALREADY_MEMBER,
    NOT_MEMBER
    };

 local interface ObjectFilter {
    /***
     * Following method will be generated properly typed
     * in the generated derived classes
     *
    boolean check_object (
        in ObjectRoot an_object,
        in MembershipState membership_state);
     *
     ***/
    };

/***********************************************************
 * ObjectQuery : Specialisation of the above to make a Query
 ***********************************************************/

 local interface ObjectQuery {

    // Atributes
    // ---------
    readonly attribute string           expression;
    readonly attribute StringSeq        parameters;

    //--- Methods
    boolean set_query (
        in string expression,
        in StringSeq parameters);
    boolean set_parameters (
        in StringSeq parameters);
    };


/***************************************************
 * ObjectModifier: Root of all the objects modifiers 
 ***************************************************/

 local interface ObjectModifier {
    /***
     * Following method will be generated properly typed
     * in the generated derived classes
     *
    void modify_object (
        in ObjectRoot an_object);
     *
     ***/
    };

/**********************************************************
 * ObjectExtent : Root of all the extent (lists of objects)
 **********************************************************/

 local interface ObjectExtent {
    /***
     * Following method will be generated properly typed
     * in the generated derived classes
     *
     readonly attribute ObjectRootSeq objects;

     ObjectExtent find_objects (
        in ObjectFilter filter
        );
    void modify_objects (
        in ObjectFilter     filter,
        in ObjectModifier   modifier
        );  
     *
     ***/
     };


/**********************************************************
 * Selection : Root of all the selections (dynamic subsets)
 **********************************************************/

local interface Selection {
 
    // Attributes
    // ----------
    readonly attribute boolean              auto_refresh;
    readonly attribute boolean              concerns_contained;

    /***
     * Following attributes will be generated properly typed 
     * in the generated derived classes
     *
    readonly attribute ObjectFilter         filter;
    readonly attribute ObjectExtent         membership;
    readonly attribute SelectionListener    listener;
     *
     */

    // Operations
    // ----------
    /***
     * Following method will be generated properly typed
     * in the generated derived classes
     *
    SelectionListener set_listener (
        in SelectionListener listener);
     *
     ***/
    void refresh ();
    };


/*********************************************************************
 * ObjectHome : Root of all the representatives of applicative classes
 *********************************************************************/

local interface ObjectHome {
    
    // Attributes
    // ----------
    readonly attribute string           name;   // Shared name of the class
    readonly attribute string           filter;
    readonly attribute ObjectHome       parent;
    readonly attribute ObjectHomeSeq    children;
    readonly attribute unsigned long    registration_index;
    readonly attribute ObjectReferenceSeq   refs;
    readonly attribute boolean          auto_deref;
    
    /***
     * Following attributes will be generated properly typed 
     * in the generated derived classes
     *
    readonly attribute ObjectExtent         extent;
    readonly attribute ObjectExtent         full_extent;
    readonly attribute SelectionSeq         selections;
    readonly attribute ObjectListenerSeq    listeners;
     *
     ***/

    // Operations
    // ----------

    void set_filter (
        in string expression)
        raises (
            BadParameter);

    void set_auto_deref (
        in boolean value);
    void deref_all();
    void underef_all ();

    //--- Relations to topics

    string get_topic_name (
        in string attribute_name)
        raises (
            BadParameter);
    StringSeq get_all_topic_names ();
            
    // --- Listener management

    /***
     * Following methods will be generated properly typed
     * in the generated derived classes
     *
		void attach_listener ( 
			in ObjectListener listener,
			in boolean concerns_contained_objects);
		void detach_listener (
			in ObjectListener listener);
     *
     ***/

    // --- Selection management

    /***
     * Following methods will be generated properly typed
     * in the generated derived classes
     *
    Selection create_selection (
        in ObjectFilter filter,
        in boolean auto_refresh)
        raises (
            BadParameter);
    void delete_selection (
        in Selection a_selection)
        raises (
            BadParameter);           
     *
     ***/

    // --- Object management

    /***
     * Following methods will be generated properly typed
     * in the generated derived classes
     *
    ObjectRoot create_object(
        in CacheAccess access)
        raises (
            ReadOnlyMode);
    ObjectRoot create_object_with_oid(
        in CacheAccess  access,
        in DLRLOid      oid)
        raises (
            ReadOnlyMode,
            AlreadyExisting);
    ObjectRoot create_unregistered_object (
        in CacheAccess access)
        raises (
            ReadOnlyMode);
    void register_object (
        in ObjectRoot   unregistered_object)
        raises (
            AlreadyExisting,
            BadParameter);
        
    ObjectRoot find_object_in_access (
        in DLRLOid  oid,
        in CacheAccess access)
        raises (
            NotFound);
    ObjectRoot find_object (
        in DLRLOid  oid);
     *
     ***/
    };

/***********************
 * Collection operations
 ***********************/

abstract valuetype CollectionBase {
    long length();
    boolean is_modified (
        in ReferenceScope scope);
    long how_many_added ();    
    long how_many_removed ();
    };
 
abstract valuetype ListBase : CollectionBase {
    boolean which_added (out LongSeq indexes);
    void remove ();
    };

abstract valuetype StrMapBase : CollectionBase {
    boolean which_added (out StringSeq keys);
    StringSeq get_all_keys ();
    void remove ( in string  key );
    };

abstract valuetype IntMapBase : CollectionBase {
    boolean which_added (out LongSeq keys);
    LongSeq get_all_keys ();
    void remove ( in long key );
    }; 
    

/***************************
 * Value Bases for Relations
 ***************************/

valuetype RefRelation {
    private ObjectReference     m_ref;

    boolean is_composition();
    void reset();  
    boolean is_modified (
        in ReferenceScope scope);
    };

valuetype ListRelation : ListBase {
    private ObjectReferenceSeq  m_refs;

    boolean is_composition();
    };

valuetype StrMapRelation : StrMapBase {
    struct Item {
        string          key;
        ObjectReference ref;
        };
    typedef sequence <Item> ItemSeq;

    private ItemSeq     m_refs;

    boolean is_composition();
    };

valuetype IntMapRelation : IntMapBase {
    struct Item {
        long            key;
        ObjectReference ref;
        };
    typedef sequence <Item> ItemSeq;

    private ItemSeq     m_refs;

    boolean is_composition();
    };


/************************************************************
 * CacheAccess : Manager of the access of a subset of objects
 *      (cloned) from a Cache
 ************************************************************/

local interface CacheAccess {

    // Attributes
    // ==========
    readonly attribute CacheUsage           access_usage;
    readonly attribute Cache                owner;
    readonly attribute ObjectReferenceSeq   refs;

    // Operations
    // ==========
    void refresh ()
        raises (
            DCPSError);
    void write ()
        raises (
            ReadOnlyMode,
            DCPSError);
    void purge ();
    ObjectRoot deref (
        in ObjectReference ref)
        raises (
            NotFound);
    }; 


/***********************************************************************
 * Cache : Manager of a set of related objects
 *      is associated to one DDS::Publisher and/or one DDS::Subscriber
 ***********************************************************************/

local interface Cache {

    // Attributes
    // ----------    
    readonly attribute CacheUsage           cache_usage;
    readonly attribute DCPSState            pubsub_state;
    readonly attribute DDS::Publisher       the_publisher;
    readonly attribute DDS::Subscriber      the_subscriber;
    readonly attribute boolean              updates_enabled;
    readonly attribute ObjectHomeSeq        homes;
    readonly attribute CacheAccessSeq       sub_accesses;
    readonly attribute CacheListenerSeq     listeners;
    readonly attribute ObjectReferenceSeq   refs;

    // Operations
    // ----------

    //-- Infrastructure management
    void register_all_for_pubsub()
        raises (
            BadHomeDefinition,
            DCPSError);
    void enable_all_for_pubsub()
        raises (
            DCPSError);

    // -- Home management;
    unsigned long register_home (
        in ObjectHome  a_home)
        raises (
            BadHomeDefinition);
    ObjectHome find_home_by_name (
        in ClassName class_name)
        raises (
            BadParameter);
    ObjectHome find_home_by_index (
        in unsigned long index)
        raises (
            BadParameter);

    // -- Listener Management
    void attach_listener (
        in CacheListener listener);
    void detach_listener (
        in CacheListener listener);

    // --- Updates management
    void enable_updates ();
    void disable_updates ();

    // --- CacheAccess Management
    CacheAccess create_access (
        in CacheUsage purpose)
        raises (
            ReadOnlyMode);
    void delete_access (
        in CacheAccess access)
        raises (
            BadParameter);

    // --- Object management
    ObjectRoot deref (
        in ObjectReference ref);
    void load ()
        raises (
            DCPSError);

    // --- Protection against concurrent access
    void lock (
        in TimeOutDuration to_in_milliseconds)
        raises (ExpiredTimeOut);
    void unlock ();
    };

/************************************************
 * CacheFactory : Factory to create Cache objects
 ************************************************/

valuetype CacheDescription {
    public CacheName               name;
    public DDS::DomainParticipant domain;
    };

local interface CacheFactory {
    Cache create_cache (
        in CacheUsage       cache_usage,
        in CacheDescription cache_description)
        raises (
            DCPSError,
            AlreadyExisting);
    Cache find_cache_by_name(
        in CacheName        name)
        raises (
            BadParameter);
	void delete_cache (
		in Cache			a_cache);

    };
};