classe ara::com::ComException

A classe ara::com::ComException atua no AUTOSAR Adaptive como a classe central de exceção para sinalizar erros em chamadas da API de comunicação [SWS_CM_11327]. Ela encapsula um ara::core::ErrorCode e é instanciada e lançada em caso de falha nas operações, sendo seu construtor definido como seguro contra exceções e que não lança exceções [SWS_CM_11328]. Se as exceções C++ estiverem desativadas na toolchain do compilador, as sobrecargas da API que lançam exceções são totalmente excluídas da resolução de sobrecarga. Os chamadores capturam o objeto de exceção para analisar o código de erro contido e iniciar medidas de tratamento de erros.

mais ›

Contexto

A classe ara::com::ComException atua no módulo com da AUTOSAR Adaptive Platform como classe de exceção especializada para sinalizar erros em chamadas da API de comunicação [SWS_CM_11327]. Ela deriva publicamente da classe base ara::core::Exception e é declarada como final. Isso evidencia a integração direta na arquitetura abrangente de tratamento de erros da Adaptive Platform. Pela marcação como final, a classe deve ter sido projetada como um tipo de exceção selado, não previsto para uma hierarquia de derivação adicional. Pergunta Q-2454b5b73295287b (aberta)

A principal função de ara::com::ComException consiste em encapsular um estado de erro ocorrido na forma de um ara::core::ErrorCode e transmiti-lo às camadas chamadoras através do mecanismo de exceção do C++ [SWS_CM_11328]. A declaração e a definição são disponibilizadas através do cabeçalho #include "ara/com/com_error_domain.h" [SWS_CM_11328]. Como parceiros centrais de interação atuam o software de aplicação usuário, as funções internas de serviço e de API do gerenciamento de comunicação, bem como os tipos do domínio de erro ara::core::ErrorCode.

Ciclo de vida

O ciclo de vida de um objeto ara::com::ComException inicia na implementação de uma função da API do gerenciamento de comunicação assim que uma operação falha e a exceção é instanciada e disparada AUTOSAR_AP_SWS_CommunicationManagement §8.12.5 «Class: ComException». A criação ocorre através do construtor explícito, que recebe o objeto ara::core::ErrorCode causador [SWS_CM_11328].

Este construtor é declarado com noexcept e possui a propriedade exception safe [SWS_CM_11328]. Isso garante que nenhuma outra exceção possa ocorrer durante a própria construção do objeto de exceção. Após ser lançada via throw, o objeto é transportado no âmbito do stack unwinding até ser capturado em um bloco catch apropriado da camada chamadora. Quanto às relações de posse, a instância é automaticamente destruída na pilha após sair do bloco de tratamento. A classe não apresenta transições de estado internas no sentido de uma máquina de estados; seu estado permanece imutável após a inicialização com o código de erro.

Caminho de utilização

O fluxo de uso típico descreve a sequência de detecção de erros, disparo da exceção e subsequente tratamento:

1. Uma função da aplicação chama uma operação da interface ara::com.
2. Se ocorrer um erro durante o processamento, a implementação da API cria uma nova instância de ara::com::ComException a partir do errorCode correspondente e a lança AUTOSAR_AP_SWS_CommunicationManagement §8.12.5 «Class: ComException».
3. A aplicação captura a exceção em um bloco adequado. A captura no lado da aplicação ocorre presumivelmente por referência constante (const ara::com::ComException&) para evitar operações de cópia. Pergunta Q-5270e026eeac8be7 (aberta)
4. Através da interface da classe base, o chamador acessa o ara::core::ErrorCode contido e executa etapas de diagnóstico ou compensação [SWS_CM_11328].

Diagrama de sequência: fluxo de detecção de erro, instanciação e tratamento de ara::com::ComException. Fontes: [SWS_CM_11327], [SWS_CM_11328], AUTOSAR_AP_SWS_CommunicationManagement §8.12.5 «Class: ComException»

Cenários de erro

No contexto do tratamento de erros e da configuração da toolchain, aplicam-se as seguintes condições e casos de borda:

• Exceções C++ desativadas: se as exceções C++ estiverem desativadas na toolchain do compilador, as funções de API que criam e lançam ara::com::ComException não participam da resolução de sobrecarga conforme [SWS_CORE_10304] AUTOSAR_AP_SWS_CommunicationManagement §8.12.5 «Class: ComException». Nesse caso, o software de tratamento de erros recorre a mecanismos alternativos de retorno.
• Segurança de tipos do construtor: como o construtor é declarado como explicit, conversões implícitas de tipo são impedidas na passagem do ara::core::ErrorCode [SWS_CM_11328].
• Captura hierárquica: como ara::com::ComException herda de ara::core::Exception, os chamadores podem tratar exceções especificamente como ara::com::ComException ou de forma genérica através de manipuladores para a classe base.