classe ara::com::ComErrorDomain

A classe ara::com::ComErrorDomain representa o domínio de erros de comunicação para identificação de erros gerais e não específicos de interface na API ara::com ([SWS_CM_11265]). Ela fornece descrições de erros para códigos de erro como ComErrc::kCommunicationFailure e permite sua consulta via Message() ou a conversão em uma exceção por meio de ThrowAsException() ([SWS_CM_11332]). Como seu construtor padrão está excluído, ela atua como uma instância de domínio sem estado e thread-safe para o ara::core::Result portador do erro.

mais ›

Contexto

A classe ara::com::ComErrorDomain representa o domínio padronizado de erros de comunicação da Adaptive Platform para o cluster funcional Communication Management (SWS CommunicationManagement p. 439). Ela deriva da classe base ara::core::ErrorDomain e define o contexto semântico para erros gerais que podem ocorrer durante chamadas de método ou transmissões de dados, mas que não são específicos de um ServiceInterface individual ([SWS_CM_11265]). Na arquitetura de erros de ara::com, ela delimita sistematicamente falhas gerais de comunicação contra erros de monitoramento de E2E e erros de serviço específicos da aplicação (SWS CommunicationManagement §7.5.22.6 «Error Related Data Types»).

Entre seus parceiros centrais de interação estão a Adaptive Application, as implementações de serviço e de proxy do middleware, bem como os tipos de dados ara::core::ErrorCode e ara::core::Result do sistema básico (EXP ARAComAPI §4.7 «Error Handling»). Para a vinculação semântica de tipos, a classe disponibiliza os aliases de tipo Errc para a enumeração de códigos de erro ComErrc ([SWS_CM_11336]) e Exception para a classe de exceção associada ComException ([SWS_CM_11337]).

Diagrama de contexto: enquadramento da ComErrorDomain na arquitetura de erros de ara::com. Fontes: [SWS_CM_11265], EXP ARAComAPI §4.7 «Error Handling», SWS CommunicationManagement §7.5.22.6 «Error Related Data Types»

Ciclo de vida

Como classe de especificação para um domínio de erro, a criação de ara::com::ComErrorDomain é impedida pela exclusão do construtor padrão ComErrorDomain() = delete; ([SWS_CM_11330]). Interpretação: a disponibilização da instância de domínio deve ocorrer como singleton estático por meio da plataforma, de modo que os componentes da aplicação não precisam instanciar ou gerenciar o domínio dinamicamente. Pergunta Q-bf957a108c0a5378 (aberta)

A instância atua como um descritor sem estado, sem atributos mutáveis. Todos os métodos disponibilizados, como Name() ([SWS_CM_11331]) e Message() ([SWS_CM_11332]), são declarados como const noexcept. Isso assegura segurança irrestrita entre threads em consultas concorrentes de erro realizadas por threads paralelas da aplicação e do middleware.

Caminho de utilização

O caminho de utilização típico abrange a detecção, a transmissão e a avaliação de um erro por meio das interfaces de ara::com:

1. A aplicação inicia uma interação de serviço, por exemplo, por meio do operador de chamada da classe de método operator() ([SWS_CM_00196]).
2. Se o middleware detectar uma falha durante o processamento, como uma falha de comunicação ou um erro de aplicação não configurado ([SWS_CM_00048]), a operação SetError é chamada no Promise correspondente (SWS CommunicationManagement p. 300).
3. Nesse processo, é construído um ara::core::ErrorCode cujo domínio está definido como ara::com::ComErrorDomain ([SWS_CM_11329]) e cujo código numérico está definido como um valor de enumeração específico como ComErrc::kCommunicationFailure ([SWS_CM_10432]).
4. O ara::core::Future ou ara::core::Result retornado à aplicação transporta o código de erro no estado de erro para o chamador (EXP ARAComAPI §4.7 «Error Handling»).
5. A aplicação verifica o Result e utiliza as funções de domínio Name() ([SWS_CM_11331]) e Message() ([SWS_CM_11332]) para resolver mensagens de erro para fins de registro em log ou diagnóstico.
6. Se a lógica da aplicação esperar uma exceção e as exceções C++ estiverem ativadas, a conversão em uma ComException pode ser disparada por meio de ThrowAsException() ([SWS_CM_11333]).

Diagrama de sequência: sinalização e consulta de um erro de comunicação via ComErrorDomain. Fontes: [SWS_CM_00196], [SWS_CM_10432], [SWS_CM_11329], [SWS_CM_11332], SWS CommunicationManagement p. 300

Cenários de erro

O conceito de erros de ara::com distingue estritamente entre erros recuperáveis (Recoverable Errors) e violações graves de programação (Violations ou Corruptions) (EXP ARAComAPI §4.7 «Error Handling»). Erros recuperáveis são tratados por meio de ara::core::Result e ara::core::ErrorCode, sendo os códigos de erro do domínio ComErrorDomain endereçados por meio do alias de identificador Errc ([SWS_CM_11336]).

Se ocorrer, por exemplo, uma interrupção de transmissão durante uma chamada remota, o sistema reporta ComErrc::kCommunicationFailure ([SWS_CM_10432]). Em caso de erro de aplicação não configurado, o middleware aborta a chamada e também define um código de erro correspondente do domínio ([SWS_CM_00048], SWS CommunicationManagement p. 300).

Se um código de erro dever ser lançado como exceção, ThrowAsException() instancia uma exceção do tipo ComException ([SWS_CM_11337]) e a lança ([SWS_CM_11333]). Esse método não é seguro contra exceções (not exception safe) e, de acordo com a especificação, não participa da resolução de sobrecarga quando as exceções C++ estão desativadas ([SWS_CM_11333]). Violações de sistema não recuperáveis, por outro lado, levam diretamente à interrupção da plataforma e não são tratadas por meio de ComErrorDomain (EXP ARAComAPI §4.7 «Error Handling»).