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.
O cliente pode obter as seguintes informações a
partir de uma exceção:
- 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 ClearQuest
CM API lance 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 ClearQuest CM API
inclui estes tipos principais de exceções:
- StpException (estende WvcmException)
- StpPropertyException (estende StpException)
- StpPartialResultsException (estende PropertyException)
StpException
A
StpException é uma extensão do
WvcmException e é a classe base
de todas as exceções verificadas lançadas pelo
ClearQuest CM API. Todas
as implementações de métodos definidos pelo WVCM lançam
WvcmException.
Todos os métodos públicos do
ClearQuest CM API que
são extensões para o WVCM também lançam
WvcmException.
No entanto, as implementações de todos esses métodos lançam
consistentemente apenas
StpExceptions, não
WvcmExceptions.
Estas convenções se aplicam:
- O lance de uma StpException nunca é usado em
qualquer declaração de método (público ou não). Mesmo quando um
método lança uma StpException ele é declarado como
se lançasse uma WvcmExceptions.
- Um método nunca lança uma nova WvcmExceptions.
Embora a exceção possa ser expressa como uma
WvcmExceptions, ela sempre será lançada como uma
nova StpException.
StpPropertyException
A
StpPropertyException estende a
StpException e é a classe de exceção base para os
erros associados à leitura ou à gravação das 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 será associado ao valor recuperado se a
tentativa de recuperação for bem-sucedida ou com informações de
status (na forma de um objeto StpPropertyException),
caso a tentativa de recuperação tenha sido mal-sucedida.
StpPartialResultsException
A
StpPartialResultsException estende a
StpPropertyException e é usada para relatar a falha
de uma operação ou propriedade que envolva diversos 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. Consulte as informações
do Javadoc para obter detalhes.