path: root/TAO/tao/ccm_core/Component_Base.idl

// $Id$

/**
 * @@ Compile this file with:
 *
 *     tao_idl -Gv -I W:/ACE_wrappers/TAO -I W:/ACE_wrappers/TAO/orbsvcs/orbsvcs Component_Base.idl
 *
 * @@ CosPersistentState related stuff are removed completely.
 *
 */

//  import ::CORBA
//  import ::SecurityLevel2
//  import ::CosPersistentState
//  import ::PortableServer
//  import ::CosNotification
//  import ::CosNotifyChannelAdmin

#include <CORBA.pidl>
#include <SecurityLevel2.idl>
#include <CosPersistentState.idl>
#include <PortableServer/PortableServer.pidl>
#include <IFR_Client/Interface.pidl>
#include <CosNotification.idl>
#include <CosNotifyChannelAdmin.idl>

/**
 * Temporarily fix for lacking of typePrefix keyword.
 * Search for the word "typePrefix" when tao_idl starts
 * supporting the keyword.
 */
#pragma prefix "omg.org"

module Components {

  /**
   * @@ Commented out temporarily for lack of typePrefix support.
   */
  //    typePrefix Components "omg.org"
  typedef string FeatureName;
  typedef sequence<FeatureName> NameList;

  valuetype Cookie
  {
    private CORBA::OctetSeq cookieValue;
  };

  valuetype PortDescription
  {
    public FeatureName Name;
    public CORBA::RepositoryId type_id;
  };

  valuetype FacetDescription : PortDescription
  {
    public Object facet_ref;
  };

  typedef sequence<FacetDescription> FacetDescriptions;

  typedef unsigned long FailureReason;

  exception InvalidName {};
  exception InvalidConnection {};
  exception ExceededConnectionLimit {};
  exception AlreadyConnected {};
  exception NoConnection {};
  exception CookieRequired {};
  exception CreateFailure {
    FailureReason reason;
  };
  exception FinderFailure
  {
    FailureReason reason;
  };
  exception RemoveFailure
  {
    FailureReason reason;
  };
  exception DuplicateKeyValue {};
  exception InvalidKey {};
  exception UnknownKeyValue {};
  exception NoKeyAvailable {};
  exception BadEventType
  {
    CORBA::RepositoryId expected_event_type;
  };
  exception HomeNotFound {};
  exception WrongComponentType {};

  typedef FailureReason InvalidConfigurationReason;
  const InvalidConfigurationReason UnknownConfigValueName = 0;
  const InvalidConfigurationReason InvalidConfigValueType = 1;
  const InvalidConfigurationReason ConfigValueRequired = 2;
  const InvalidConfigurationReason ConfigValueNotExpected = 3;
  exception InvalidConfiguration
  {
    InvalidConfigurationReason reason;
    FeatureName name;
  };
  exception IllegalState {};

  interface Navigation
  {
    Object provide_facet (in FeatureName name)
      raises (InvalidName);
    FacetDescriptions get_all_facets();
    FacetDescriptions get_named_facets (in NameList names)
      raises (InvalidName);
    boolean same_component (in Object object_ref);
  };

  valuetype ConnectionDescription
  {
    public Cookie ck;
    public Object objref;
  };
  typedef sequence<ConnectionDescription> ConnectionDescriptions;

  valuetype ReceptacleDescription : PortDescription
  {
    public boolean is_multiple;
    public ConnectionDescriptions connections;
  };
  typedef sequence<ReceptacleDescription> ReceptacleDescriptions;

  interface Receptacles
  {
    Cookie connect (in FeatureName name, in Object connection )
      raises (InvalidName,
              InvalidConnection,
              AlreadyConnected,
              ExceededConnectionLimit);

    void disconnect (in FeatureName name, in Cookie ck)
      raises (InvalidName,
              InvalidConnection,
              CookieRequired,
              NoConnection);

    ConnectionDescriptions get_connections (in FeatureName name)
      raises (InvalidName);

    ReceptacleDescriptions get_all_receptacles ();

