Tous les incidents sont signalés au moyen d'un objet d'exception, qui constitue une sous-classe de l'objet d'exception défini par WVCM. A partir d'une telle exception, le client peut obtenir les informations suivantes :
- Un code raison (une extension d'une énumération WVCM), qui classe le type d'incident signalé (par exemple WvcmException.ReasonCode.READ_FAILED).
- Un code raison secondaire, qui donne une classification plus fine de l'incident dans le cadre de la classification du code raison (par exemple, StpException.StpReasonCode.CONFLICT).
- Un identifiant de message indépendant de l'environnement local (index de catalogue) avec des valeurs d'argument spécifiques à l'incident signalé. Ces informations conviennent à la journalisation et peuvent également être utilisées pour générer un message localisé.
- Une liste des exceptions imbriquées, dont chacune décrit un incident secondaire qui a contribué à l'incident signalé par l'exception.
- Pour les problèmes d'accès aux ressources, la ressource principale impliquée dans l'incident, qui est généralement la ressource ciblée par l'opération qui a échoué.
- Pour les problèmes d'accès aux propriétés, la propriété de la ressource principale impliquée dans l'incident.
- Pour les opérations qui gèrent plusieurs ressources, une liste des ressources pour lesquelles l'opération a réussi.
- Pour des incidents sélectionnés, des informations supplémentaires spécifiques à l'incident signalé.
Chaque opération définit un ensemble de conditions préalables qui doivent être satisfaites afin que l'opération réussisse. Par exemple, une ressource dont les propriétés doivent être lues doit exister, une ressource ayant le même nom que la ressource qui doit être créée ne peut pas exister, une ressource à extraire doit être versionnée et archivée.
Le non-respect de ces conditions préalables peut entraîner une exception par l'opération.
Un ensemble de ressources peut souvent être appliqué aux opérations. Si l'opération échoue sur l'une d'entre elles, une exception est renvoyée (les succès étant répertoriés dans l'objet d'exception).
Les problèmes rencontrés par le serveur pendant la lecture ou l'écriture des propriétés ou méta-propriétés d'une ressource n'entraînent pas le fait qu'une opération de l'API CMRational lance une exception. A l'inverse, l'exception est associée à la propriété dans le proxy renvoyé. Ce n'est que lorsque le client tente d'extraire du proxy cette valeur de propriété que l'exception est générée. Le client peut également interroger le proxy avant d'extraire la valeur de propriété afin de déterminer si des problèmes existent et obtenir l'exception, sans qu'elle soit renvoyée. Voir Informations supplémentaires concernant les propriétés.
L'API CM Rational
comprend ces principaux types d'exceptions :
- StpException (étend WvcmException)
- StpPropertyException (étend StpException)
- StpPartialResultsException (étend PropertyException)
StpException
StpException est une extension de
WvcmException et constitue la classe de base de toutes les exceptions vérifiées renvoyées par l'API CM Rational. Toutes les implémentations des méthodes définies par WVCM renvoient WvcmException. Toutes les méthodes publiques de l'API CMRational
qui sont des extensions de WVCM génèrent également WvcmException. Toutefois, les implémentations de toutes ces méthodes génèrent de manière constante, uniquement les StpExceptions, et non les WvcmExceptions.
Ces conventions s'appliquent :
- Le renvoi d'une StpException est jamais utilisé dans aucune déclaration de méthode (publique ou autre). Même lorsqu'une méthode génère une StpException, elle est déclarée comme si elle générait une WvcmException.
- Une méthode ne génère jamais de nouvelle WvcmException. Bien que l'exception puisse être exprimée en tant que WvcmException, elle est toujours générée en tant que nouvelle StpException.
StpPropertyException
StpPropertyException étend
StpExtension est constitue la classe d'exception de base pour les erreurs associées à la lecture ou l'écriture des propriétés de ressource.
Après qu'une valeur de propriété est demandée depuis un serveur, son nom est associé au résultat et stocké dans un proxy. Ce nom est associé à la valeur récupérée si la tentative de récupération a réussi ou aux informations sur l'état (sous la forme d'un objet StpPropertyException) en cas d'échec de la tentative de récupération.
StpPartialResultsException
StpPartialResultsException
étend StpPropertyException et est utilisé pour signaler l'échec d'une opération ou d'une propriété impliquant plusieurs ressources. Elle devient un substitut de la ResourceList qui est généralement renvoyée par l'opération ou la propriété. Elle contient une ResourceList, qui possède les proxys des ressources qui ont été traitées avec succès, et une liste des StpExceptions, dont chacune correspond à une ressource pour laquelle l'opération a échoué. Pour plus de détails, consultez les informations Javadoc.