TAO/tao/ImR_Client/ImplRepo.idl

   1 // -*- IDL -*-
   2
   3 #ifndef TAO_IMRCLIENT_IMPLREPO_PIDL
   4 #define TAO_IMRCLIENT_IMPLREPO_PIDL
   5
   6 #include "ServerObject.idl"
   7 #include "tao/StringSeq.pidl"
   8
   9 module ImplementationRepository
  10 {
  11   // = Exceptions
  12
  13   /// Object already bound in the Implementation Repository
  14   exception AlreadyRegistered {};
  15
  16   /// The server could not be restarted.
  17   exception CannotActivate
  18   {
  19     string reason;
  20   };
  21
  22   /// Object not found in the Implementation Repository
  23   exception NotFound {};
  24
  25   /// Operation cannot be completed due to Activator version
  26   /// or other incompatibility
  27   exception CannotComplete
  28   {
  29     string reason;
  30   };
  31
  32   /// One environment variable/value pair.
  33   struct EnvironmentVariable
  34   {
  35     string name;
  36     string value;
  37   };
  38
  39   /// Complete Environment.
  40   typedef sequence<EnvironmentVariable> EnvironmentList;
  41
  42   /// The type of Activation
  43   enum ActivationMode {NORMAL, MANUAL, PER_CLIENT, AUTO_START};
  44
  45   /// Options used to start up the server.
  46   struct StartupOptions
  47   {
  48     /// Startup command (program name and arguments).
  49     string command_line;
  50
  51     /// Environment Variables.
  52     EnvironmentList environment;
  53
  54     /// Working directory.
  55     string working_directory;
  56
  57     /// Activation Mode
  58     ActivationMode activation;
  59
  60     /// Name of the activator
  61     string activator;
  62
  63     /// Number of retries allowed
  64     long start_limit;
  65   };
  66
  67   /// Status of server
  68   enum ServerActiveStatus
  69   {
  70     /// No attempt as been made to determine status.
  71     ACTIVE_MAYBE,
  72
  73     /// Server has been successfully pinged within ping interval.
  74     ACTIVE_YES,
  75
  76     /// Server was not able to be pinged within ping interval.
  77     ACTIVE_NO
  78   };
  79
  80   struct ServerInformation
  81   {
  82     /// Server name.
  83     string server;
  84
  85     /// How to start up the server.
  86     StartupOptions startup;
  87
  88     /// This is used in places that require a partial IOR with
  89     /// just the ObjectKey missing.
  90     string partial_ior;
  91
  92     /// Server status
  93     ServerActiveStatus activeStatus;
  94   };
  95
  96   typedef sequence <ServerInformation> ServerInformationList;
  97
  98   /**
  99     * @brief The Server Information Iterator Interface
 100     *
 101     * Interface for iterating over servers returned with
 102     * Administration::list ().
 103     */
 104   interface ServerInformationIterator
 105   {
 106     /// This operation returns at most the requested number of
 107     /// servers.
 108     /// If how_many == 0, then returns all servers
 109     boolean next_n (in unsigned long how_many,
 110                     out ServerInformationList servers);
 111
 112     /// This operation destroys the iterator.
 113     void destroy ();
 114   };
 115
 116   /**
 117     * @brief The Implementation Repository Administration Interface
 118     *
 119     * This interface exports all the administration functionality of
 120     * the Implementation Repository.
 121     */
 122   interface Administration
 123   {
 124     /// Activate server that is named @a server.
 125     ///
 126     /// The @c NotFound exception is raised when @a server is not found
 127     /// in the Implementation Repository.  The @c CannotActivate exception
 128     /// is raised when @a server is found in the Repository but could not be
 129     /// activated.
 130     void activate_server (in string server)
 131       raises (NotFound, CannotActivate);
 132
 133     /// Add/Update the the @a server.
 134     /// The @c NotFound exception is raised when the activator specified
 135     /// in the options is not registered.
 136     void add_or_update_server (in string server, in StartupOptions options)
 137       raises(NotFound);
 138
 139     /// Remove @a server from the Implementation Repository.
 140     ///
 141     /// The @c NotFound exception is raised when @a server is not found
 142     /// in the Implementation Repository.
 143     void remove_server (in string server)
 144       raises (NotFound);
 145
 146     /// Tries to shutdown the server, first gracefully, then ungracefully.
 147     ///
 148     /// The @c NotFound exception is raised when @a server is not found
 149     /// in the Implementation Repository.
 150     void shutdown_server (in string server)
 151       raises (NotFound);
 152
 153     /// Used to notify the Implementation Repository that @a server is alive
 154     /// and well at @a partial_ior.
 155     ///
 156     /// The @c NotFound exception is raised when @a server is not found
 157     /// in the Implementation Repository.
 158     void server_is_running (in string server,
 159                             in string partial_ior,
 160                             in ServerObject server_object)
 161       raises (NotFound);
 162
 163     /// Used to tell the Implementation Repository that @a server is shutting
 164     /// down.
 165     ///
 166     /// The @c NotFound exception is raised when @a server is not found
 167     /// in the Implementation Repository.
 168
 169     void server_is_shutting_down (in string server)
 170       raises (NotFound);
 171
 172     /// Returns the startup information for a given @a server.
 173     void find (in string server, out ServerInformation info);
 174
 175     /// Returns at most @a how_many servers in @a server_list.  If there
 176     /// are additional servers, they can be received through the
 177     /// @a server_iterator.  If there are no more servers, then
 178     /// @a server_iterator is null.
 179     /// If @a how_many == 0, then returns all servers.
 180     /// If @a determine_active_status is true then
 181     /// set ServerInformation::active_status attribute by determining
 182     /// if the server is alive.
 183     void list (in unsigned long how_many,
 184                in boolean determine_active_status,
 185                out ServerInformationList server_list,
 186                out ServerInformationIterator server_iterator);
 187
 188     /// Shutdown the ImR, optionally shutting down registered
 189     /// activators and servers first.
 190     oneway void shutdown(in boolean activators, in boolean servers);
 191   };
 192
 193   /**
 194     * @brief The Extended Implementation Repository Administration Interface
 195     *
 196     * This interface adds operations in a way that maintains compatibility
 197     */
 198   interface AdministrationExt : Administration
 199   {
 200     /// Identify a set of peer poas that exist in the same process.
 201     void link_servers (in string server, in CORBA::StringSeq peers)
 202       raises(NotFound, CannotComplete);
 203
 204     /// Have the appropriate activator send a signal to the named server process
 205     void kill_server (in string server, in short signum)
 206       raises(NotFound, CannotComplete);
 207
 208     /// Combine the action of shutting down a running server instance if any via
 209     /// a shutdown command if signum is 0, or via kill if signum is nonzero
 210     void force_remove_server (in string server, in short signum)
 211       raises(NotFound, CannotComplete);
 212   };
 213 };
 214
 215 #endif /* TAO_IMRCLIENT_IMPLREPO_PIDL */