matlab.net.http.io.ContentConsumer - Consumer for HTTP message payloads - MATLAB (original) (raw)

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:

• FileConsumer
• StringConsumer
• JSONConsumer
• ImageConsumer
• MultipartConsumer
• BinaryConsumer
• GenericConsumer

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

expand all

Public Properties

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 theContentLength value of the top-level consumer.

Example: numel(someData) where someData is typeuint8

Attributes:

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 theMediaType. 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:

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:

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:

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:

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 emptyData and Payload properties. To store received data, consumers can modify the Response andMessageBody.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 asHeader 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 toputData(uint8.empty)) or when an exception occurs.

If an exception occurs in the consumer during message processing, then MATLAB throws an HTTPException object. TheHistory property contains this Response value.

If the consumer is a delegate that is processing part of a multipart message, thenResponse.Header contains the header of the whole message, and the Payload and Data properties ofResponse.Body are cleared before invoking theContentConsumer for each part. At the conclusion of each part, a newResponseMessage is added to the end of the array ofResponseMessage objects in the original response'sBody.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:

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 asResponse.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:

Protected Properties

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 aContentConsumer 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 defaultAppendFcn function is used, a subclass that processes all ofResponse.Body.Data on each call to putData might no longer have a use for the original data, so it can reset theCurrentLength property to 1 so that the nextputData 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 defaultAppendFcn 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:

The ContentConsumer to which this consumer is delegating, specified as a matlab.net.http.io.ContentConsumer object. ThedelegateTo 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 callinginitialize.

Attributes:

The ContentConsumer that delegated to this consumer, specified as amatlab.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:

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 itsdata 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 atconsumer.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 updateResponse.Body.Data to its final value.

The default behavior, if this property is empty, uses an internal function that treatsData as an array of arbitrary values supporting thehorzcat function. It efficiently addsnewdata by preallocating space, maintainingCurrentLength to be the actual length of data stored. At the end of the message, it truncates Response.Body.Data toCurrentLength.

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:

Methods

expand all

More About

expand all

When you specify a ContentConsumer in the call toRequestMessage.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);

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. AGenericConsumer also uses delegates. A ContentConsumer normally does not care whether it is a top-level consumer or a delegate. Any consumer in thematlab.net.http.io namespace can work as a delegate.

Version History

Introduced in R2018a