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

名前空間: matlab.net.http.io
スーパークラス: matlab.net.http.io.ContentConsumer

HTTP ペイロードの文字列コンシューマー

説明

StringConsumer は、応答メッセージの文字データを Content-Type に基づく charset に従ってデコードして応答の本文に格納します。このコンシューマーを RequestMessage の送信時に直接指定して、特定のパラメーターのデータに対する文字列変換を指定できます。

このコンシューマーのサブクラス化の例については、Figure ウィンドウでのストリームデータの表示の PricesStreamer クラスを参照してください。

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

作成

説明

consumer = StringConsumer は、メッセージの Content-Type で指定された文字セットを使用して入力をスカラー string に変換するコンシューマーを構築します。

consumer = StringConsumer(Name,Value) は、1 つ以上の Name,Value のペアの引数で指定されたオプションを使用してコンシューマーを構築します。Name はプロパティ名の Charset または TextType で、Value は対応する値です。Name1,Value1,Name2,Value2 のように、名前と値のペアの引数を任意の順番で指定できます。

Charset プロパティを指定しない場合、このコンシューマーでは、Response の Content-Type フィールドに基づいて MATLAB^® で設定される ContentType プロパティからの charset の派生が試行されます。StringConsumer では、ContentType で charset パラメーターが明示的に指定されている場合、あるいはそのタイプの既定の charset が MATLAB で認識されている場合に charset が特定されます。

• "text/*" - サブタイプに応じて US-ASCII または UTF-8 のいずれか。

• "application/*" - サブタイプの UTF-8 (json、xml、javascript、css、x-www-form-urlencoded)、それ以外は不明。

このコンシューマーでメッセージの ContentType から charset を特定できない場合、メッセージは拒否されて変換されません。その場合、ResponseMessage.Body には uint8 ペイロードのみが格納されます。charset が不明なメッセージを変換する場合は、メッセージに適用する前 (サブクラスを作成している場合は initialize メソッドを呼び出す前) にこのコンシューマーで Charset を設定します。US-ASCII および他のいくつかの charset のスーパーセットである UTF-8 を使用することを推奨します。

プロパティ

パブリック プロパティ

Charset — 文字セット

空 (既定値) | string

データの変換に使用する文字セット。string として指定します。この値は最初は空です。空のままにすると、メッセージの受信時にメッセージの Content-Type フィールドで指定された charset または既定の charset に基づいて値が設定されます。変換に別の charset を使用する場合は、StringConsumer コンストラクターで charset を指定するか、このプロパティを直接設定します。このプロパティは、メッセージの途中も含め、サブクラスでいつでも設定できます。この値を putData の呼び出し後に変更した場合、後続の putData の呼び出しで新しい値が使用されます。Response.Body.Data の既存の内容は変更されません。

このプロパティを空のままにした場合、応答の受信の開始時に、MATLAB で Content-Type に基づいて選択された charset に設定されます。このコンシューマーを別のメッセージに再利用する場合は、新しい charset を選択できます。このプロパティを空でない値に設定した場合、MATLAB で変更されることはありません。

属性:

GetAccess	public
SetAccess	public
Dependent	true

TextType — データの戻り値の型

"string" (既定値) | "char"

返すデータの型。"string" または "char" として指定します。この値は 'TextType' パラメーターからコンストラクターに渡されます。既定の設定は "string" です。この値の変更時にデータが既に Response.Body.Data に格納されていた場合、そのデータは新しい型に変換されます。

属性:

GetAccess	public
SetAccess	public
Dependent	true

AllocationLength — 推奨されるバッファー サイズ

uint64

推奨されるバッファー サイズ。uint64 として指定されます。AllocationLength は、MATLAB により、putData に渡されるデータの予測されるバッファー サイズに設定されます。実際のサイズは、これよりも小さくなることも大きくなることもあります。パフォーマンスを向上させるために、この値を使用して、コンシューマーでデータを処理するためのスペースを事前に割り当てることができます。

このプロパティは、サブクラスで利用できるように、start メソッドを呼び出す前に MATLAB で設定されます。

属性:

GetAccess	public
SetAccess	public

ContentLength — 想定されるペイロードの長さ

uint64 | 空

想定されるペイロードの長さ。uint64 として指定されます。このプロパティは通常、Header プロパティにおける matlab.net.http.field.ContentLengthField の Value プロパティになります。

ContentLength が空の場合、長さは不明です。ペイロードは putData(uint8.empty) が呼び出された時点で終了します。

このプロパティは、サブクラスでデータの長さを確認できるように、initialize を呼び出す前に MATLAB で設定されます。

この ContentConsumer が最上位のコンシューマーのデリゲートである場合、ContentLength の値が最上位のコンシューマーの ContentLength と異なる値になることがあります。

例: numel(someData)。ここで、someData は uint8 型です。

属性:

GetAccess	public
SetAccess	public

ContentType — ペイロードのメディア タイプ

matlab.net.http.MediaType | 空

