Alle Fehler werden
mit Hilfe eines Exception-Objekts gemeldet, das eine Unterklasse des vom WVCM definierten Exception-Objekts ist.
Der Client kann die folgenden Informationen aus einer Ausnahme
abrufen:
- Einen Ursachencode (Erweiterung einer WVCM-Aufzählung), der den Typ des gemeldeten Vorfalls klassifiziert
(z. B. WvcmException.ReasonCode.READ_FAILED)
- Einen untergeordneten Ursachencode mit einer differenzierteren Klassifizierung des Vorfalls innerhalb der Klassifizierung des Ursachencodes
(z. B. StpException.StpReasonCode.CONFLICT)
- Eine sprachunabhängige Nachrichten-ID (Katalogindex) und spezifische Argumentwerte für den gemeldeten Vorfall (Diese Informationen sind für
Protokollierungszwecke geeignet und können auch zum Generieren einer lokalisierten Nachricht verwendet werden.)
- Eine Liste verschachtelter Ausnahmen, von denen jede einen untergeordneten Vorfall beschreibt, der zu dem von der Ausnahme gemeldeten Vorfall beigetragen hat
- Bei Problemen mit dem Ressourcenzugriff die Ressource, die primär am Vorfall beteiligt war, wobei es sich in der Regel um die Zielressource der fehlgeschlagenen Operation
handelt
- Bei Problemen mit dem Zugriff auf Eigenschaften die Eigenschaft der Ressource, die primär am Vorfall beteiligt war
- Bei Operationen mit mehreren Zielressourcen eine Liste der Ressourcen, für die die Operation erfolgreich ausgeführt wurde
- Bei ausgewählten Vorfällen zusätzliche Informationen zum gemeldeten Vorfall
Jede Operation definiert eine Reihe von Vorbedingungen, die erfüllt sein müssen, damit die Operation erfolgreich ausgeführt werden kann. So muss eine Ressource, deren Eigenschaften gelesen werden sollen, vorhanden sein, und eine Ressource, die denselben Namen wie eine zu erstellende Ressource hat,
darf es nicht geben. Eine Ressource, die ausgecheckt werden soll, muss versionsgesteuert und eingecheckt sein.
Die Nichterfüllung solcher Vorbedingungen hat zur Folge, dass die Operation eine Ausnahme auslöst.
Operationen können häufig auf eine Gruppe von Ressourcen angewendet werden. Schlägt die Operation für eine der Ressourcen fehl, wird eine
Ausnahme ausgelöst. (Das Exception-Objekt meldet die erfolgreichen Verläufe der Operation.)
Probleme, die der Server beim Lesen oder Schreiben der Eigenschaften bzw.
Metaeigenschaften einer Ressource feststellt, führen nicht dazu, dass eine
ClearQuest CM API-Operation eine
Ausnahme auslöst. Die Ausnahme wird stattdessen der Eigenschaft innerhalb des zurückgegebenen Proxys zugeordnet. Erst wenn der Client versucht, diesen Eigenschaftswert aus dem Proxy zu extrahieren, wird die
Ausnahme ausgelöst. Bevor der Client den Eigenschaftswert extrahiert, kann er
den Proxy auch befragen, um festzustellen, ob Probleme vorliegen, und die
Ausnahme empfangen, ohne dass sie ausgelöst wird. Siehe
Abschnitt Zusätzliche Informationen zu Eigenschaften.
Die ClearQuest CM API umfasst
die folgenden Hauptarten von Ausnahmen:
- StpException (erweitert WvcmException)
- StpPropertyException (erweitert StpException)
- StpPartialResultsException (erweitert PropertyException)
StpException
StpException
ist eine Erweiterung von
WvcmException und
die Basisklasse aller geprüften Ausnahmen, die von der
ClearQuest CM API ausgelöst
werden. Alle Implementierungen von Methoden, die in WVCM definiert sind, lösen
WvcmException aus. Alle allgemein
zugänglichen Methoden der
ClearQuest CM API, die
Erweiterungen zu WVCM sind, lösen ebenfalls
WvcmException aus. Die Implementierungen
aller dieser Methoden lösen jedoch konsistent nur Ausnahmen
StpException und keine Ausnahmen
WvcmException aus. Es gelten folgende Konventionen:
- In einer Methodendeklaration (für eine allgemein zugängliche Methode oder
eine andere Methode) wird nie eine StpException ausgelöst.
Selbst wenn eine Methode eine StpException auslöst, wird sie
deklariert, als würde sie eine WvcmException auslösen.
- Eine Methode löst nie eine neue WvcmException aus. Obwohl
die Ausnahme als eine WvcmException ausgedrückt werden kann,
wird sie stets als eine neue StpException ausgelöst.
StpPropertyException
StpPropertyException
erweitert StpException und ist die Basisausnahmeklasse für
Fehler im Zusammenhang mit dem Lesen oder Schreiben von Ressourceneigenschaften.
Nachdem ein Eigenschaftswert von einem Server angefordert wurde, wird der
Name dem Ergebnis zugeordnet und in einem Proxy gespeichert. War der
Abrufversuch erfolgreich, wird dieser Name dem abgerufenen Wert zugeordnet. Bei
einem nicht erfolgreichen Abrufversuch wird der Name Statusinformationen (in
Form eines StpPropertyException-Objekts) zugeordnet.
StpPartialResultsException
StpPartialResultsException
erweitert StpPropertyException und wird verwendet, um das
Fehlschlagen einer Operation oder einer Eigenschaft, die für mehrere Ressourcen
gilt, zu melden. Diese Ausnahme wird als Ersatz
für die ResourceList verwendet, die normalerweise von der Operation oder Eigenschaft zurückgegeben wird. Sie enthält eine
ResourceList mit den Proxys für die erfolgreich verarbeiteten Ressourcen und eine Liste mit
StpExceptions, die jeweils einer Ressource entsprechen, für die die Operation gescheitert ist. Die
Javadoc-Informationen enthalten Details.