    ReceptacleDescriptions get_named_receptacles (in NameList names)
      raises (InvalidName);
  };

  abstract valuetype EventBase {};

  interface EventConsumerBase
  {
    void push_event (in EventBase evt) raises (BadEventType);
  };

  valuetype ConsumerDescription : PortDescription
  {
    public EventConsumerBase consumer;
  };
  typedef sequence<ConsumerDescription> ConsumerDescriptions;

  valuetype EmitterDescription : PortDescription
  {
    public EventConsumerBase consumer;
  };
  typedef sequence<EmitterDescription> EmitterDescriptions;

  // @@ I added the parent class "PortDescription" below as it seems
  //    to be missing from the draft.
  valuetype SubscriberDescription : PortDescription
  {
    public Cookie ck;
    public EventConsumerBase consumer;
  };
  typedef sequence<SubscriberDescription> SubscriberDescriptions;

  valuetype PublisherDescription : PortDescription
  {
    public SubscriberDescriptions consumer;
  };
  typedef sequence<PublisherDescription> PublisherDescriptions;

  interface Events
  {
    EventConsumerBase get_consumer (in FeatureName sink_name)
      raises (InvalidName);

    Cookie subscribe (in FeatureName publisher_name,
                      in EventConsumerBase subscriber)
      raises (InvalidName,
              AlreadyConnected,
              InvalidConnection);

    void unsubscribe (in FeatureName publisher_name,
                      in Cookie ck)
      raises (InvalidName,
              InvalidConnection);

    void connect_consumer (in FeatureName emitter_name,
                           in EventConsumerBase consumer)
      raises (InvalidName,
              AlreadyConnected,
              InvalidConnection);

    EventConsumerBase disconnect_consumer (in FeatureName source_name)
      raises (InvalidName,
              NoConnection);

    ConsumerDescriptions get_all_consumers ();

    ConsumerDescriptions get_named_consumers (in NameList names)
      raises (InvalidName);

    EmitterDescriptions get_all_emitters ();

    EmitterDescriptions get_named_emitters (in NameList names)
      raises (InvalidName);

    PublisherDescriptions get_all_publishers ();

    PublisherDescriptions get_named_publishers (in NameList names)
      raises (InvalidName);
  };

  abstract valuetype PrimaryKeyBase {};

  interface CCMObject; //forward reference

  interface CCMHome
  {
    CORBA::IRObject get_component_def ();
    CORBA::IRObject get_home_def ();
    void remove_component ( in CCMObject comp)
      raises (RemoveFailure);
  };
  typedef sequence<CCMHome> CCMHomes;

  interface KeylessCCMHome
  {
    CCMObject create_component()
      raises (CreateFailure);
  };

  interface HomeFinder
  {
    CCMHome find_home_by_component_type (in CORBA::RepositoryId comp_repid)
      raises (HomeNotFound);

    CCMHome find_home_by_home_type (in CORBA::RepositoryId home_repid)
      raises (HomeNotFound);

    CCMHome find_home_by_name (in string home_name)
      raises (HomeNotFound);
  };

  interface Configurator
  {
    void configure (in CCMObject comp)
      raises (WrongComponentType);
  };

  valuetype ConfigValue
  {
    public FeatureName name;
    public any value;
  };

  typedef sequence<ConfigValue> ConfigValues;

  interface StandardConfigurator : Configurator
  {
    void set_configuration (in ConfigValues descr);
  };

  interface HomeConfiguration : CCMHome
  {
    void set_configurator (in Configurator cfg);
    void set_configuration_values (in ConfigValues config);
    void complete_component_configuration (in boolean b);
    void disable_home_configuration();
  };

  valuetype ComponentPortDescription
  {
    public FacetDescriptions facets;
    public ReceptacleDescriptions receptacles;
    public ConsumerDescriptions consumers;
    public EmitterDescriptions emitters;
    public PublisherDescriptions publishers;
  };

