16. Precondition/Postcondition XML Elements (事前/事後条件 XML 要素)

セクション 8.7 で紹介されたように, エラー条件に関する追加情報は, 多くのステータス応答のボディに含めることができます。このセクションでは, エラーボディメカニズムの使用に関する要件を設定し, 多数の事前条件および事後条件コードを導入します。

メソッドの "事前条件 (precondition)" は, そのメソッドを実行するために真でなければならないサーバーの状態を記述します。メソッドの "事後条件 (postcondition)" は, そのメソッドが完了した後に真でなければならないサーバーの状態を記述します。

各事前条件および事後条件には, それに関連付けられた一意の XML 要素があります。207 Multi-Status 応答では, XML 要素は, 条件が 1 つ以上のプロパティに適用されるか, リソース全体に適用されるかに応じて, 適切な 'propstat または 'response' 要素内の 'error' 要素内に表示されなければなりません。この仕様の 'error' ボディが使用される他のすべてのエラー応答では, リクエストによって別途ネゴシエートされない限り, 事前条件/事後条件 XML 要素は, 適切な応答ステータスとともに, 応答ボディ内のトップレベルの 'error' 要素の子として返されなければなりません。最も一般的な応答ステータスコードは, リクエストが常に失敗するため繰り返すべきでない場合は 403 (Forbidden), ユーザーが競合を解決してリクエストを再送信できると予想される場合は 409 (Conflict) です。'error' 要素は特定のエラー情報を含む子要素を含むことができ, 任意のカスタム子要素で拡張できます。

このメカニズムは, ここまたは HTTP で定義されている正しい数値ステータスコードを使用することに代わるものではありません。クライアントは常に数値コードのみに基づいて妥当な行動方針を取ることができなければならないからです。ただし, 新しい数値コードを定義する必要はなくなります。この目的で使用される新しい機械可読コードは, 事前条件および事後条件として分類される XML 要素であるため, 当然, 新しい条件コードを定義するグループは独自の名前空間を使用できます。いつものように, "DAV:" 名前空間は IETF 認可の WebDAV ワーキンググループによる使用のために予約されています。

この仕様をサポートするサーバーは, このドキュメントで定義されている事前条件または事後条件が違反されるたびに XML エラーを使用すべきです。このドキュメントで指定されていないエラー条件の場合, サーバーは適切な数値ステータスを選択し, 応答ボディを空白のままにすることができます。ただし, クライアントが条件コードを自動的に認識しない場合でも, 相互運用性テストやデバッグに非常に役立つため, サーバーは代わりにカスタム条件コードやその他のサポートテキストを使用できます。

例 - 事前条件コード付き応答:

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>

この例では, 親コレクション "/workspace/webdav/" の深さ無限ロックを認識していないクライアントが, コレクションメンバー "/workspace/webdav/proposal.doc" を変更しようとしました。

その他の有用な事前条件および事後条件は, [RFC3744] (特にセクション 7.1.1 を参照), [RFC3253], および [RFC3648] など, WebDAV を拡張する他の仕様で定義されています。

これらのすべての要素は "DAV:" 名前空間にあります。特に指定されていない限り, 各条件の XML 要素の内容は空と定義されています。

lock-token-matches-request-uri

名前 (Name): lock-token-matches-request-uri

使用 (Use with): 409 Conflict

目的 (Purpose): (事前条件) -- リクエストには, UNLOCK メソッドのロックを識別するための Lock-Token ヘッダーが含まれる場合があります。ただし, Request-URI がトークンによって識別されるロックのスコープ内にない場合, サーバーはこのエラーを使用すべきです。ロックに Request-URI を含まないスコープがある場合, ロックが消失した場合, またはトークンが無効な場合があります。

lock-token-submitted

名前 (Name): lock-token-submitted (事前条件)

使用 (Use with): 423 Locked

目的 (Purpose): ロックトークンを送信する必要があったため, リクエストは成功しませんでした。この要素が存在する場合, リクエストを妨げたロックされたリソースの URL を少なくとも 1 つ含まなければなりません。コレクションロックが関与する MOVE, COPY, および DELETE の場合, どのロックされたリソースがリクエストを失敗させたかをクライアントが見つけるのは困難な場合がありますが, サーバーはそのようなロックされたリソースを 1 つだけ返す責任があります。サーバーがすべてを知っている場合, リクエストの成功を妨げたすべてのロックされたリソースを返すことができます。

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

no-conflicting-lock

名前 (Name): no-conflicting-lock (事前条件)

使用 (Use with): 通常 423 Locked

目的 (Purpose): すでに存在する競合するロックの存在により, LOCK リクエストが失敗しました。リクエストが向けられたリソースが間接的にのみロックされている場合でも, ロックは競合する可能性があることに注意してください。この場合, 事前条件コードを使用して, "lockdiscovery" プロパティの個別のルックアップを回避し, 競合するロックのルートであるリソースについてクライアントに通知できます。

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

no-external-entities

名前 (Name): no-external-entities

使用 (Use with): 403 Forbidden

目的 (Purpose): (事前条件) -- リクエストボディに外部エンティティが含まれているためにサーバーがクライアントリクエストを拒否する場合, サーバーはこのエラーを使用すべきです。

preserved-live-properties

名前 (Name): preserved-live-properties

使用 (Use with): 409 Conflict

目的 (Purpose): (事後条件) -- サーバーは他の点では有効な MOVE または COPY リクエストを受信しましたが, 宛先で同じ動作を持つライブプロパティを維持できません。サーバーがリポジトリの一部のパートでのみ一部のライブプロパティをサポートしている場合, または単に内部エラーがある場合があります。

propfind-finite-depth

名前 (Name): propfind-finite-depth

使用 (Use with): 403 Forbidden

目的 (Purpose): (事前条件) -- このサーバーは, コレクションに対する無限深度の PROPFIND リクエストを許可しません。

cannot-modify-protected-property

名前 (Name): cannot-modify-protected-property

使用 (Use with): 403 Forbidden

目的 (Purpose): (事前条件) -- クライアントは PROPPATCH で保護されたプロパティ (DAV:getetag など) を設定しようとしました。[RFC3253] のセクション 3.12 も参照してください。