16. Precondition/Postcondition XML Elements (Elementi XML di precondizione/postcondizione)

Come introdotto nella Sezione 8.7, informazioni aggiuntive sulle condizioni di errore possono essere incluse nel corpo di molte risposte di stato. Questa sezione formula requisiti sull'uso del meccanismo del corpo di errore e introduce un numero di codici di precondizione e postcondizione.

Una "precondizione" di un metodo descrive lo stato del server che deve essere vero affinché quel metodo possa essere eseguito. Una "postcondizione" di un metodo descrive lo stato del server che deve essere vero dopo che quel metodo è stato completato.

Ogni precondizione e postcondizione ha un elemento XML unico associato ad essa. In una risposta 207 Multi-Status, l'elemento XML DEVE apparire all'interno di un elemento 'error' nell'elemento 'propstat o 'response' appropriato a seconda che la condizione si applichi a una o più proprietà o alla risorsa nel suo complesso. In tutte le altre risposte di errore in cui viene utilizzato il corpo 'error' di questa specifica, l'elemento XML di precondizione/postcondizione DEVE essere restituito come figlio di un elemento 'error' di livello superiore nel corpo della risposta, salvo diversa negoziazione da parte della richiesta, insieme a uno stato di risposta appropriato. I codici di stato di risposta più comuni sono 403 (Forbidden) se la richiesta non deve essere ripetuta perché fallirà sempre, e 409 (Conflict) se si prevede che l'utente possa essere in grado di risolvere il conflitto e ripresentare la richiesta. L'elemento 'error' PUÒ contenere elementi figlio con informazioni di errore specifiche e PUÒ essere esteso con qualsiasi elemento figlio personalizzato.

Questo meccanismo non sostituisce l'uso di un codice di stato numerico corretto come definito qui o in HTTP, perché il client deve sempre essere in grado di intraprendere una linea d'azione ragionevole basata solo sul codice numerico. Tuttavia, elimina la necessità di definire nuovi codici numerici. I nuovi codici leggibili dalla macchina utilizzati per questo scopo sono elementi XML classificati come precondizioni e postcondizioni, quindi naturalmente qualsiasi gruppo che definisce un nuovo codice di condizione può utilizzare il proprio namespace. Come sempre, il namespace "DAV:" è riservato all'uso da parte dei gruppi di lavoro WebDAV autorizzati dall'IETF.

Un server che supporta questa specifica DOVREBBE utilizzare l'errore XML ogni volta che viene violata una precondizione o postcondizione definita in questo documento. Per condizioni di errore non specificate in questo documento, il server PUÒ semplicemente scegliere uno stato numerico appropriato e lasciare vuoto il corpo della risposta. Tuttavia, un server PUÒ invece utilizzare un codice di condizione personalizzato e altro testo di supporto, perché anche quando i client non riconoscono automaticamente i codici di condizione, possono essere molto utili nei test di interoperabilità e nel debug.

Esempio - Risposta con codice di precondizione:

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 questo esempio, un client inconsapevole di un blocco di profondità infinita sulla collezione padre "/workspace/webdav/" ha tentato di modificare il membro della collezione "/workspace/webdav/proposal.doc".

Altre precondizioni e postcondizioni utili sono state definite in altre specifiche che estendono WebDAV, come [RFC3744] (vedere in particolare la Sezione 7.1.1), [RFC3253] e [RFC3648].

Tutti questi elementi sono nello spazio dei nomi "DAV:". Se non specificato diversamente, il contenuto dell'elemento XML di ciascuna condizione è definito come vuoto.

lock-token-matches-request-uri

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

Utilizzare con (Use with): 409 Conflict

Scopo (Purpose): (precondizione) -- Una richiesta può includere un'intestazione Lock-Token per identificare un blocco per il metodo UNLOCK. Tuttavia, se il Request-URI non rientra nell'ambito del blocco identificato dal token, il server DOVREBBE utilizzare questo errore. Il blocco può avere un ambito che non include il Request-URI, o il blocco potrebbe essere scomparso, o il token potrebbe essere non valido.

lock-token-submitted

Nome (Name): lock-token-submitted (precondizione)

Utilizzare con (Use with): 423 Locked

Scopo (Purpose): La richiesta non ha potuto avere successo perché avrebbe dovuto essere inviato un token di blocco. Questo elemento, se presente, DEVE contenere almeno un URL di una risorsa bloccata che ha impedito la richiesta. Nei casi di MOVE, COPY e DELETE in cui sono coinvolti blocchi di collezione, può essere difficile per il client scoprire quale risorsa bloccata ha fatto fallire la richiesta -- ma il server è responsabile solo di restituire una tale risorsa bloccata. Il server PUÒ restituire ogni risorsa bloccata che ha impedito il successo della richiesta se le conosce tutte.

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

no-conflicting-lock

Nome (Name): no-conflicting-lock (precondizione)

Utilizzare con (Use with): Tipicamente 423 Locked

Scopo (Purpose): Una richiesta LOCK è fallita a causa della presenza di un blocco conflittuale già esistente. Si noti che un blocco può essere in conflitto anche se la risorsa a cui è stata diretta la richiesta è solo indirettamente bloccata. In questo caso, il codice di precondizione può essere utilizzato per informare il client sulla risorsa che è la radice del blocco conflittuale, evitando una ricerca separata della proprietà "lockdiscovery".

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

no-external-entities

Nome (Name): no-external-entities

Utilizzare con (Use with): 403 Forbidden

Scopo (Purpose): (precondizione) -- Se il server rifiuta una richiesta del client perché il corpo della richiesta contiene un'entità esterna, il server DOVREBBE utilizzare questo errore.

preserved-live-properties

Nome (Name): preserved-live-properties

Utilizzare con (Use with): 409 Conflict

Scopo (Purpose): (postcondizione) -- Il server ha ricevuto una richiesta MOVE o COPY altrimenti valida, ma non può mantenere le proprietà live con lo stesso comportamento alla destinazione. Potrebbe essere che il server supporti solo alcune proprietà live in alcune parti del repository, o semplicemente abbia un errore interno.

propfind-finite-depth

Nome (Name): propfind-finite-depth

Utilizzare con (Use with): 403 Forbidden

Scopo (Purpose): (precondizione) -- Questo server non consente richieste PROPFIND di profondità infinita sulle collezioni.

cannot-modify-protected-property

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

Utilizzare con (Use with): 403 Forbidden

Scopo (Purpose): (precondizione) -- Il client ha tentato di impostare una proprietà protetta in un PROPPATCH (come DAV:getetag). Vedere anche [RFC3253], Sezione 3.12.