16. Precondition/Postcondition XML Elements (Éléments XML de précondition/postcondition)

Comme introduit dans la section 8.7, des informations supplémentaires sur les conditions d'erreur peuvent être incluses dans le corps de nombreuses réponses d'état. Cette section formule des exigences sur l'utilisation du mécanisme de corps d'erreur et introduit un certain nombre de codes de précondition et de postcondition.

Une "précondition" d'une méthode décrit l'état du serveur qui doit être vrai pour que cette méthode soit exécutée. Une "postcondition" d'une méthode décrit l'état du serveur qui doit être vrai après que cette méthode ait été complétée.

Chaque précondition et postcondition a un élément XML unique qui lui est associé. Dans une réponse 207 Multi-Status, l'élément XML DOIT apparaître à l'intérieur d'un élément 'error' dans l'élément 'propstat ou 'response' approprié selon que la condition s'applique à une ou plusieurs propriétés ou à la ressource dans son ensemble. Dans toutes les autres réponses d'erreur où le corps 'error' de cette spécification est utilisé, l'élément XML de précondition/postcondition DOIT être retourné en tant qu'enfant d'un élément 'error' de niveau supérieur dans le corps de la réponse, sauf négociation contraire par la requête, avec un état de réponse approprié. Les codes d'état de réponse les plus courants sont 403 (Forbidden) si la requête ne doit pas être répétée car elle échouera toujours, et 409 (Conflict) s'il est prévu que l'utilisateur puisse résoudre le conflit et soumettre à nouveau la requête. L'élément 'error' PEUT contenir des éléments enfants avec des informations d'erreur spécifiques et PEUT être étendu avec n'importe quels éléments enfants personnalisés.

Ce mécanisme ne remplace pas l'utilisation d'un code d'état numérique correct tel que défini ici ou dans HTTP, car le client doit toujours être capable de prendre une ligne de conduite raisonnable basée uniquement sur le code numérique. Cependant, cela élimine le besoin de définir de nouveaux codes numériques. Les nouveaux codes lisibles par machine utilisés à cette fin sont des éléments XML classés comme préconditions et postconditions, donc naturellement, tout groupe définissant un nouveau code de condition peut utiliser son propre espace de noms. Comme toujours, l'espace de noms "DAV:" est réservé à l'usage des groupes de travail WebDAV agréés par l'IETF.

Un serveur prenant en charge cette spécification DEVRAIT utiliser l'erreur XML chaque fois qu'une précondition ou postcondition définie dans ce document est violée. Pour les conditions d'erreur non spécifiées dans ce document, le serveur PEUT simplement choisir un état numérique approprié et laisser le corps de la réponse vide. Cependant, un serveur PEUT plutôt utiliser un code de condition personnalisé et d'autres textes de support, car même lorsque les clients ne reconnaissent pas automatiquement les codes de condition, ils peuvent être très utiles dans les tests d'interopérabilité et le débogage.

Exemple - Réponse avec code de précondition:

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>

Dans cet exemple, un client ignorant un verrou de profondeur infinie sur la collection parente "/workspace/webdav/" a tenté de modifier le membre de la collection "/workspace/webdav/proposal.doc".

D'autres préconditions et postconditions utiles ont été définies dans d'autres spécifications étendant WebDAV, telles que [RFC3744] (voir en particulier la section 7.1.1), [RFC3253] et [RFC3648].

Tous ces éléments sont dans l'espace de noms "DAV:". Sauf indication contraire, le contenu de l'élément XML de chaque condition est défini comme étant vide.

lock-token-matches-request-uri

Nom (Name): lock-token-matches-request-uri

Utiliser avec (Use with): 409 Conflict

Objectif (Purpose): (précondition) -- Une requête peut inclure un en-tête Lock-Token pour identifier un verrou pour la méthode UNLOCK. Cependant, si le Request-URI ne tombe pas dans la portée du verrou identifié par le jeton, le serveur DEVRAIT utiliser cette erreur. Le verrou peut avoir une portée qui n'inclut pas le Request-URI, ou le verrou peut avoir disparu, ou le jeton peut être invalide.

lock-token-submitted

Nom (Name): lock-token-submitted (précondition)

Utiliser avec (Use with): 423 Locked

Objectif (Purpose): La requête n'a pas pu réussir car un jeton de verrou aurait dû être soumis. Cet élément, s'il est présent, DOIT contenir au moins une URL d'une ressource verrouillée qui a empêché la requête. Dans les cas de MOVE, COPY et DELETE où des verrous de collection sont impliqués, il peut être difficile pour le client de découvrir quelle ressource verrouillée a fait échouer la requête -- mais le serveur est seulement responsable de retourner une telle ressource verrouillée. Le serveur PEUT retourner toutes les ressources verrouillées qui ont empêché la requête de réussir s'il les connaît toutes.

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

no-conflicting-lock

Nom (Name): no-conflicting-lock (précondition)

Utiliser avec (Use with): Généralement 423 Locked

Objectif (Purpose): Une requête LOCK a échoué en raison de la présence d'un verrou conflictuel déjà existant. Notez qu'un verrou peut être en conflit bien que la ressource vers laquelle la requête a été dirigée ne soit que indirectement verrouillée. Dans ce cas, le code de précondition peut être utilisé pour informer le client de la ressource qui est la racine du verrou conflictuel, évitant une recherche séparée de la propriété "lockdiscovery".

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

no-external-entities

Nom (Name): no-external-entities

Utiliser avec (Use with): 403 Forbidden

Objectif (Purpose): (précondition) -- Si le serveur rejette une requête client parce que le corps de la requête contient une entité externe, le serveur DEVRAIT utiliser cette erreur.

preserved-live-properties

Nom (Name): preserved-live-properties

Utiliser avec (Use with): 409 Conflict

Objectif (Purpose): (postcondition) -- Le serveur a reçu une requête MOVE ou COPY par ailleurs valide, mais ne peut pas maintenir les propriétés dynamiques avec le même comportement à la destination. Il se peut que le serveur ne prenne en charge certaines propriétés dynamiques que dans certaines parties du référentiel, ou qu'il ait simplement une erreur interne.

propfind-finite-depth

Nom (Name): propfind-finite-depth

Utiliser avec (Use with): 403 Forbidden

Objectif (Purpose): (précondition) -- Ce serveur n'autorise pas les requêtes PROPFIND de profondeur infinie sur les collections.

cannot-modify-protected-property

Nom (Name): cannot-modify-protected-property

Utiliser avec (Use with): 403 Forbidden

Objectif (Purpose): (précondition) -- Le client a tenté de définir une propriété protégée dans un PROPPATCH (comme DAV:getetag). Voir également [RFC3253], Section 3.12.