matlab.net.http.io.ContentConsumer Class
Namespace: matlab.net.http.io
Superclasses: handle
, matlab.mixin.Heterogeneous
Consumer for HTTP message payloads
Description
A ContentConsumer is an object that converts or processes data
received in an HTTP ResponseMessage
object. MATLAB® calls the consumer repeatedly during receipt of a response message to process
buffers of the payload as it is being received. You can act on or display this streamed data
while it is being received. You also can abort the transfer before receiving the entire
message. Using a consumer can improve latency (the delay between
receiving an instruction and the beginning of the transfer of data) when the time to process
the data is comparable to the speed of the network. It also allows you to receive unbounded
streamed response messages.
ContentConsumer
is an abstract class. To process incoming data received in
an HTTP response message, use one of the ContentConsumer
subclasses:
You also can write you own subclass of the ContentConsumer
class or extend
one of the subclasses.
The matlab.net.http.io.ContentConsumer
class is a handle
class.
Properties
Public Properties
ContentLength
— Expected length of payload
uint64
| empty
Expected length of the payload, specified as uint64
. The property
normally is the Value
property of the matlab.net.http.field.ContentLengthField
in the Header
property.
If ContentLength
is empty, then the length is not known. The
payload ends when putData(uint8.empty)
is called.
MATLAB sets this property before calling initialize
,
for the convenience of subclasses that might benefit from knowing the length of the
data.
If this ContentConsumer
is a delegate of a top-level consumer, then the
value of ContentLength
might be different from the
ContentLength
value of the top-level consumer.
Example: numel(someData)
where someData
is type
uint8
Attributes:
GetAccess | public |
SetAccess | public |
ContentType
— Media type of payload
matlab.net.http.MediaType
| empty
Media type of payload, specified as a matlab.net.http.MediaType
object. The
property normally is the Value
property of the matlab.net.http.field.ContentTypeField
in the Header
property. If the ContentType
property is empty, then the ContentTypeField
is empty or
nonexistent.
MATLAB sets this property before calling initialize
for the convenience of subclasses that might want to examine the
MediaType
. Subclasses can set this property if they determine from
the data that it is of a different MediaType
.
At the end of the transfer, MATLAB copies this value into the Response.Body.ContentType
property.
Example: 'application/octet-stream'
Attributes:
GetAccess | public |
SetAccess | public |
AllocationLength
— Suggested buffer size
uint64
Suggested buffer size, specified as uint64
. MATLAB sets AllocationLength
to the anticipated size of
buffers of data passed to putData
.
The actual size might be smaller or larger. To improve performance, the consumer can use
this value to preallocate space to handle the data.
MATLAB sets this property before calling the start
method for the convenience of subclasses.
Attributes:
GetAccess | public |
SetAccess | public |
URI
— Destination of request being processed
matlab.net.URI
Destination of the request being processed, specified as a matlab.net.URI
object. This value is the original destination URI as determined by send
. It is not the URI of a proxy or the final URI after redirections.
MATLAB sets this property before calling initialize
, for the convenience of subclasses.
Attributes:
GetAccess | public |
SetAccess | public |
Request
— Completed RequestMessage
that was sent
matlab.net.http.RequestMessage
The completed RequestMessage
that was sent, specified as a matlab.net.http.RequestMessage
object. This is the final RequestMessage
after all redirections, which is the completedrequest
return value from the send
method.
MATLAB sets this property before calling initialize
, for the convenience of subclasses.
Attributes:
GetAccess | public |
SetAccess | public |
Response
— ResponseMessage
being processed
matlab.net.http.ResponseMessage
The ResponseMessage
being processed, specified as a matlab.net.http.ResponseMessage
object.
MATLAB sets the Response
property before calling initialize
.
The value is the ResponseMessage
after headers have been received but
before receiving any payload. At the start of the response message processing (or the
start of a part for multipart messages), the ResponseMesssage.Body
property is a MessageBody
object with empty
Data
and Payload
properties. To store
received data, consumers can modify the Response
and
MessageBody.Data
properties during data transfer. Usually,
consumers that process and then store data set Response.Body.Data
to their processed payload, though this is not required. At the completion of the
transfer, MATLAB returns this Response
to the caller of send
. Consumers
should not modify other Response
properties, such as
Header
or StatusLine
, as those changes are
returned to the caller of send
.
The Response.Body.Payload
property is empty during the transfer
and consumers should not attempt to modify it. If the HTTPOptions.SavePayload
property is
set, then MATLAB sets Payload
to the received payload at the end of
the transfer of the message or the part (after the call to
putData(uint8.empty)
) or when an exception occurs.
If an exception occurs in the consumer during message processing, then MATLAB throws an HTTPException
object. The
History
property contains this Response
value.
If the consumer is a delegate that is processing part of a multipart message, then
Response.Header
contains the header of the whole message, and
the Payload
and Data
properties of
Response.Body
are cleared before invoking the
ContentConsumer
for each part. At the conclusion of each part, a new
ResponseMessage
is added to the end of the array of
ResponseMessage
objects in the original response's
Body.Data
containing the Header
from this
object and the Body
from this property. The next delegate sees a
fresh Response
with an empty MessageBody
, not the
previous delegate's MessageBody
.
Attributes:
GetAccess | public |
SetAccess | public |
Dependent | true |
Header
— Header of payload currently being processed
matlab.net.http.HeaderField
Header of the payload currently being processed, specified as a matlab.net.http.HeaderField
object.
Consumers use this header to determine how to process the payload that is being sent
to them. For a top-level consumer, this value is the same as
Response.Header
. For a delegate, the value might be different.
For example, in a multipart message processed by a MultipartConsumer
, it
is the header of the part that this delegate is processing. The delegate can still
examine Response.Header
for headers of the original message.
MATLAB sets this property before calling initialize
,
for the convenience of subclasses.
Attributes:
GetAccess | public |
SetAccess | public |
Protected Properties
CurrentLength
— Length of data currently in Response.Body.Data
uint64.empty
(default) | uint64
Length of data currently in the Response.Body.Data
property,
specified as uint64
.
This property is used when Response.Body.Data
has been
preallocated to a size larger than the actual amount of data currently stored, to
indicate the length of that stored data. If this property is empty, then it means that
all of Response.Body.Data
contains the stored data or that a
ContentConsumer
subclass is disposing of the data in some way other
than storing it in Response.Body.Data
.
This property is used and set by the putData
method in this base class when the AppendFcn
property is empty. It
is for the benefit of subclasses that call putData
and want to examine
already-stored data, and/or any implementations of AppendFcn
that
maintain results in Response.Body.Data
.
Subclasses that use putData
also can modify this property to reset
the position in the buffer where the data is stored. For example, when the default
AppendFcn
function is used, a subclass that processes all of
Response.Body.Data
on each call to putData
might no longer have a use for the original data, so it can reset the
CurrentLength
property to 1 so that the next
putData
call overwrites the buffer with new data. There is no need
to clear elements in the buffer past the end of the new data.
Subclasses that do not call putData
can use this property to track
their own data, or can leave it unset (empty). MATLAB does not place any constraints on the value that can be set here
and does not use it for any purpose other than to determine where the default
AppendFcn
should store the next buffer of data, and where to
truncate the data at the end of the message. Set this property to empty before the final
call to putData(uint8.empty)
to prevent truncation of the data.
MATLAB sets this property to empty before each call to initialize
.
Attributes:
GetAccess | protected |
SetAccess | protected |
CurrentDelegate
— ContentConsumer
to which this consumer is delegating
matlab.net.http.io.ContentConsumer
| []
The ContentConsumer
to which this consumer is delegating,
specified as a matlab.net.http.io.ContentConsumer
object. The
delegateTo
method of the calling consumer (the delegator)
sets the CurrentDelegate
property. If there is no current delegation, then
the value is []
.
MATLAB sets CurrentDelegate
to
[]
before calling
initialize
.
Attributes:
GetAccess | protected |
SetAccess | protected |
MyDelegator
— ContentConsumer
that delegated to this consumer
matlab.net.http.io.ContentConsumer
| empty
The ContentConsumer
that delegated to this consumer, specified as a
matlab.net.http.io.ContentConsumer
object. If this consumer is a
delegate that was invoked by another consumer, such as a GenericConsumer
or MultipartConsumer
, then this is the calling consumer. It is empty in a
top-level consumer specified in the call to send
.
Delegates can use this property to access properties of their delegators, for example, to determine which consumer delegated to them.
Attributes:
GetAccess | protected |
SetAccess | protected |
AppendFcn
— Function called by putData
to append additional data
function handle
Function, specified as a function handle, called by the putData
method to append additional data. The putData
method in this class
calls the AppendFcn
function to append data it receives in its
data
argument to existing data in the response message. The
function must have the signature:
AppendFcn(consumer,newdata)
where newdata
is the data to be appended to the array at
consumer.Response.Body.Data
. It is the responsibility of this
method to update consumer.CurrentLength
to reflect the new length
of Data
. If newdata
is empty, which indicates
the end of the stream, then the function should update
Response.Body.Data
to its final value.
The default behavior, if this property is empty, uses an internal function that treats
Data
as an array of arbitrary values supporting the
horzcat
function. It efficiently adds
newdata
by preallocating space, maintaining
CurrentLength
to be the actual length of data stored. At the
end of the message, it truncates Response.Body.Data
to
CurrentLength
.
Subclasses can change this property if horzcat
is not appropriate
for the append process. For example, when a StringConsumer
builds a
scalar string, it would add to the string using the plus
function
instead of horzcat
.
Subclasses that do not invoke ContentConsumer.putData
to append data,
or which are satisfied with horzcat
behavior when appending data,
can ignore this property.
Example: @customAppend
where @customAppend
is
defined by the consumer
Attributes:
GetAccess | protected |
SetAccess | protected |
Methods
Public Methods
initialize | Prepare consumer for new HTTP payload |
start | Start HTTP data transfer to ContentConsumer |
putData | Process or save next buffer of data for ContentConsumer |
delegateTo | Delegate to another consumer |
More About
Top-Level Consumer
When you specify a ContentConsumer
in the call to
RequestMessage.send
, the consumer is a top-level
consumer. MATLAB passes the entire payload as it is being received, a buffer at a time. For
example:
req = RequestMessage; resp = req.send(url, [], MyConsumer);
Delegate
A consumer invoked by another consumer to handle all or part of the data in a message is a delegate.
In the following code, mp
is the top-level consumer that receives the
entire payload of a multipart message.
mp = MultipartConsumer('image/*', ImageConsumer, 'text/*', StringConsumer); resp = req.send(url, [], mp);
ImageConsumer
and StringConsumer
objects are delegate
consumers that get only those parts of the payload that are images or text. A
GenericConsumer
also uses delegates. A ContentConsumer
normally does not care whether it is a top-level consumer or a delegate. Any consumer in the
matlab.net.http.io
namespace can work as a delegate.
Class Hierarchy
Version History
Introduced in R2018a
Comando de MATLAB
Ha hecho clic en un enlace que corresponde a este comando de MATLAB:
Ejecute el comando introduciéndolo en la ventana de comandos de MATLAB. Los navegadores web no admiten comandos de MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)