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 サブクラスを使用します。

• FileProvider

• StringProvider

• JSONProvider

• ImageProvider

• FormProvider

• MultipartProvider

• MultipartFormProvider

• GenericProvider

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

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

サブクラスの作成

簡単な ContentProvider であれば、MATLAB から要求されたときにデータのバッファーを提供する getData メソッドを実装するだけで作成できます。プロバイダーを使用するには、RequestMessage の Body プロパティに挿入します。この例では、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 メソッドを呼び出します。

プロパティ

パブリック プロパティ

Header — メッセージまたはパートのヘッダー フィールド

matlab.net.http.HeaderField.empty (既定値) | matlab.net.http.HeaderField

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

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

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

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

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

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

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

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

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

属性:

GetAccess	public
SetAccess	public

ForceChunked — チャンク転送コーディングを強制するかどうかを示す

false (既定値) | true

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

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

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

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

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

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

属性:

GetAccess	public
SetAccess	public

Request — 送信する要求メッセージ

matlab.net.http.RequestMessage

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

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

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

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

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

属性:

GetAccess	public
SetAccess	matlab.net.http.RequestMessage

保護プロパティ

CurrentDelegate — このプロバイダーのデリゲート先の ContentProvider

matlab.net.http.io.ContentProvider | 空

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

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

属性:

GetAccess	protected
SetAccess	protected

MyDelegator — このプロバイダーのデリゲート元の ContentProvider

matlab.net.http.io.ContentProvider.empty (既定値) | matlab.net.http.io.ContentProvider

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

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

属性:

GetAccess	protected
SetAccess	protected

メソッド

パブリック メソッド

string	ContentProvider を string として表示する
show	ContentProvider の情報を表示する

保護されたメソッド

complete	ContentProvider の完全な HTTP ヘッダー
preferredBufferSize	ContentProvider の推奨されるバッファー サイズ
expectedContentLength	ContentProvider の内容の長さ
start	ContentProvider からのデータ転送を開始する
restartable	ContentProvider が再起動可能かどうか
reusable	ContentProvider が再利用可能かどうか
delegateTo	別のプロバイダーにデリゲートする

抽象メソッド

getData

ContentProvider から HTTP 要求メッセージで送信するデータの次のバッファー

詳細

再起動可能性と再利用可能性

プロバイダーには再起動可能なものや再利用可能なものがあります。再起動可能とは、MATLAB で start が呼び出されるたびに、前回の処理が正常に完了していない場合でも、プロバイダーから同じメッセージを同じデータ ストリームで繰り返し再送信できることを意味します。この動作が必要なのは、サーバーから別のサーバーへのメッセージのリダイレクトが可能なため、その際にデータを再送信する必要があるからです。その場合、MATLAB は complete を再度呼び出さずに start を呼び出します。プロバイダーが再起動可能かどうかを判定するために、MATLAB は restartable メソッドを呼び出します。false の場合に、既に開始されているプロバイダーで start を呼び出す必要があり、complete への割り込み呼び出し (新しいメッセージでのみ発生) がなければ、MATLAB は例外をスローします。

再利用可能とは、MATLAB で complete メソッドが呼び出されるたびに、別の (または同じ) メッセージにプロバイダーを再利用できることを意味します。プロバイダーが再利用可能かどうかを判定するために、MATLAB は reusable メソッドを呼び出します。false が返され、既に開始されているプロバイダーで complete を呼び出す必要がある場合、MATLAB は例外をスローします。プロバイダーが再利用可能な場合は、プロバイダーが再起動可能であっても、次の start の呼び出しが成功すると仮定されます。

ContentProvider は restartable と reusable の両方に対して false を返すため、この基底クラスを再起動可能または再利用可能なプロバイダーで直接拡張する場合は、それらの一方または両方のメソッドを true を返すようにオーバーライドします。matlab.net.http.io 名前空間の ContentProvider の具象サブクラスは、いずれも再起動と再利用の両方が可能であるため、それらのメソッドに対して true を返します。それらのサブクラスのいずれかを再利用可能または再起動可能でないプロバイダーで拡張する場合は、それらの一方または両方のメソッドを false を返すようにオーバーライドします。

この例の MyProvider クラスは、メッセージの最後にプロバイダーでファイルを閉じているため、再起動可能でも再利用可能でもありません。再利用可能にするには、コンストラクターではなく complete メソッドで fopen を呼び出して、プロバイダーの状態をメッセージに使用する前の状態に戻します。

     classdef MyProvider < matlab.net.http.io.ContentProvider
        properties
            FileID double
            Name string
        end
 
        methods
            function obj = MyProvider(name)
                obj.Name = name;
            end
 
            function [data, stop] = getData(obj, length)
                ...as above...
            end
 
            function complete(obj, uri)
                obj.FileID = fopen(name);
                [e-mail]();
            end
 
            function tf = reusable(~)
                tf = true;
            end
            
            function delete(obj)
                ...as above...
            end
        end
      end

