/*****************************************************************************
 *                                                                        
 *  File: Configuration.idl                                               
 *                                                                        
 *  Description: Definition of the interfaces for Component Configuration.
 *                                                                        
 *  Project: 2K - Automatic Configuration                                 
 *  Author: Fabio Kon (f-kon@cs.uiuc.edu)                                 
 *                                                                        
 *****************************************************************************
  Revision Control Information
   $Revision: 1.2 $
   $Log: Configuration.idl,v $
   Revision 1.2  2000/01/24 15:56:44  f-kon
   minor improvements

   Revision 1.1.1.1  1999/10/12 00:42:46  f-kon
   Version compatible with TAO 1.0

   Revision 1.1.1.1  1999/04/01 18:16:36  f-kon
   This new 2K source tree contains the most up-to-date version of ACE and TAO
   and including the dynamicTAO code as well as some 2K tests and preliminary
   versions of some of its high-level systems.


   Revision 1.1  1999/02/15 18:04:19  f-kon
   *** empty log message ***

 ******************************************************************************/

/**
 * A module containing interfaces, structures, and types for Component Configuration. 
 *
 * @version        0.2
 * @author         Fabio Kon
 */

#ifndef CONFIGURATION_IDL
#define CONFIGURATION_IDL

module Configuration 
{
  enum EventType {STARTED, FINISHED, SHUTDOWN, RECONFIGURED, REPLACED, MIGRATED, 
                  DELETED, FAILED, APP_SPECIFIC, UNKNOWN};
  
  struct Event
  {
    EventType type;
    string description;
  };

  interface ComponentConfigurator; // forward declaration

  struct DependencySpecification
  {
    string name;
    ComponentConfigurator componentConfig;
  };
  
  typedef sequence<DependencySpecification> DependencyList;	

  /**
   * An interface for representing the dependencies between CORBA Objects.
   * @see Factory
   */
  interface ComponentConfigurator
    {
      exception invalidArgument{};
      exception ElementExists{};
      exception NotFound{};
      exception HookBusy{};
      exception HookVacant{};
      
      /**
       * Deletes the references to all internal data structures and deactivates
       * the current object.
       */
      void destroy ();

      /**
       * Adds a hook to the configurator.
       * @parm   hookName  the name of the hook to be added.
       * @raises ElementExists if the hook already exists.
       */
      void addHook          (in string hookName) raises (ElementExists);

      /**
       * Deletes a hook from the configurator.
       * @parm   hookName  the name of the hook to be deleted.
       * @raises NotFound if the hook is not found.
       */
      void deleteHook       (in string hookName) raises (NotFound);
      
      /**
       * Attaches a ComponentConfigurator to the given hook.
       * @parm  hookName  the name of the hook.
       * @parm  cc        the ComponentConfigurator to be attached to the hook.
       * @raises HookBusy if there is already a component attached to the hook.
       * @raises NotFound if the hook does not exist.
       */
      void hook             (in string hookName, in ComponentConfigurator cc) 
          raises (NotFound);

      /**
       * Detaches a ComponentConfigurator from the given hook.
       * @parm hookName  the name of the hook.
       * @parm cc        the ComponentConfigurator to be detached.
       * @raises HookVacant if there are no components attached to the hook.
       * @raises NotFound if the hook does not exist.
       */
      void unhook           (in string hookName) raises (HookVacant, NotFound);

      /**
       * Adds a new component to the list of clients.
       * @parm  client  the ComponentConfigurator representing the new client.
       * @parm  hookNameInClient the name of the hook to which this component is attached.
       * @raises ElementExists if the given pair (client, hookNameInClient) is 
       *                          already present in the client list.
       * 
       */
      void registerClient   (in ComponentConfigurator client, 
                             in string hookNameInClient) raises (ElementExists);

      /**
       * Removes a pair (client, hook) from the list of clients.
       * @parm  client  the ComponentConfigurator representing the new client.
       * @parm  hookNameInClient the name of the hook to which this component is attached.
       * @raises NotFound if the given pair (client, hookNameInClient) is not 
       *                     present in the client list.
       * 
       */
      void unregisterClient (in ComponentConfigurator client, 
                             in string hookNameInClient) raises (NotFound);
            
      /**
       * This implementation simply prints the event to the standard output.
       * @parm  hookedComponent the ComponentConfigurator that generated the event.
       * @parm  e               the event that was generated. 
       */
      void eventOnHookedComponent (in ComponentConfigurator hookedComponent,
                                   in Event e, in unsigned short timeToLive);

      /**
       * This implementation simply prints the event to the standard output.
       * @parm  client  the ComponentConfigurator that generated the event.
       * @parm  e       the event that was generated. 
       */
      void eventOnClient          (in ComponentConfigurator client,
                                   in Event e, in unsigned short timeToLive);

      /**
       * Accessor for the component name.
       * @returns a string containing the component name. 
       */      
      string name ();

      /**
       * Accessor for the component information string.
       * @returns a string containing component information.
       */
      string info ();

      /**
       * Provides a list of the hooks in this component.
       * @returns a list of DependencySpecifications.
       * @see DependencySpecification
       */
      DependencyList listHooks ();

      /**
       * Provides a reference to the component attached to the given hook.
       * @returns a reference to the ComponentConfigurator.
       */
      ComponentConfigurator getHookedComponent(in string hookName);

      /** Provides the number of clients of this component. 
       * May be used for garbage collection.
       * @returns the size of the list of clients.
       */
      unsigned short numberOfClients ();

      /** Provides a list of the clients of this component.
       * @returns a list of DependencySpecifications.
       */
      DependencyList listClients ();

      /** Accessor to the object that implement this component.
       * @returns a reference to the CORBA object implementing this component.
       */
      Object implementation ();
    };

  
  /**
   * A Factory for creating ComponentConfigurator objects.
   * @see ComponentConfigurator
   */
  interface Factory
      {
          /** Creates a new configurator for the given implementation with the given name. 
           * @returns a reference to the new ComponentConfigurator.
           */
           ComponentConfigurator newConfigurator (in string name, in Object implementation);

           /** Shuts down the Factory. All the ComponentConfigurators created
            *  with the Factory are also destroyed.  
            */
           oneway void shutdown ();
    };
};

#endif