ペイロードのメディア タイプ。matlab.net.http.MediaType オブジェクトとして指定します。このプロパティは通常、Header プロパティにおける matlab.net.http.field.ContentTypeField の Value プロパティになります。ContentType プロパティが空の場合、ContentTypeField は空または存在しません。

このプロパティは、サブクラスで MediaType を確認できるように、initialize を呼び出す前に MATLAB で設定されます。データから別の MediaType であることがわかった場合は、サブクラスでこのプロパティを設定できます。

この値は、転送の終了時に MATLAB によって Response.Body.ContentType プロパティにコピーされます。

例: 'application/octet-stream'

属性:

GetAccess	public
SetAccess	public

Header — 現在処理中のペイロードのヘッダー

matlab.net.http.HeaderField

現在処理中のペイロードのヘッダー。matlab.net.http.HeaderField オブジェクトとして指定されます。

コンシューマーは、このヘッダーを使用して、送られてくるペイロードの処理方法を決定します。最上位のコンシューマーの場合、この値は Response.Header と同じになります。デリゲートの場合は値が異なることがあります。たとえば、MultipartConsumer で処理されるマルチパート メッセージの場合は、そのデリゲートで処理中のパートのヘッダーになります。デリゲートは引き続き Response.Header で元のメッセージのヘッダーを確認できます。

このプロパティは、サブクラスで利用できるように、initialize を呼び出す前に MATLAB で設定されます。

属性:

GetAccess	public
SetAccess	public

Request — 送信が完了した RequestMessage

matlab.net.http.RequestMessage

送信が完了した RequestMessage。matlab.net.http.RequestMessage オブジェクトとして指定します。これは、すべてのリダイレクトが完了した最終的な RequestMessage であり、send メソッドからの completedrequest 戻り値です。

このプロパティは、サブクラスで利用できるように、initialize を呼び出す前に MATLAB で設定されます。

属性:

GetAccess	public
SetAccess	public

Response — 処理中の ResponseMessage

matlab.net.http.ResponseMessage

処理中の ResponseMessage。matlab.net.http.ResponseMessage オブジェクトとして指定します。

Response プロパティは、initialize を呼び出す前に MATLAB で設定されます。この値は、ヘッダーの受信まで完了し、ペイロードを受信する前の ResponseMessage になります。応答メッセージの処理の開始時 (マルチパート メッセージの場合はパートの開始時) に、ResponseMesssage.Body プロパティは、Data プロパティと Payload プロパティが空の MessageBody オブジェクトになります。受信したデータを格納するために、コンシューマーはデータ転送中に Response プロパティと MessageBody.Data プロパティを変更できます。通常、コンシューマーはデータセット Response.Body.Data を処理してから処理済みのペイロードに格納しますが、これは必須ではありません。転送が完了すると、この Response が MATLAB から send の呼び出し元に返されます。Response の Header や StatusLine などの他のプロパティは、コンシューマーで変更しないでください。これらを変更した場合、その変更が send の呼び出し元に返されます。

Response.Body.Payload プロパティは転送中は空であり、コンシューマーで変更してはなりません。HTTPOptions.SavePayload プロパティが設定されると、次に MATLAB は、メッセージまたはパートの転送終了時 (putData(uint8.empty) の呼び出し後)、または例外の発生時に、受信したペイロードに Payload を設定します。

メッセージの処理中にコンシューマーで例外が発生した場合は、MATLAB から HTTPException オブジェクトがスローされます。History プロパティにはこの Response 値が含まれます。

コンシューマーがマルチパート メッセージのパートを処理するデリゲートの場合、Response.Header にメッセージ全体のヘッダーが格納され、各パートの ContentConsumer を呼び出す前に Response.Body の Payload プロパティと Data プロパティがクリアされます。各パートの最後で、元の応答の Body.Data にある ResponseMessage オブジェクトの配列の末尾に、このオブジェクトの Header およびこのプロパティの Body を含む、新しい ResponseMessage が追加されます。次のデリゲートでは、前のデリゲートの MessageBody ではなく空の MessageBody を含む新規の Response が確認されます。

属性:

GetAccess	public
SetAccess	public
Dependent	true

URI — 処理中の要求の送信先

matlab.net.URI

処理中の要求の送信先。matlab.net.URI オブジェクトとして指定されます。この値は、send で決定される元の送信先 URI の値になります。プロキシの URI やリダイレクト後の最終的な URI ではありません。

このプロパティは、サブクラスで利用できるように、initialize を呼び出す前に MATLAB で設定されます。

属性:

GetAccess	public
SetAccess	public

保護プロパティ

AppendFcn — データを追加するために putData で呼び出される関数

関数ハンドル

データを追加するために putData メソッドで呼び出される関数。関数ハンドルとして指定されます。このクラスの putData メソッドは、data 引数で受け取ったデータを応答メッセージの既存のデータに追加するために関数 AppendFcn を呼び出します。この関数のシグネチャは次のとおりでなければなりません。

AppendFcn(consumer,newdata)

