/*
 * sga-manager.idl
 *
 * $Author: fpina $
 * $Revision: 158110 $ - $Date: 2014-11-06 09:32:30 -0200 (Qui, 06 Nov 2014) $
 */

#ifndef _SGA_MANAGER_IDL
#define _SGA_MANAGER_IDL

#include "sga-daemon.idl"
#include "sga-common.idl"

/**
 * \brief Interfaces entre SGA e SGA Manager para gerência da execução remota
 * de algoritmos.
 */
module sgaidl {

   interface SGADaemon;
   interface SGACommand;

   /**
    * @TODO Mudar essa estrutura para um dicionário tb?
    * \brief Informações sobre o fim da execução de um comando. Essas
    * informações correspondem, basicamente, às estatísticas fornecidas pelo
    * comando 'time'.
    */
   struct CompletedCommandInfo {
     long elapsedTimeSec;
     long userTimeSec;
     long cpuTimeSec;
   };

   /**
    * \brief Informações sobre um comando recuperado.
    */
   struct RetrievedInfo {
    /** \brief Identificação do comando recuperado */
    string cmdId;
    /** \brief Referência para o gerenciador de comando */
    SGACommand cmdRef;
   };

   /**
    * \brief Informações de todos os comandos que foram recuperados.
    */
   typedef sequence<RetrievedInfo> RetrievedCmds;

   /** \brief Indica que os comandos listados no campo *commands* são inválido. */
   exception InvalidCommandException { string message; };
   /** \brief Indica que */
   exception InvalidParameterException { string message; };
   /** \brief Indica que o SGA informado é inválido. */
   exception InvalidSGAException { string message; };
   /** \brief Indica que o solicitante não tem permissão para realizar a operação. */
   exception NoPermissionException { string message; };
   /** \brief Indica que o SGA informado já está cadastrado. */
   exception SGAAlreadyRegisteredException { string message; };
   /** \brief Indica que o SGA não está registrado. */
   exception SGANotRegisteredException { string message; };

   /**
    * \brief Interface implementada pelo SGA Manager (SSI)
    */
   interface SGAManager {
      /**
       * \brief SGA avisa ao manager que está ativo.
       *
       * \param sga Referência para o SGA.
       * \param sgaName Nome do SGA.
       * \param infos Informações (estáticas) com as propriedades do SGA.
       * \param updateInterval Informa de quanto em quanto tempo o SGA deve
       * dizer que está vivo.
       *
       * \exception InvalidParameterException Caso algum parâmetro informado
       * seja inválido.
       * \exception SGAAlreadyRegisteredException Caso o SGA já esteja
       * registrado.
       * \exception NoPermissionException Caso o solicitante não tenha permissão
       * para registrar o SGA.
       */
      void registerSGA(in SGADaemon sga,
        in string sgaName,
        in SGAProperties infos,
        out long updateInterval)
      raises (InvalidParameterException,
        SGAAlreadyRegisteredException,
        NoPermissionException);

      /**
       * \brief SGA avisa ao manager que sairá do ar.
       *
       * \param sga Referência para o SGA.
       * \param sgaName Nome do SGA.
       *
       * \exception SGANotRegisteredException Caso o SGA não esteja
       * registrado.
       * \exception NoPermissionException Caso o solicitante não tenha permissão
       * para desregistrar o SGA.
       */
      void unregisterSGA(in SGADaemon sga,
        in string sgaName)
      raises (SGANotRegisteredException,
        NoPermissionException);

      /**
       * \brief SGA indica que está acessível.
       *
       * \param sga Referência para o SGA
       * \param sgaName Nome do SGA
       *
       * \return *true* se o SGA estava acessível e seu registro está válido.
       */
      boolean isRegistered(in SGADaemon sga,
        in string sganame)
      raises (InvalidSGAException,
        NoPermissionException);

      // @TODO Revisar se o retorno dos métodos abaixo pode ser void pois os
      // erros são indicados por exceção.
      /**
       * \brief SGA envia seus os dados dinâmicos para o Manager.
       *
       * \param sga Referência para o SGA.
       * \param sgaName Nome do SGA.
       * \param infos Informações (dinâmicas) com as propriedades do SGA.
       *
       * \return *True* ee atualizou as informações.
       *
       * \exception InvalidParameterException Caso algum parâmetro informado
       * seja inválido.
       * \exception SGANotRegisteredException Caso o SGA não esteja
       * registrado.
       * \exception NoPermissionException Caso o solicitante não tenha permissão
       * para atualizar as informações do SGA.
       */
      boolean updateSGAInfo(in SGADaemon sga,
        in string sgaName,
        in SGAProperties infos)
      raises (InvalidParameterException,
        SGANotRegisteredException,
        NoPermissionException);

      /**
       * \brief SGA avisa ao manager que um comando terminou.
       *
       * \param sgaName Nome do SGA.
       * \param cmd Referência para o gerenciador de comando.
       * \param cmdId Identificador do comando.
       * \param info Informações sobre o término de execução do comando.
       *
       * \return *true* se o Manager aceitou a notificação ou *false* se o
       * Manager desconhece o SGA (pode acontecer se o Manager esteve fora do
       * ar, o que exige um novo registro do SGA)
       *
       * \exception InvalidSGAException Caso o SGA seja inválidp.
       * \exception InvalidCommandException Caso o comando seja inválido.
       * \exception NoPermissionException Caso o solicitante não tenha permissão
       * para atualizar as informações do comando.
       */
      boolean commandCompleted(in string sgaName,
        in SGACommand cmd,
        in string cmdid,
        in CompletedCommandInfo info)
      raises (InvalidSGAException,
        InvalidCommandException,
        NoPermissionException);

      /**
       * \brief SGA avisa ao manager que um comando foi perdido.
       *
       * \param sgaName Nome do SGA
       * \param cmdId Identificador do comando
       *
       * \return *true* se o Manager aceitou a notificação ou *false* se o
       * Manager desconhece o SGA (pode acontecer se o Manager esteve fora do
       * ar, o que exige um novo registro do SGA)
       *
       * \exception InvalidSGAException Caso o SGA seja inválidp.
       * \exception InvalidCommandException Caso o comando seja inválido.
       * \exception NoPermissionException Caso o solicitante não tenha permissão
       * para atualizar as informações do comando.
       */
      boolean commandLost(in string sgaName,
       in string cmdid)
      raises (InvalidSGAException,
        InvalidCommandException,
        NoPermissionException);

      /**
       * \brief SGA avisa ao manager que um comando foi recuperado.
       *
       * \param sganame Nome da máquina hospedeira do SGA
       * \param cmds Comandos recuperados pelo SGA.
       *
       * \return true se os comandos foram registrados com sucesso junto ao SSI
       *
       * \exception InvalidSGAException Caso o SGA seja inválidp.
       * \exception InvalidCommandException Caso o comando seja inválido.
       * \exception NoPermissionException Caso o solicitante não tenha permissão
       * para atualizar as informações do comando.
       */
      boolean commandRetrieved(in string sganame,
        in RetrievedCmds cmds)
      raises (InvalidSGAException,
       InvalidCommandException,
        NoPermissionException);
   };
};

#endif
