expectedContentLength

クラス: matlab.net.http.io.ContentProvider
名前空間: matlab.net.http.io

ContentProvider の内容の長さ

構文

length = expectedContentLength(provider) length = expectedContentLength(provider,force)

説明

length = expectedContentLength(provider) は、想定される内容の長さ (バイト数) を返します。このメソッドは、内容の長さを MATLAB^® にレポートするサブクラスでオーバーライドして使用します。RequestMessage.send および RequestMessage.complete でこのメソッドを呼び出し、戻り値を使用して RequestMessage の Content-Length ヘッダーフィールドを設定します。メッセージに値が設定された Content-Length フィールドが既にあり、length が空でない場合は、その Content-Length フィールドの値と等しくなければなりません。length は内容が含まれていなければ 0 になります。その場合は、getData の最初の呼び出しで空の data と stop=true を返します。

MATLAB は、このメソッドを RequestMessage.send、RequestMessage.complete、および delegateTo のデリゲートで呼び出します。この MATLAB による呼び出しは、ContentProvider.complete の後、ContentProvider.start よりも前に行われます。このメソッドが complete よりも前に呼び出された場合、プロバイダーでは変換を制御するすべてのヘッダーフィールドを確認しないと変換後のデータの長さを特定できないことがあるため、無効な戻り値が返される可能性があります。

メッセージに Content-Length ヘッダーフィールドを含めない場合 (メッセージの送信にチャンク転送コーディングを使用する場合)、このメソッドをオーバーライドして空でない値を返す唯一の理由は、想定される長さのデータをプロバイダーが返す、ということをダブルチェックして確実にするためです。

データの長さがわかっている場合 (このメソッドが数値を返すか Content-Length フィールドが空でない場合)、このプロバイダーの getData メソッドは、そのバイト数が返された時点で stop=true を返さなければなりません。MATLAB は、length=0 の場合も、常に getData が stop=true を返すまで繰り返し getData を呼び出します。長さが不明な場合、最上位のプロバイダーであれば (マルチパートデリゲートでなければ)、MATLAB でチャンク転送コーディングを使用して内容が送信され、プロバイダーは stop=true を設定するまでの間に任意の長さのデータ (データなしも含む) を自由に返すことができます。

データの長さが事前にわからない場合やデータの長さの計算に時間がかかりそうな場合は [] を返すようにします。チャンク転送コーディングの使用は、データの長さがわかっている場合でも、すべてのメッセージで許可してまったく問題ありません。このプロバイダーがマルチパートデリゲートの場合、空でない戻り値は、もし getData で返されるバイト数が多かったり少なかったりするなら強制的にエラーとして処理する、という目的でのみ使用されます。これによって Content-Length ヘッダーフィールドがパートに表示されることはありません。詳細については、MultipartProvider を参照してください。

length = expectedContentLength(provider,force) は、force が true であるなら、そうでなければ [] を返す場合でも、長さの計算が不可能でない限りはデータの長さを (必要であれば計算して) 返すように要求します。この数値を返すためにメッセージのすべてのデータの計算や生成に時間がかかる場合は、後続の getData の呼び出しで再計算しなくても済むようにデータをキャッシュしておきます。force 引数は、データの長さを事前に確認する必要があるサブクラスで使用するために用意されています。MATLAB によるこのメソッドの呼び出し時にこのオプションが設定されることはなく、このオプションを設定する可能性があるサブクラスとして使用されないことがわかっていれば、そのプロバイダーでは force 引数を無視してかまいません。

このメソッドの呼び出し元では、force を true に設定して [] が返された場合、エラーとして処理できるほか、長さが不明な内容に対応した方法で対処することもできます。

force を指定すると、length を計算するためにすべてのデータを生成する必要がある場合に、データの生成と送信を同時に行うストリーミングの利点を損なう場合があります。そのため、このオプションは、デバッグや、データの長さが短いことをあらかじめ把握しているような、特別なケースに最も適しています。

force を使用する例として、他のプロバイダーの出力を必要に応じて圧縮する仮想の CompressProvider があります。メッセージが短い場合の圧縮は非効率なため、出力が一定の長さを超える場合にのみ圧縮します。CompressProvider では、長さを特定するために、他のプロバイダーの expectedContentLength を force を true に設定して呼び出す必要があります。他のプロバイダーがストリーミング JSONProvider の場合、JSON 文字列の長さを特定するにはすべての入力データを処理する必要があるため、expectedContentLength では通常は [] を返します。force を true に設定した場合は、JSONProvider の expectedContentLength メソッドですべてのデータが処理され (多くの場合は後で putData メソッドで使用できるように出力文字列が内部にキャッシュされます)、その文字列の長さが返されます。

入力引数

すべて展開する

`provider` — コンテンツプロバイダー
`matlab.net.http.io.ContentProvider`

コンテンツプロバイダー。matlab.net.http.io.ContentProvider オブジェクトとして指定します。

`force` — データの長さを返すかどうか
`false` (既定値) | `true`

データの長さを返すかどうか。true または false として指定します。

true の場合、expectedContentLength はデータの長さを必要に応じて計算して返さなければなりません。これには、通常であれば [] を返すような状況でも、長さの計算が不可能でない限り従う必要があります。この数値を返すためにメッセージのすべてのデータの計算や生成に時間がかかる場合は、後続の getData の呼び出しで再計算しなくても済むようにデータをキャッシュしておきます。force 引数は、データの長さを事前に確認する必要があるサブクラスで使用するために用意されています。MATLAB によるこのメソッドの呼び出し時にこのオプションが設定されることはなく、このオプションを設定する可能性があるサブクラスとして使用されないことがわかっていれば、そのプロバイダーでは force 引数を無視してかまいません。

force を指定すると、length を計算するためにすべてのデータを生成する必要がある場合に、データを生成と同時に送信するストリーミングの利点が失われることがあります。そのため、このオプションは、デバッグなどの特別な場合やデータの長さが小さいことがわかっている場合に適しています。

出力引数

すべて展開する

`length` — 想定される内容の長さ
`[]` (既定値) | バイト

想定される内容の長さ (バイト数)。このメソッドをオーバーライドしない場合、expectedContentLength は [] を返します。MATLAB では、次のようにして内容の長さを判定します。

この ContentProvider がマルチパートデリゲート (MultipartProvider を参照) でない場合、メッセージに値が空でない Content-Length フィールドがあれば (元の RequestMessage で挿入されるか complete メソッドで Header プロパティに追加)、その Content-Length フィールドが内容の長さになります。
Content-Length フィールドがない場合 (またはこのプロバイダーがマルチパートデリゲートの場合)、このプロバイダーの getData メソッドで stop 戻り値を設定した時点でペイロード (またはパートのデータ) が終了します。この場合、内容の長さを指定する必要はありません。

属性

Access protected

バージョン履歴

R2018a で導入

参考