interface de serviço StateMachineService

A interface de serviço StateMachineService é fornecida pelo State Management para cada máquina de estados configurada, a fim de que uma SMControlApplication possa solicitar mudanças de estado de maneira direcionada por meio do método RequestTransition [SWS_SM_00600], [SWS_SM_91107]. O serviço é oferecido imediatamente após a conclusão bem-sucedida da etapa de inicialização da máquina de estados e confirma solicitações sem semântica de Fire-and-Forget. No entanto, solicitações são rejeitadas com erros específicos se o valor fornecido for inválido, se a transição a partir do estado atual não for permitida ou se uma sessão de atualização ou de recuperação estiver ativa simultaneamente [SWS_SM_91107].

mais ›

Papel e contexto de sistema da interface de serviço

A interface de serviço StateMachineService é fornecida pelo cluster funcional State Management (SM) por meio de uma porta de serviço padronizada [SWS_SM_91021]. De acordo com a definição formal de interface [SWS_SM_91022], o State Management instancia e oferece esse serviço baseado em ara::com para cada instância configurada individual de uma StateMachine [SWS_SM_00600].

Como consumidor primário dessa interface atua uma SMControlApplication, a qual interage diretamente com a máquina de estados por meio do serviço para solicitar mudanças de estado SWS StateManagement §9.2.2 «StateMachine service». Enquanto notificações sobre estados ocorridos para aplicações adaptativas regulares são realizadas primariamente por meio da interface de serviço separada StateMachineNotification [SWS_SM_00665], StateMachineService forma a interface de controle ativa para a iniciação de transições.

Métodos e semântica de chamada

A interface define o método RequestTransition, que precisa ser chamado pela SMControlApplication para provocar uma mudança de estado na StateMachine referenciada [SWS_SM_91107]. O método espera o parâmetro de entrada TransitionRequest do tipo TransitionRequestType, que representa o valor de transição requerido dentro da TransitionRequestTable subjacente [SWS_SM_91107], SWS StateManagement §7.x «TransitionRequestTable».

Para RequestTransition, a propriedade Fire & Forget está definida como false [SWS_SM_91107]. A aplicação chamadora recebe, assim, uma confirmação vinculativa da requisição. Interpretação: dentro do padrão proxy-skeleton de ara::com, o retorno deve ser fornecido tipicamente por meio de um ara::core::Future ou de um respectivo objeto de resultado, que resolve em caso de sucesso ou transmite um status de erro específico em caso de falha. Pergunta Q-41fa67738672c735 (aberta)

Ciclo de vida e dependências de estado

Cada serviço ara::com configurado para uma StateMachine a ser iniciada – incluindo StateMachineService – precisa estar disponível e ser oferecido (Offer) assim que o ActionListItem «StartStateMachine» tiver sido processado com sucesso [SWS_SM_00618]. Isso permite à SMControlApplication solicitar uma transição imediatamente após a criação bem-sucedida da máquina de estados, mesmo que a máquina de estados ainda esteja processando a ActionList inicial nesse momento SWS StateManagement §7.x «StateMachine service interfaces - Offer».

A oferta do serviço é encerrada (StopOffer) assim que ocorre o processamento para parar a respectiva máquina de estados [SWS_SM_00619]. Além disso, as chamadas estão sujeitas a pré-requisitos funcionais: se uma sessão de atualização estiver em execução no sistema no momento, a iniciação de mudanças de estado é, por princípio, inadmissível [SWS_SM_91107].

Tratamento de erros e Application Errors

Durante a execução de RequestTransition, podem ocorrer Application Errors específicos, que são retornados pelo State Management ao chamador [SWS_SM_91107]:

• kInvalidValue: o valor fornecido não está associado a nenhuma transição na TransitionRequestTable [SWS_SM_91107].
• kTransitionNotAllowed: a transição de estado solicitada não é permitida a partir do estado atual da StateMachine [SWS_SM_91107].
• kRecoveryTransitionOngoing: a solicitação é descartada, pois uma recuperação (recovery) está sendo executada no momento [SWS_SM_91107].
• kTransitionFailed: ocorreu um erro durante a execução da transição para o estado de destino [SWS_SM_91107].
• kOperationCanceled: a solicitação foi cancelada porque foi substituída por uma solicitação mais recente [SWS_SM_91107].
• kUpdateInProgress: a operação é proibida porque uma sessão de atualização está ativa no momento [SWS_SM_91107].

Diagrama de sequência: fluxo de uma solicitação de transição via StateMachineService com disponibilização, confirmação de sucesso e tratamento de erros. Fontes: [SWS_SM_91107], [SWS_SM_00618], SWS StateManagement §7.x «StateMachine service interfaces - Offer».