// $Id$

module ImplementationRepository
{
  interface ServerObject
    // = TITLE
    //    Server Side IR Object
    //
    // = DESCRIPTION
    //    This object, which exists on the servers that use the 
    //    Implementation Repository (IR), is used to control or check the 
    //    status of the server by the IR.
  {
    void ping ();
    // Check the liveness of a server.

    void shutdown ();
    // Try to shutdown the server gracefully.
  };

  struct EnvironmentVariable
  // One environment variable/value pair.
  {
    string name;
    string value;
  };

  typedef string Address;
  // Specifies the location of the server.

  typedef sequence<EnvironmentVariable> EnvironmentList;
  // Complete Environment.

  enum ActivationMode {NORMAL, MANUAL, PER_CLIENT, AUTO_START};
  // The type of Activation 

  struct StartupOptions
  // Options used to start up the server.
  {
    string command_line;
    // Startup command (program name and arguments).
    
    EnvironmentList environment;
    // Environment Variables.
    
    string working_directory;
    // Working directory.

    ActivationMode activation;
    // Activation Mode
  };

  struct ServerInformation
  // All the information about one server.
  {
    string logical_server;
    // The logical server this server is part of.

    string server;
    // Server name.

    StartupOptions startup;
    // How to start up the server.

    Address location;
    // Where the server is located currently.
  };

  typedef sequence <ServerInformation> ServerInformationList;

  interface ServerInformationIterator;
  // Forward declaration.

  interface Administration
    // = TITLE
    //    The Implementation Repository Administration Interface
    //
    // = DESCRIPTION
    //    This interface exports all the administration functionality of
    //    the Implementation Repository.
  {
    // = Exceptions

    exception AlreadyRegistered {};
    // Object already bound in the Implementation Repository

    exception CannotActivate
    {
      string reason;
    };
    // The server could not be restarted.

    exception NotFound {};
    // Object not found in the Implementation Repository

    void activate_server (in string server)
      raises (NotFound,
              CannotActivate);
    // Activate server that is named <server>.
    //
    // The <NotFound> exception is raised when <server> is not found
    // in the Implementation Repository.  The <CannotActivate> exception
    // is raised when <server> is found in the Repository but could not be
    // activated.

    void register_server (in string server,
                          in StartupOptions options)
      raises (AlreadyRegistered);
    // Register the <options> to specify how the <server> should be
    // restarted when a client asks for it.  
    //
    // The <AlreadyRegistered> exception is raised when <server> has
    // already been registered with the Implementation Repository.

    void reregister_server (in string server,
                            in StartupOptions options);
    // Update the <options> to specify how the <server> should be
    // restarted when a client asks for it.  Will register the server
    // if not already registered.

    void remove_server (in string server)
      raises (NotFound);
    // Remove <server> from the Implementation Repository.
    //
    // The <NotFound> exception is raised when <server> is not found
    // in the Implementation Repository.

    void shutdown_server (in string server)
      raises (NotFound);
    // Tries to shutdown the server, first gracefully, then ungracefully.
    //
    // The <NotFound> exception is raised when <server> is not found
    // in the Implementation Repository.

    Address server_is_running (in string server,
                               in Address addr,
                               in ServerObject server_object)
      raises (NotFound);
    // Used to notify the Implementation Repository that <server> is alive 
    // and well at <addr>.
    //
    // The <NotFound> exception is raised when <server> is not found
    // in the Implementation Repository.

    void server_is_shutting_down (in string server)
      raises (NotFound);
    // Used to tell the Implementation Repository that <server> is shutting
    // down.
    //
    // The <NotFound> exception is raised when <server> is not found
    // in the Implementation Repository.

    void find (in string server, 
               out ServerInformation info)
      raises (NotFound);
    // Returns the startup information for a given <server>.
    //
    // The <NotFound> exception is raised when <server> is not found
    // in the Implementation Repository.

    void list (in unsigned long how_many,
               out ServerInformationList server_list,
               out ServerInformationIterator server_iterator);
    // Returns at most <how_many> servers in <server_list>.  If there
    // are additional servers, they can be received through the
    // <server_iterator>.  If there are no more servers, then
    // <server_iterator> is null.
  };

  interface ServerInformationIterator
  {
    // = TITLE
    // Interface for iterating over servers returned with
    // Administration::list ().

    boolean next_n (in unsigned long how_many,
		    out ServerInformationList server_list);
    // This operation returns at most the requested number of
    // servers.

    void destroy ();
    // This operation destroys the iterator.
  };
};