16. Precondition/Postcondition XML Elements (Vorbedingung/Nachbedingung XML-Elemente)

Wie in Abschnitt 8.7 eingeführt, können zusätzliche Informationen über Fehlerbedingungen im Körper vieler Statusantworten enthalten sein. Dieser Abschnitt stellt Anforderungen an die Verwendung des Fehlerköper-Mechanismus und führt eine Reihe von Vorbedingungen und Nachbedingungen ein.

Eine "Vorbedingung (precondition)" einer Methode beschreibt den Zustand des Servers, der wahr sein muss, damit diese Methode ausgeführt werden kann. Eine "Nachbedingung (postcondition)" einer Methode beschreibt den Zustand des Servers, der wahr sein muss, nachdem diese Methode abgeschlossen wurde.

Jede Vorbedingung und Nachbedingung hat ein eindeutiges XML-Element, das mit ihr verbunden ist. In einer 207 Multi-Status-Antwort MUSS das XML-Element innerhalb eines 'error'-Elements im entsprechenden 'propstat- oder 'response'-Element erscheinen, je nachdem, ob die Bedingung auf eine oder mehrere Eigenschaften oder auf die Ressource als Ganzes zutrifft. In allen anderen Fehlerantworten, bei denen der 'error'-Körper dieser Spezifikation verwendet wird, MUSS das Vorbedingung/Nachbedingung-XML-Element als Kind eines 'error'-Elements der obersten Ebene im Antwortkörper zurückgegeben werden, sofern nicht anders durch die Anfrage verhandelt, zusammen mit einem entsprechenden Antwortstatus. Die häufigsten Antwortstatuscodes sind 403 (Forbidden), wenn die Anfrage nicht wiederholt werden sollte, weil sie immer fehlschlagen wird, und 409 (Conflict), wenn erwartet wird, dass der Benutzer den Konflikt möglicherweise lösen und die Anfrage erneut senden kann. Das 'error'-Element KANN Kindelemente mit spezifischen Fehlerinformationen enthalten und KANN mit beliebigen benutzerdefinierten Kindelementen erweitert werden.

Dieser Mechanismus ersetzt nicht die Verwendung eines korrekten numerischen Statuscodes, wie hier oder in HTTP definiert, da der Client immer in der Lage sein muss, eine vernünftige Vorgehensweise nur auf der Grundlage des numerischen Codes zu wählen. Es beseitigt jedoch die Notwendigkeit, neue numerische Codes zu definieren. Die neuen maschinenlesbaren Codes, die für diesen Zweck verwendet werden, sind XML-Elemente, die als Vorbedingungen und Nachbedingungen klassifiziert sind, sodass natürlich jede Gruppe, die einen neuen Bedingungscode definiert, ihren eigenen Namespace verwenden kann. Wie immer ist der Namespace "DAV:" für die Verwendung durch IETF-beauftragte WebDAV-Arbeitsgruppen reserviert.

Ein Server, der diese Spezifikation unterstützt, SOLLTE den XML-Fehler verwenden, wenn eine in diesem Dokument definierte Vorbedingung oder Nachbedingung verletzt wird. Für Fehlerbedingungen, die in diesem Dokument nicht spezifiziert sind, KANN der Server einfach einen geeigneten numerischen Status wählen und den Antwortkörper leer lassen. Ein Server KANN jedoch stattdessen einen benutzerdefinierten Bedingungscode und anderen unterstützenden Text verwenden, da selbst wenn Clients Bedingungscodes nicht automatisch erkennen, sie bei Interoperabilitätstests und Debugging sehr nützlich sein können.

Beispiel - Antwort mit Vorbedingungscode:

HTTP/1.1 423 Locked
Content-Type: application/xml; charset="utf-8"
Content-Length: xxxx

<?xml version="1.0" encoding="utf-8" ?>
<D:error xmlns:D="DAV:">
  <D:lock-token-submitted>
    <D:href>/workspace/webdav/</D:href>
  </D:lock-token-submitted>
</D:error>

In diesem Beispiel versuchte ein Client, der sich einer Tiefe-Unendlich-Sperre auf der übergeordneten Sammlung "/workspace/webdav/" nicht bewusst war, das Sammlungsmitglied "/workspace/webdav/proposal.doc" zu ändern.

