ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

matlab.net.http.io.ContentProvider クラス

パッケージ: matlab.net.http.io
スーパークラス: handle, matlab.mixin.Heterogeneous

HTTP メッセージ ペイロードの ContentProvider

説明

ContentProvider は、メッセージの送信中に HTTP RequestMessage のデータを提供します。簡単なものとしては、データを MATLAB® 型からバイト ストリームに変換するプロバイダーがあります。より複雑なプロバイダーでは、データをサーバーにストリーミングできます。この場合、データの取得や生成を送信と同時に行えるため、メッセージの開始前にすべてのデータをメモリに読み込む必要がありません。

通常、データを Web サービスに送信するときは (PUT 要求または POST 要求が一般的)、RequestMessage を作成し、データを MessageBody オブジェクトの形式で RequestMessage.Body プロパティに挿入します。そのメッセージを RequestMessage.send を使用して送信すると、そのデータがサーバーに送信するバイト ストリームに変換されます。この変換は、メッセージの Content-Type と Body.Data のデータのタイプに基づいて MATLAB で行われます。この変換ルールについては、MessageBody.Data を参照してください。

MessageBody オブジェクトを RequestMessage.Body プロパティに挿入する代わりに、ContentProvider オブジェクトを作成して挿入することができます。この場合、メッセージを送信すると、MATLAB で ContentProvider のメソッドが呼び出され、送信するデータのバッファーがメッセージの送信中に取得されます。

メッセージに MessageBody または ContentProvider のどちらを挿入した場合も、RequestMessage.send の呼び出しはメッセージ全体が送信されて応答を受信するか、エラーが発生するまで戻りません (ブロックされます)。ただし、ContentProvider の場合は、送信がブロックされている間、送信するデータのバッファーを取得するためのプロバイダーに対するコールバックが MATLAB で定期的に実行されます。ContentProvider では、これらのコールバックで、ファイル、MATLAB 配列、ハードウェア センサー、MATLAB 関数などの任意のソースからデータを取得できます。プロバイダーの役割は、そのデータを Web に送信できるバイト ストリーム (uint8 形式のバッファー) に変換することです。

ContentProvider は、クラスの作成者が独自のデータ ジェネレーターやデータ コンバーターを使用してサブクラス化できるように設計された抽象クラスです。また、MATLAB プロバイダーのいずれかを使用 (またはサブクラス化) すれば、サブクラスを記述せずにさまざまなデータを生成させることができます。これらのプロバイダーには、データを MessageBody に直接挿入する場合に実行される自動変換に比べて、データの取得方法や変換方法をより柔軟に制御できるオプションがあります。ContentProvider のサブクラスのいずれかを使用します。

データをストリーミングする必要がない場合でも、これらのプロバイダーのいずれかを使用すると、データが内部形式から uint8 ストリームに変換されるため、特定のタイプの内容を送信する処理が簡単になります。たとえば、FormProvider を使用すれば、フォームの応答をサーバーに送信し、データを QueryParameter オブジェクトの配列として表現できるので便利です。MultipartFormProvider を使用すると、マルチパート フォームの応答を送信できるため、マルチパート フォームの応答の作成が簡単になります。ContentProvider を使用する場合は、サーバーへの送信が想定される内容のタイプを理解しておく必要があります。

matlab.net.http.io.ContentProvider クラスは handle クラスです。

サブクラスの作成

簡単な ContentProvider であれば、MATLAB から要求されたときにデータのバッファーを提供する getData メソッドを実装するだけで作成できます。プロバイダーを使用するには、RequestMessageBody プロパティに挿入します。この例では、RequestMessage コンストラクターの 3 番目の引数で MyProvider オブジェクトを Body に挿入しています。

provider = MyProvider;
req = matlab.net.http.RequestMessage('put', headers, provider);
resp = req.send(uri);