  interface CCMObject : Navigation, Receptacles, Events
  {
    CORBA::IRObject get_component_def ( );
    CCMHome get_ccm_home( );
    PrimaryKeyBase get_primary_key( )
      raises (NoKeyAvailable);
    void configuration_complete( )
      raises (InvalidConfiguration);
    void remove()
      raises (RemoveFailure);
    ComponentPortDescription get_all_ports ();
  };


  // @@ Enumeration and DefaultEnumeration are only for EJB to CCM
  // mapping?  At any rate, we should be able to skip them for now.
  abstract valuetype Enumeration
  {
    boolean has_more_elements();
    CCMObject next_element();
  };

  typedef sequence<CCMObject> CCMObjectSeq;

  valuetype DefaultEnumeration : Enumeration
  {
    private CCMObjectSeq objects;
  };

  // @@ Components::Transaction is still there.
  module Transaction
  {

    typedef sequence<octet> TranToken;

    exception NoTransaction {};
    exception NotSupported {};
    exception SystemError {};
    exception RollbackError {};
    exception HeuristicMixed {};
    exception HeuristicRollback {};
    exception Security {};
    exception InvalidToken {};

    enum Status
    {
      ACTIVE,
      MARKED_ROLLBACK,
      PREPARED,
      COMMITTED,
      ROLLED_BACK,
      NO_TRANSACTION,
      PREPARING,
      COMMITTING,
      ROLLING_BACK
    };

    local interface UserTransaction {
      void begin ()
        raises (NotSupported,
                SystemError);

      void commit ()
        raises (RollbackError,
                NoTransaction,
                HeuristicMixed,
                HeuristicRollback,
                Security,
                SystemError);

      void rollback ()
        raises (NoTransaction,
                Security,
                SystemError);

      void set_rollback_only ()
        raises (NoTransaction,
                SystemError);

      Status get_status()
        raises (SystemError);

      void set_timeout (in long to)
        raises (SystemError);

      TranToken suspend ()
        raises (NoTransaction,
                SystemError);

      void resume (in TranToken txtoken)
        raises (InvalidToken,
                SystemError);
    };
  };

  // @@ module Notification doesn't seem to exist anymore.
    module Notification {

        typedef CosNotification::EventHeader EventHeader;
        /**
         * @@ Typo with "CosNotifyChannnelAdmin::ChannelId"?
         */
        typedef CosNotifyChannelAdmin::ChannelID Channel;

        exception ChannelUnavailable {};
        exception InvalidSubscription {};
        exception InvalidName {};
        exception InvalidChannel {};

        local interface LocalCookie {
            boolean same_as (in LocalCookie cookie);
        };

        local interface Event {
            EventConsumerBase create_channel
                (out Channel chid)
                raises (ChannelUnavailable);
            LocalCookie subscribe (
                in EventConsumerBase ecb,
                in Channel chid)
                raises (ChannelUnavailable);
            void unsubscribe (in LocalCookie cookie)
                raises (InvalidSubscription);
            EventConsumerBase obtain_channel (
                in string supp_name,
                in EventHeader hdr)
                raises (InvalidName);
            void listen (in EventConsumerBase ecb,
                in string csmr_name)
                raises (InvalidName);
            void push (in EventBase evt);
            void destroy_channel (in Channel chid)
                raises (InvalidChannel);
        };
    };

  // *************** Basic Container interfaces ***************

  typedef SecurityLevel2::Credentials Principal;

  local interface CCMContext
  {
    Principal get_caller_principal();

    CCMHome get_CCM_home();

    boolean get_rollback_only()
      raises (IllegalState);

    Transaction::UserTransaction get_user_transaction()
      raises (IllegalState);

    boolean is_caller_in_role (in string role);

    void set_rollback_only()
      raises (IllegalState);
  };

  enum CCMExceptionReason
  {
    SYSTEM_ERROR,
    CREATE_ERROR,
    REMOVE_ERROR,
    DUPLICATE_KEY,
    FIND_ERROR,
    OBJECT_NOT_FOUND,
    NO_SUCH_ENTITY
  };