newdata は、consumer.Response.Body.Data の配列に追加されるデータです。このメソッドは、Data の新しい長さに合わせて consumer.CurrentLength を更新する必要があります。newdata が空の場合はストリームの末尾を示し、関数により Response.Body.Data が最終的な値に更新されます。

既定の動作では、このプロパティが空の場合、Data を任意の値の配列として扱う、関数 horzcat に対応した内部関数が使用されます。この関数では、スペースを事前に割り当てることで効率的に newdata が追加され、格納されたデータの実際の長さが CurrentLength に反映されます。メッセージの最後に、Response.Body.Data が CurrentLength の値までで切り捨てられます。

horzcat が追加処理に適さない場合は、このプロパティをサブクラスで変更できます。たとえば、StringConsumer でスカラー string を作成する場合は、string への追加に関数 horzcat ではなく関数 plus を使用することがあります。

データを追加する ContentConsumer.putData を呼び出さない場合やデータを追加する際の horzcat の動作に問題がない場合は、サブクラスでこのプロパティを無視することができます。

例: @customAppend。@customAppend はコンシューマーによって定義されます。

属性:

GetAccess	protected
SetAccess	protected

CurrentDelegate — このコンシューマーによるデリゲート先の ContentConsumer

matlab.net.http.io.ContentConsumer | []

このコンシューマーによるデリゲート先の ContentConsumer。matlab.net.http.io.ContentConsumer オブジェクトとして指定します。呼び出し元のコンシューマー (デリゲーター) の delegateTo メソッドによって CurrentDelegate プロパティが設定されます。現在のデリゲーションがない場合、値は [] です。

MATLAB は initialize を呼び出す前に CurrentDelegate を [] に設定します。

属性:

GetAccess	protected
SetAccess	protected

CurrentLength — Response.Body.Data の現在のデータの長さ

uint64.empty (既定値) | uint64

Response.Body.Data プロパティの現在のデータの長さ。uint64 として指定されます。

このプロパティは、Response.Body.Data に事前に割り当てられたサイズが現在格納されている実際のデータの量よりも大きい場合に、格納されているデータの長さを示すために使用されます。このプロパティが空の場合は、すべての Response.Body.Data にデータが格納されているか、ContentConsumer サブクラスで Response.Body.Data に格納する以外の何らかの方法でデータが破棄されていることを示します。

このプロパティは、この基底クラスの putData メソッドで、AppendFcn プロパティが空の場合に使用および設定されます。putData を呼び出すサブクラスで既に格納されているデータを確認したり、AppendFcn の任意の実装で Response.Body.Data に結果を反映したりするのに使用できます。

putData を使用するサブクラスでは、このプロパティを変更してデータが格納されるバッファーの位置をリセットすることもできます。たとえば、既定の関数 AppendFcn を使用している場合、putData の呼び出しごとにすべての Response.Body.Data を処理するサブクラスで元のデータが不要になったときは、CurrentLength プロパティを 1 にリセットすることで次の putData の呼び出し時に新しいデータでバッファーを上書きできます。新しいデータの末尾を越えてバッファーの要素をクリアする必要はありません。

putData を呼び出さないサブクラスでは、このプロパティを独自のデータの追跡に使用できます。使用しない場合は未設定 (空) のままにしておいてかまいません。ここで設定できる値に関して、MATLAB にはいかなる制約もありません。また、この値は、既定の AppendFcn でデータの次のバッファーを格納する位置とメッセージの末尾のデータを切り捨てる位置を特定するためにのみ使用され、それ以外の目的には使用されません。データが切り捨てられないようにするには、putData(uint8.empty) の最後の呼び出しの前にこのプロパティを空に設定します。

このプロパティは、initialize の各呼び出しの前に MATLAB で空に設定されます。

属性:

GetAccess	protected
SetAccess	protected

MyDelegator — このコンシューマーのデリゲート元の ContentConsumer

matlab.net.http.io.ContentConsumer | 空

このコンシューマーのデリゲート元の ContentConsumer。matlab.net.http.io.ContentConsumer オブジェクトとして指定されます。このコンシューマーが GenericConsumer や MultipartConsumer などの別のコンシューマーから呼び出されたデリゲートである場合、これは呼び出し側のコンシューマーを示します。send の呼び出しで指定された最上位のコンシューマーの場合は空になります。

デリゲートは、このプロパティを使用してデリゲーターのプロパティにアクセスし、デリゲート元のコンシューマーなどを確認できます。

属性:

GetAccess	protected
SetAccess	protected

メソッド

パブリック メソッド

initialize	新しい HTTP メッセージの StringConsumer を準備する
start	StringConsumer へのデータ転送を開始する
putData	string データの次のバッファーを応答に追加する
convert	StringConsumer でデータを string に変換する
delegateTo	別のコンシューマーへのデリゲート

詳細

クラスの階層

バージョン履歴

R2018a で導入

参考

ResponseMessage | putData | initialize | ContentConsumer | StringProvider | ContentTypeField

トピック

• Figure ウィンドウでのストリームデータの表示