次に、コンストラクターに引数として名前が渡されたファイルを読み取って Web に送信する MyProvider クラスの例を示します。この例では、処理が終了するかこのプロバイダーが削除されたときにファイルを閉じます。

    classdef MyProvider < matlab.net.http.io.ContentProvider
        properties
            FileID double
        end
 
        methods
            function obj = MyProvider(name)
                obj.FileID = fopen(name);
            end
 
            function [data, stop] = getData(obj, length)
                [data, len] = fread(obj.FileID, length, '*uint8');
                stop = len < length;
                if (stop)
                    fclose(obj.FileID);
                    obj.FileID = [];
                end
            end
 
            function delete(obj)
                if ~isempty(obj.FileID)
                    fclose(obj.FileID);
                    obj.FileID = [];
                end
            end
        end
    end

MATLAB は、送信する新しいメッセージの作成中にプロバイダーの complete メソッドを呼び出します。これは、プロバイダーでの新しいメッセージの準備として、必要なヘッダー フィールドをメッセージに追加できるようにするためです。MATLAB は、データの送信時になると、getData の最初の呼び出しの前にプロバイダーの start メソッドを呼び出します。

プロパティ

すべて展開する

パブリック プロパティ

メッセージまたはパートのヘッダー フィールド。1 つ以上の matlab.net.http.HeaderField オブジェクトのベクトルとして指定されます。

このプロパティはサブクラスの作成にのみ使用されます。このプロパティは、プロバイダーの complete を呼び出す前に MATLAB で設定されます。マルチパート メッセージ以外については、このプロパティは、MATLAB によって matlab.net.http.field.GenericFields や値が空のフィールドを除いた Request.Header の内容に初期化されます。ContentProvider では、送信するデータを示すヘッダー フィールドを追加したり、メッセージの既存のヘッダー フィールドにパラメーターを追加したりする場合にこのプロパティを使用します。MultipartProvider のデリゲートでは、このプロパティは、MATLAB によってデリゲート元のプロバイダーが挿入するパート用のヘッダー フィールドに初期化されます。これらのフィールドはデリゲートで変更が可能です。

マルチパート メッセージ以外では、プロバイダーの complete メソッドから戻ると、MATLAB はこのプロパティを読み取って、その内容を Request のヘッダーにマージします。この Header に含まれるフィールドの NamesRequest.Header にない場合、Request.Header の末尾に追加されます。この Header に含まれるフィールドの NameRequest.Header に含まれるフィールドと同じで、どちらの Values も空でない場合は、次のように処理されます。

  • Request.Header のフィールドが GenericField の場合、Header のフィールドは無視されます。

  • Request.Header のフィールドが GenericField でない場合、Header のフィールドに置き換えられます。

これらの一方または両方の Value が空の場合は、Request.Header からフィールドが削除され、メッセージの正常な終了時にも追加されません。

MultipartProvider のデリゲートの場合は、この Header の内容全体がパートのヘッダーとして使用されます。マルチパート デリゲートでは、Request.Header にその Header に付随する任意のフィールドが含まれていると想定してはなりません。プロバイダーがマルチパート デリゲートであるかどうかは MyDelegatorMultipartProvider かどうかを確認すれば特定できますが、このテストが必要になることはほとんどありません。

このプロパティが MATLAB で読み取られるのは、プロバイダーの complete メソッドの呼び出しから戻るときだけです。MATLAB で start が呼び出された後は、この配列に対する変更は無視されます。

クラスを作成するときは、スーパークラスで complete を呼び出す前に、この (complete メソッド内の) Headerにサブクラスがフィールドを追加済みの場合があることを認識しておく必要があります。それらのフィールドは残しておいて、同じ名前のフィールドを追加しないようにすることを推奨します。ただし、フィールドへのパラメーターの追加は可能です。たとえば、既存の Content-Type フィールドに charset パラメーターがない場合、スーパークラスで追加できます。

属性:

GetAccess
public
SetAccess
public

チャンク転送コーディングを強制するかどうかを示します。boolean として指定されます。これはサブクラスの作成にのみ関係するプロパティで、マルチパート デリゲート以外のプロバイダーにのみ該当します。サブクラスでは、ForceChunked を設定することで、内容の送信にチャンク転送コーディングを使用するかどうかを制御します。false (既定) の場合、MATLAB は、メッセージの送信準備ができた時点で内容の長さがわかっているかどうかに基づいて、内容をチャンク化して送信するかどうかを決定します。

  • MATLAB で内容の長さがわかっている場合 (メッセージに Content-Length フィールドがあるか、このプロバイダーの expectedContentLength メソッドから数値が返された場合)、チャンク化して送信するかどうかを MATLAB で決定します。

  • MATLAB で内容の長さがわからない場合 (ヘッダーに Content-Length フィールドがないか、expectedContentLength の戻り値が空の場合)、MATLAB はメッセージを常にチャンク化して送信します。