  exception CCMException
  {
    CCMExceptionReason reason;
  };

  local interface EnterpriseComponent {};

  local interface SessionContext : CCMContext
  {
    Object get_CCM_object()
      raises (IllegalState);
  };

  local interface SessionComponent : EnterpriseComponent
  {
    void set_session_context ( in SessionContext ctx)
      raises (CCMException);

    void ccm_activate()
      raises (CCMException);

    void ccm_passivate()
      raises (CCMException);

    void ccm_remove ()
      raises (CCMException);
  };

  local interface SessionSynchronization
  {
    void after_begin ()
      raises (CCMException);

    void before_completion ()
      raises (CCMException);

    void after_completion (in boolean committed)
      raises (CCMException);
  };

  local interface EntityContext : CCMContext
  {
    Object get_CCM_object ()
      raises (IllegalState);

    PrimaryKeyBase get_primary_key ()
      raises (IllegalState);
  };

  local interface EntityComponent : EnterpriseComponent
  {
    void set_entity_context (in EntityContext ctx)
      raises (CCMException);

    void unset_entity_context ()
      raises (CCMException);

    void ccm_activate ()
      raises (CCMException);

    void ccm_load ()
      raises (CCMException);

    void ccm_store ()
      raises (CCMException);

    void ccm_passivate ()
      raises (CCMException);

    void ccm_remove ()
      raises (CCMException);
  };

  // *************** Extended Container Interfaces ***************

  enum BadComponentReferenceReason
  {
    NON_LOCAL_REFERENCE,
    NON_COMPONENT_REFERENCE,
    WRONG_CONTAINER
  };

  typedef CosPersistentState::CatalogBase CatalogBase;
  typedef CosPersistentState::TypeId TypeId;

  typedef short SegmentId;
  const SegmentId COMPONENT_SEGMENT = 0;

  typedef short FacetId;
  const FacetId COMPONENT_FACET = 0;

  typedef sequence<octet> IdData;
  typedef CosPersistentState::Pid PersistentId;

  typedef short StateIdType;
  const StateIdType PERSISTENT_ID = 0;

  exception BadComponentReference
  {
    BadComponentReferenceReason reason;
  };
  exception PolicyMismatch {};
  exception PersistenceNotAvailable {};
  exception UnknownActualHome {};
  exception ProxyHomeNotSupported {};
  exception InvalidStateIdData {};

  local interface HomeRegistration
  {
    void register_home (in CCMHome home_ref,
                        in string home_name);

    void unregister_home (in CCMHome home_ref);
  };

  local interface CCM2Context : CCMContext
  {
    HomeRegistration get_home_registration ();

    void req_passivate ()
      raises (PolicyMismatch);

    CatalogBase get_persistence (in TypeId catalog_type_id)
      raises (PersistenceNotAvailable);
  };

  local interface ProxyHomeRegistration : HomeRegistration
  {
    void register_proxy_home (in CCMHome rhome,
                              in CCMHome ahome)
      raises (UnknownActualHome,
              ProxyHomeNotSupported);
  };

  local interface Session2Context : SessionContext, CCM2Context
  {
    Object create_ref (in CORBA::RepositoryId repid);

    Object create_ref_from_oid (in CORBA::OctetSeq oid,
                                in CORBA::RepositoryId repid);

    CORBA::OctetSeq get_oid_from_ref (in Object objref)
      raises (IllegalState,
              BadComponentReference);
  };

  abstract valuetype StateIdValue
  {
    StateIdType get_sid_type();
    IdData get_sid_data();
  };

  local interface StateIdFactory
  {
    StateIdValue create (in IdData data)
      raises (InvalidStateIdData);
  };

  valuetype PersistentIdValue : StateIdValue
  {
    private PersistentId pid;

    PersistentId get_pid();
    factory init (in PersistentId pid);
  };

  valuetype SegmentDescr
  {
    private StateIdValue sid;
    private SegmentId seg;

    StateIdValue get_sid();
    SegmentId get_seg_id();
    factory init (in StateIdValue sid,
                  in SegmentId seg);
  };