このプロバイダーを再起動可能にするには、restartable メソッドと start メソッドを追加し、start メソッドで fseek を発行してファイルの先頭に戻ります。

            function start(obj)
                [e-mail]();
                fseek(obj.FileID, 0, -1);
            end
 
            function tf = restartable(~)
                tf = true;
            end

本文に ContentProvider を含む RequestMessage で complete または send を呼び出すと、MATLAB は、自動フィールドの追加前に、プロバイダーの Request プロパティをプロバイダーが配置された RequestMessage に設定し、Header プロパティを Request のヘッダーに設定します。その後、プロバイダーの次のメソッドを以下の順序で呼び出します。

• complete - RequestMessage.send または RequestMessage.complete を呼び出したときに、メッセージの最後に呼び出されます (通常はメッセージごとに 1 回)。プロバイダーの Header プロパティがプロバイダー固有のメッセージに追加するいずれかのヘッダー フィールドに設定されている必要があります。このメソッドが以降に MATLAB で呼び出された場合、プロバイダーでは新しいメッセージに使用されているものと仮定します。ほとんどのプロバイダーでは、このメソッドを実装してヘッダーを追加する必要があります。さらに、この抽象クラスの直接のサブクラスでない場合は、他の既定の動作を呼び出すためにスーパークラスも呼び出します。プロバイダーの reusable メソッドで true が返された場合を除き、MATLAB でプロバイダーの complete が複数回呼び出されることはありません。既定ではこの抽象クラスは再利用可能ではありませんが、matlab.net.http.io 名前空間の具象プロバイダーはすべて再利用可能です。

• preferredBufferSize/expectedContentLength - complete の後、start が呼び出されるまでの間に RequestMessage.send から呼び出されます。ほとんどのプロバイダーでは、既定の動作で問題がないため、これらのメソッドを実装する必要はありません。ただし、force 引数をサポートするようにオーバーライドすることができます。

これらのメソッドから戻った後、MATLAB は RequestMessage のヘッダーをサーバーに送信します。本文の送信時になると、MATLAB は次のメソッドを呼び出します。

• start - 前のメソッドの呼び出し後、サーバーで要求メッセージの本文を受信する準備ができたと MATLAB で判断された時点で RequestMessage.send から呼び出されます。これが以降に MATLAB で呼び出された場合、間に complete がなければ、プロバイダーでは (同じヘッダーをもつ) 同じメッセージの本文をもう一度送信するように求められているものと仮定します。プロバイダーの restartable メソッドで true が返された場合を除き、前回の complete の呼び出し以降に MATLAB で start が複数回呼び出されることはありません。既定ではこの抽象クラスは再起動可能ではありませんが、matlab.net.http.io 名前空間の具象プロバイダーはすべて再起動可能です。

• getData - start の呼び出し後、RequestMessage.send がブロックされている間、サーバーでデータの新しいバッファーを受信する準備ができたと MATLAB で判断されるたびに呼び出されます。このメソッドはデータの uint8 ベクトルを返さなければなりません。プロバイダーは stop インジケーターを返すことでデータの末尾を示します。このメソッドはすべてのプロバイダーで実装しなければなりません。

getData から stop インジケーターが返された後、MATLAB は要求メッセージを終了し、サーバーからの応答を待ちます。

デリゲーション

RequestMessage.Body に挿入された ContentProvider では、メッセージのすべてまたは一部のデータの提供を 1 つ以上の他のプロバイダーにデリゲートできます。たとえば、MultipartProvider は、複数のパートで構成されるメッセージを作成し、各パートを MultipartProvider コンストラクターに指定された他のプロバイダーから提供します。この場合、MultipartProvider がデリゲーターで、他のプロバイダーがデリゲートです。各デリゲートが順番に呼び出されて、それぞれのヘッダー フィールドとデータの位置を提供します。

あるプロバイダーから別のプロバイダーにデリゲートするには、delegateTo を呼び出して CurrentDelegate をデリゲートに設定し、デリゲートの MyDelegator を現在のプロバイダー (デリゲーター) に設定してから、デリゲートの complete メソッドと start メソッドを呼び出して、関数ハンドル GetDataFcn を返します。これにより、デリゲーターの getData メソッドでデリゲートの GetDataFcn が呼び出されてデータが取得されます。MATLAB に返す前に、データが変更されることもあります。一般に、プロバイダーでデリゲートであるかどうかを確認したり、そのデリゲート元を特定したりする必要はありません。

クラスの階層

バージョン履歴

R2018a で導入

参考

RequestMessage | MessageBody | FileProvider | StringProvider | JSONProvider | ImageProvider | MultipartProvider | FormProvider | MultipartFormProvider | QueryParameter | ContentConsumer