Einige andere nützliche Vorbedingungen und Nachbedingungen wurden in anderen Spezifikationen definiert, die WebDAV erweitern, wie [RFC3744] (siehe insbesondere Abschnitt 7.1.1), [RFC3253] und [RFC3648].

Alle diese Elemente befinden sich im Namespace "DAV:". Sofern nicht anders angegeben, ist der Inhalt des XML-Elements jeder Bedingung als leer definiert.

lock-token-matches-request-uri

Name: lock-token-matches-request-uri

Verwendung mit (Use with): 409 Conflict

Zweck (Purpose): (Vorbedingung) -- Eine Anfrage kann einen Lock-Token-Header enthalten, um eine Sperre für die UNLOCK-Methode zu identifizieren. Wenn jedoch die Request-URI nicht in den Geltungsbereich der durch das Token identifizierten Sperre fällt, SOLLTE der Server diesen Fehler verwenden. Die Sperre kann einen Geltungsbereich haben, der die Request-URI nicht einschließt, oder die Sperre könnte verschwunden sein, oder das Token könnte ungültig sein.

lock-token-submitted

Name: lock-token-submitted (Vorbedingung)

Verwendung mit (Use with): 423 Locked

Zweck (Purpose): Die Anfrage konnte nicht erfolgreich sein, weil ein Sperr-Token hätte eingereicht werden müssen. Dieses Element MUSS, falls vorhanden, mindestens eine URL einer gesperrten Ressource enthalten, die die Anfrage verhindert hat. In Fällen von MOVE, COPY und DELETE, bei denen Sammlungssperren beteiligt sind, kann es für den Client schwierig sein, herauszufinden, welche gesperrte Ressource die Anfrage zum Scheitern gebracht hat -- aber der Server ist nur dafür verantwortlich, eine solche gesperrte Ressource zurückzugeben. Der Server KANN jede gesperrte Ressource zurückgeben, die den Erfolg der Anfrage verhindert hat, wenn er sie alle kennt.

<!ELEMENT lock-token-submitted (href+) >

no-conflicting-lock

Name: no-conflicting-lock (Vorbedingung)

Verwendung mit (Use with): Typischerweise 423 Locked

Zweck (Purpose): Eine LOCK-Anfrage ist aufgrund des Vorhandenseins einer bereits bestehenden konfliktierenden Sperre fehlgeschlagen. Beachten Sie, dass eine Sperre in Konflikt sein kann, obwohl die Ressource, an die die Anfrage gerichtet war, nur indirekt gesperrt ist. In diesem Fall kann der Vorbedingungscode verwendet werden, um den Client über die Ressource zu informieren, die die Wurzel der konfliktierenden Sperre ist, wodurch eine separate Suche nach der Eigenschaft "lockdiscovery" vermieden wird.

<!ELEMENT no-conflicting-lock (href)* >

no-external-entities

Name: no-external-entities

Verwendung mit (Use with): 403 Forbidden

Zweck (Purpose): (Vorbedingung) -- Wenn der Server eine Client-Anfrage ablehnt, weil der Anfragekörper eine externe Entität enthält, SOLLTE der Server diesen Fehler verwenden.

preserved-live-properties

Name: preserved-live-properties

Verwendung mit (Use with): 409 Conflict

Zweck (Purpose): (Nachbedingung) -- Der Server hat eine ansonsten gültige MOVE- oder COPY-Anfrage erhalten, kann aber die Live-Eigenschaften mit demselben Verhalten am Ziel nicht aufrechterhalten. Es kann sein, dass der Server nur einige Live-Eigenschaften in einigen Teilen des Repositorys unterstützt oder einfach einen internen Fehler hat.

propfind-finite-depth

Name: propfind-finite-depth

Verwendung mit (Use with): 403 Forbidden

Zweck (Purpose): (Vorbedingung) -- Dieser Server erlaubt keine PROPFIND-Anfragen mit unendlicher Tiefe für Sammlungen.

cannot-modify-protected-property

Name: cannot-modify-protected-property

Verwendung mit (Use with): 403 Forbidden

Zweck (Purpose): (Vorbedingung) -- Der Client hat versucht, eine geschützte Eigenschaft in einem PROPPATCH zu setzen (wie DAV:getetag). Siehe auch [RFC3253], Abschnitt 3.12.