  typedef sequence<SegmentDescr> SegmentDescrSeq;

  local interface ComponentId
  {
    FacetId get_target_facet();

    SegmentId get_target_segment();

    StateIdValue get_target_state_id (in StateIdFactory sid_factory)
      raises (InvalidStateIdData);

    StateIdValue get_segment_state_id (in SegmentId seg,
                                       in StateIdFactory sid_factory)
      raises (InvalidStateIdData);

    ComponentId create_with_new_target (in FacetId new_target_facet,
                                        in SegmentId new_target_segment);

    SegmentDescrSeq get_segment_descrs (in StateIdFactory sid_factory)
      raises (InvalidStateIdData);
  };

  local interface Entity2Context : EntityContext, CCM2Context
  {
    ComponentId get_component_id ()
      raises (IllegalState);

    ComponentId create_component_id (in FacetId target_facet,
                                     in SegmentId target_segment,
                                     in SegmentDescrSeq seq_descrs);

    ComponentId create_monolithic_component_id (in FacetId target_facet,
                                                in StateIdValue sid);

    Object create_ref_from_cid (in CORBA::RepositoryId repid,
                                in ComponentId cid);

    ComponentId get_cid_from_ref (in Object objref)
      raises (BadComponentReference);
  };

  // *************** Packaging and Deployment ***************

  module Deployment
  {
    typedef string UUID;
    typedef string Location;

    enum AssemblyState
    {
      INACTIVE,
      INSERVICE
    };

    exception UnknownImplId {};
    exception InvalidLocation {};
    exception InstallationFailure
    {
      FailureReason reason;
    };
    exception InvalidAssembly {};

    interface ComponentInstallation
    {
      void install(in UUID implUUID,
                   in Location component_loc)
        raises (InvalidLocation,
                InstallationFailure);

      void replace(in UUID implUUID,
                   in Location component_loc)
        raises (InvalidLocation,
                InstallationFailure);

      void remove(in UUID implUUID)
        raises (UnknownImplId,
                RemoveFailure);

      Location get_implementation (in UUID implUUID)
        raises (UnknownImplId,
                InstallationFailure);
    };

    interface Assembly
    {
      void build();

      void tear_down()
        raises (RemoveFailure);

      AssemblyState get_state();
    };

    interface AssemblyFactory
    {
      Cookie create(in Location assembly_loc)
        raises (InvalidLocation,
                CreateFailure);

      Assembly lookup(in Cookie c)
        raises (InvalidAssembly);

      void destroy(in Cookie c)
        raises (InvalidAssembly,
                RemoveFailure);
    };

    interface ComponentServer;  // Forward decl.
    typedef sequence<ComponentServer> ComponentServers;

    interface ServerActivator
    {
      ComponentServer create_component_server (in ConfigValues config)
        raises (CreateFailure,
                InvalidConfiguration);

      void remove_component_server (in ComponentServer server)
        raises (RemoveFailure);

      ComponentServers get_component_servers ();
    };

    interface Container;        // Forward decl.
    typedef sequence<Container> Containers;

    interface ComponentServer
    {
      readonly attribute ConfigValues configuration;

      ServerActivator get_server_activator ();
      Container create_container (in ConfigValues config)
        raises (CreateFailure,
                InvalidConfiguration);

      void remove_container (in Container cref)
        raises (RemoveFailure);

      Containers get_containers ();

      void remove ()
        raises (RemoveFailure);
    };

    exception ImplEntryPointNotFound {};

    interface Container
    {
      readonly attribute ConfigValues configuration;

      ComponentServer get_component_server ();

      CCMHome install_home (in UUID id,
                            in string entrypt,
                            in ConfigValues config)
        raises (UnknownImplId,
                ImplEntryPointNotFound,
                InstallationFailure,
                InvalidConfiguration);

      void remove_home (in CCMHome href)
        raises (RemoveFailure);

      CCMHomes get_homes ();
      void remove ()
        raises (RemoveFailure);

    };

  };
};