Todos
os problemas são relatados por meio de um objeto de exceção, que é uma subclasse
do objeto de exceção definido pelo WVCM. A partir dessa exceção, o cliente
pode obter as seguintes informações:
- Um código de razão (uma extensão de uma enumeração do WVCM), que classifica o
tipo de incidente sendo relatado (por exemplo, WvcmException.ReasonCode.READ_FAILED).
- Um código de razão subordinado, que fornece uma classificação mais refinada do
incidente dentro da classificação do código de razão (por exemplo, StpException.StpReasonCode.CONFLICT).
- Um identificador de mensagem independente do código do idioma (índice de catálogo) e valores de argumentos
específicos do incidente relatado. Essas informações são apropriadas para
fins de criação de log e também podem ser utilizadas para gerar uma mensagem localizada.
- Uma lista de exceções aninhadas, sendo que cada uma descreve um incidente subordinado
que contribuiu com o incidente relatado pela exceção.
- Para problemas de acesso a recursos, o recurso primário envolvido no incidente,
que é geralmente o recurso destinado pela operação que falhou.
- Para problemas de acesso a propriedades, a propriedade do recurso primário envolvida
no incidente.
- Para operações que endereçam vários recursos, uma lista dos recursos
que obtiverem êxito na operação.
- Para incidências selecionadas, informações adicionais específicas do incidente
relatado.
Cada operação define um conjunto de condições prévias que devem ser atendidas para que
a operação tenha êxito. Por exemplo, um recurso cujas propriedades serão lidas
deve existir, um recurso que tenha o mesmo nome que o recurso a ser criado não pode existir,
um recurso submetido ao registro de saída deve ter versão e registro de entrada.
Violações de tais condições prévias fazem com que a operação emita uma exceção.
As operações podem geralmente ser aplicadas a uma coleta de recursos. Se a operação
falhar em qualquer um eles, uma exceção será emitida (com os sucessos relatados
no objeto de exceção).
Os problemas que o servidor encontra ao ler ou gravar as propriedades ou metapropriedades de um recurso não fazem com que uma operação do Rational CM API emita uma exceção. Em vez disso, a exceção é associada à propriedade
no proxy retornado. A exceção será lançada apenas quando o cliente tenta extrair
esse valor da propriedade do proxy. O cliente também pode interrogar
o proxy antes de extrair o valor da propriedade para determinar se existem
problemas e para obter a exceção sem que ela seja emitida. Consulte o Informações Adicionais sobre Recursos.
O Rational CM
API inclui estes tipos principais de exceções:
- StpException (estende WvcmException)
- StpPropertyException (estende StpException)
- StpPartialResultsException (estende PropertyException)
StpException
StpException é
uma extensão de
WvcmException e é a classe-base de todas as
exceções verificadas emitidas pelo Rational CM API. Todas as implementações
de métodos definidos pelo WVCM emitem a WvcmException. Todos os métodos públicos do Rational CM
API que são extensões para o WVCM também emitem a WvcmException. Entretanto, as
implementações de todos esses métodos emitem consistentemente apenas StpExceptions,
não WvcmExceptions.
Estas convenções se aplicam:
- A emissão de uma StpException nunca é utilizada em nenhuma declaração de método (pública
ou outra diferente). Mesmo quando um método emite uma StpException, ele é declarado como
se emitisse uma WvcmException.
- Um método nunca emite uma nova WvcmException. Embora a exceção possa
ser expressa como uma WvcmException, ela é sempre emitida como uma nova StpException.
StpPropertyException
StpPropertyException estende
StpExtension e é classe de exceção base para erros associados à
leitura ou gravação de propriedades do recurso.
Depois que um valor da propriedade é
solicitado a partir de um servidor, seu nome é associado ao resultado e armazenado
em um proxy. Esse nome é associado ao valor recuperado, se a tentativa de recuperação
foi bem-sucedida, ou com informações de status (na forma de um objeto
StpPropertyException), se a tentativa de recuperação não foi bem-sucedida.
StpPartialResultsException
StpPartialResultsException
estende a StpPropertyException e é utilizada para relatar a falha de uma operação
ou propriedade que envolve vários recursos. Ela torna-se uma substituta
da ResourceList, que é geralmente retornada pela operação ou propriedade. Ela
contém uma ResourceList, que possui os proxies para os recursos que foram
processados com êxito, e uma Lista de StpExceptions, cada uma correspondendo
a um recurso para o qual a operação falhou. Para obter detalhes, consulte as
informações de Javadoc.