ForceChunkedtrue の場合、内容の長さがわかっているかどうかに関係なく、既知の長さがチャンク サイズに満たない場合を除き、MATLAB はメッセージをチャンク化して送信します。このプロパティが true の場合は、メッセージに Content-Length フィールドを含めてはなりません。HTTP ではチャンクされたメッセージに Content-Length フィールドを含めることが許可されないためです。ただし、想定されるデータの長さを返しているかを MATLAB で検証する場合は、expectedContentLength メソッドで非ゼロの値を返すことができます。

MATLAB でメッセージをチャンク化して送信する場合、各チャンクのサイズは getData で返されたデータの長さと等しくなります。

MATLAB は、complete メソッドを呼び出してから start を呼び出すまでの間にこの値を読み取ります。このフィールドの設定は行いません。

属性:

GetAccess
public
SetAccess
public

送信する要求メッセージ。matlab.net.http.RequestMessage オブジェクトとして指定されます。

このプロパティはサブクラスの作成にのみ使用されます。このプロパティは、このプロバイダーで他のメソッドを呼び出す前であり、かつヘッダー フィールドを追加したりメッセージを検証したりする前に、このプロバイダーが Body に配置された RequestMessageRequestMessage.send メソッドと RequestMessage.complete メソッドで設定されます。プロバイダーは、このメッセージを調べて元の要求の内容を確認できます。

デリゲートの場合、このプロパティの値はデリゲーターと同じになります。ContentProvider がデリゲートである場合は、必ずしも要求メッセージの本文全体を提供するわけではないため、この Request のヘッダー フィールドがそのプロバイダーで提供するデータに関連するものであるとは限らないことに注意が必要です。通常、デリゲートでは、この要求のデータ関連のヘッダー フィールド (Content-Type など) は無視します。

このメッセージへのヘッダー フィールドの追加や既存のヘッダー フィールドの変更をプロバイダーで行う場合は、complete メソッドで Header プロパティにそれらのフィールドを追加します。それらのフィールドに対する処理は、complete の呼び出し元 (RequestMessage またはデリゲート元のプロバイダー) で決定されます。RequestMessage.sendRequestMessage.complete は、それらのフィールドを RequestMessageHeader に常にコピーします。デリゲート元のプロバイダーでは、フィールドをそれぞれの Header プロパティにコピーしたりメッセージに挿入したりできます (MultipartProvider の場合と同様)。詳細については、Header プロパティを参照してください。

このプロパティは読み取り専用です。

属性:

GetAccesspublic
SetAccessmatlab.net.http.RequestMessage

保護プロパティ

このプロバイダーのデリゲート先の ContentProvidermatlab.net.http.io.ContentProvider オブジェクトとして指定されます。このプロパティは、現在のデリゲート先のプロバイダーを示すために呼び出し元のプロバイダー (デリゲーター) の delegateTo メソッドで設定されます。現在のデリゲーションがない場合、値は空です。

このプロパティは complete メソッドで空に設定されます。

属性:

GetAccess
protected
SetAccess
protected

このプロバイダーのデリゲート元の ContentProvidermatlab.net.http.io.ContentProvider オブジェクトとして指定されます。

このプロパティは、ContentProvider から別のプロバイダーにメッセージのすべてまたは一部のデータの送信がデリゲートされている場合に、デリゲート元のプロバイダーを示します。たとえば、MultipartProvider はメッセージのパートを他のプロバイダーにデリゲートするため、各デリゲートに自身のハンドルを挿入します。それ以外の場合、MyDelegator は空です。このプロパティは、デリゲートの delegateTo メソッドで設定されます。

属性:

GetAccess
protected
SetAccess
protected

メソッド

すべて展開する

詳細

すべて展開する

R2018a で導入