putData

Class: matlab.net.http.io.ContentConsumer
Namespace: matlab.net.http.io

Process or save next buffer of data for ContentConsumer

Syntax

[size,stop] = putData(consumer,data)


Description

[size,stop] = putData(consumer,data) provides a buffer of data read from the server to the consumer.

MATLAB^® calls putData. Subclass consumers can override this method to receive streamed data. Your consumer should return the length of data that it actually processed in size, and a true/false indication in stop to specify whether it wants to receive further data from this message.

When MATLAB calls putData with an empty data argument, it means that the message or message part in the case of a multipart message has ended.

If you create a subclass of a consumer that implements this method, your putData method can call its superclass putData to take advantage of any conversions or processing that the superclass implements.

MATLAB limits the size of data buffers to the bufsize value returned by the start method or an internal buffer size if bufsize is []. Also, if the server sends a chunk-encoded message, then a given call to putData never provides more than one chunk. This allows the consumer to obtain slowly arriving chunks in a timely manner even if bufsize is much larger than the chunk size.

Default behavior of putData() in this base class:

Subclass consumers have the option of storing their possibly converted content directly in Response.Body.Data, either incrementally or all at once, or disposing of it in some other way. The subclass consumer does not need to call this putData method to store data. As a convenience, consumers that want to store content incrementally in Response.Body.Data can call this method to do so. This method appends data to Response.Body.Data using the AppendFcn, attempting to do so efficiently by incrementally allocating capacity. The actual length of stored data is maintained in the CurrentLength property, which can be smaller than the actual length of Response.Body.Data. At the end of the transfer (for example, when putData(consumer,[]) or putData(consumer,uint8.empty) is called, Response.Body.Data is truncated to CurrentLength. You can define your own AppendFcn to implement an alternative append method.

By default this method always returns size equal to the numel(data) and stop equal to false.

If you intend to use this method to store data and you know the maximum length of data to be stored, then you should set Response.Body.Data to a vector of the desired size filled with default values (for example, zeros), before calling this method for the first time. This method starts storing data at the beginning of your data area and then truncates it to the length of data at the end of the message, maintaining the length of data stored in CurrentLength.

Consumers that call this method in this base class to store data incrementally can provide data of any type that supports horzcat or vertcat, including structures and cell arrays. If you provide a cell array, the existing Data is converted to a cell array if it is not already, and elements of the cell array are inserted into the existing cell array at the linear index beginning at CurrentLength+1.

If you call this method in ContentConsumer to store data, then you should let this method manage Response.Body.Data or CurrentLength and not modify them directly.

ContentConsumers that call this method in their superclass should be prepared to do any cleanup, such as closing windows or deleting temporary files, if the superclass throws an exception.

Input Arguments

consumer — Content consumer

matlab.net.http.io.ContentConsumer

Content consumer, specified as a matlab.net.http.io.ContentConsumer object.

data — Buffer of raw data in ResponseMessage

nonempty uint8 vector | uint8.empty | [] (empty double)

Buffer of raw data in a matlab.net.http.ResponseMessage object, specified as a one of the following:

• nonempty uint8 vector - A normal buffer of data read from the server.

• uint8.empty - End of data. This is the normal way MATLAB indicates that the response message has ended. This is an indication for the consumer to clean up (for example, delete temporary files or truncate response data to current length) and be prepared for a possible future call to initialize for a subsequent message. In response, the consumer should return stop=true and size=0 to indicate that processing was successful with no new bytes processed. If a consumer returns size=[], then the consumer had a problem finalizing the data and MATLAB throws an HTTPException back to the caller of RequestMessage.send.

• [] (empty double) - The server, a network problem, or the user (using Ctrl+C) aborted the transfer. The consumer should generally clean up exactly as if uint8.empty was received, but some consumers might delete any incomplete data already received. On return from putData, MATLAB throws an HTTPException whose History.Response contains any data that the consumer stored in its Response property.

Most consumers that do not care about the difference between [] and uint8.empty can simply check isempty(data) and clean up appropriately. In every case where data is empty, consumers must call their superclass putData with that same empty value, even if they are not using their superclass putData to store data, as that is the only way the superclass knows to clean up. After receiving an empty value of data, implementations must ignore subsequent calls to putData with empty values, until the next call to start. Typically they should return stop=false and size=0 on subsequent calls and not carry out any additional processing.

Output Arguments

size — Length of data processed

double | [] (empty double)

Length of data processed, returned as double or empty double. If the value of size is:

• size >= 0, size <= length(data) - The number of bytes of data processed by this call to putData. The number is used only for the benefit of subclasses of this consumer to know how much data was processed. It has no effect on future calls to putData. If data is empty, then size is ignored.

• size < 0 - The result of abs(size) is the number of bytes processed. Same as the previous case, but in addition, MATLAB silently skips the remainder of the data, making one more call to putData(uint8.empty) at the end of the data. If a MultipartConsumer is not being used, this is similar to returning stop=true, except for the additional call to putData at the end. If MultipartConsumer is being used, a negative value of size only ends the part, and does not affect processing of subsequent parts of the message, so the connection is not closed until the next part or end of message is reached.

• size = [] (empty double) - The consumer has decided something went wrong with the transfer and further transfers from the server should be terminated. This is similar to stop=true, but it is considered an error, causing a standard HTTPException to be thrown to the caller of RequestMessage.send indicating that the consumer aborted the connection. In this case, the only way the caller can get the partially processed ResponseMessage is through HTTPException.History.

  As an alternative to returning size=[] to throw a standard exception, your putData method can directly throw its own exception, which MATLAB wraps as a cause in an HTTPException returned to the caller of RequestMessage.send.

stop — Indicate whether to receive further data

false (default) | true

Indicate whether to receive further data from this message, specified as true or false. If stop is true, then the MATLAB stops processing the rest of the message, including any subsequent parts of a multipart message being processed by MultipartConsumer, silently proceeding as if the end of the message has been reached, even if the message has more data. This immediately closes the connection to the server and no error is returned to the caller of RequestMessage.send. This is not considered an error condition and is the normal way to terminate receipt of an arbitrary-length stream gracefully. If stop=true and data is not already empty, then MATLAB makes one additional call to putData with empty data. stop=true might be set whether or not data is empty.

Consumers should not normally set stop=true at the end of data, because, if they are multipart delegates, that would terminate processing for the rest of the message. To terminate processing just for their own part of the message, consumers should return size < 0 to indicate that they do not want to receive more data for their part.

Attributes

Access

public

Version History

Introduced in R2018a