matlab.net.http.io.ContentProvider.expectedContentLength - Content length of ContentProvider - MATLAB (original) (raw)

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

Content length of ContentProvider

Syntax

length = expectedContentLength(provider) length = expectedContentLength(provider,force)

Description

[length](#mw%5F9c11ac35-3f9c-40c3-ba89-a84bc917d38e) = expectedContentLength([provider](#d126e828182)) returns the expected content length in bytes. This method is intended to be overridden by subclasses that want to report their content length to MATLAB®. RequestMessage.send andRequestMessage.complete call this method and use the return value to set the Content-Length header field in the RequestMessage. If the message already has a Content-Length field with a value, and length is nonempty, then its value must be equal to the value in that Content-Length field.length might be 0 to indicate there is no contents, in which case the first call to getData should return emptydata and stop=true.

MATLAB calls this method from RequestMessage.send,RequestMessage.complete and in the delegate bydelegateTo. MATLAB calls this after ContentProvider.complete and beforeContentProvider.start. If this method is called before callingcomplete, then the return value might be invalid, because a provider cannot necessarily determine the length of its converted data without seeing all the header fields that control the conversion.

If you do not choose to have a Content-Length header field in your message (the message is being sent using chunked transfer coding), then the only reason to override this method and return a nonempty value is as a double-check to ensure that your provider returns the expected length of data.

In cases where the length of the data is known (that is, when this method returns a number or the Content-Length field is nonempty), this provider'sgetData method must return stop=true after exactly that number of bytes have been returned. MATLAB always calls getData repeatedly, even iflength=0, until getData returnsstop=true. In cases where the length is not known, if this is a top level provider (not a multipart delegate), then MATLAB uses chunked transfer coding to send the contents and the provider is free to return any length of data, including none, prior to settingstop=true.

You should return [] if you do not know the length of the data in advance, or if computing the length of the data would be time-consuming. It is harmless (and perfectly normal) to allow any message to use chunked transfer coding, even if you know the length. If this provider is a multipart delegate, a nonempty return value is only used to force an error in case getData returns more or fewer bytes, and will not cause a Content-Length header field to appear in the part. SeeMultipartProvider for more information.

[length](#mw%5F9c11ac35-3f9c-40c3-ba89-a84bc917d38e) = expectedContentLength([provider](#d126e828182),[force](#mw%5Fa0e7985d-b5a8-4065-a344-640e5be9b9d3)), if force is true, requires that you return the length of the data, computing it if necessary, even if you would otherwise return[], unless computing the length is impossible. If returning this number requires a lengthy computation or generation of all the data in the message, then you should cache the data so that you do not have to recompute it in subsequentgetData calls. The force argument is provided for use by subclasses who must know the length of the data in advance. MATLAB never sets this option when calling this method, and if you know that your provider is never used as a subclass that might set this option, then you can ignore theforce argument.

Callers of this method who get [] in response to settingforce to true can either consider it an error, or behave in a way that is compatible with content of unknown length.

Specifying force can negate the benefit of streaming (sending data as it is being generated) if it requires all the data to be generated to computelength, so this option is best used for special cases, for example debugging, or when the length of data is known to be small.

An example of the use of force is a hypotheticalCompressProvider that optionally compresses the output of any other provider, but only if that output is greater than a certain length (because compression is inefficient for short messages). To determine the length, theCompressProvider needs to invoke the other provider'sexpectedContentLength with force set totrue. If that other provider is a streamingJSONProvider, expectedContentLength normally returns[], because determining the length of a JSON string requires processing all of the input data. With force set totrue, the JSONProvider'sexpectedContentLength method processes all of the data (perhaps caching the output string internally for later use by its putData method), and returns that string's length.

Input Arguments

expand all

Content provider, specified as amatlab.net.http.io.ContentProvider object.

Indicate whether to return the length of the data, specified astrue or false.

If true, the expectedContentLength must return the length of the data, computing it if necessary, even if you would otherwise return [], unless computing the length is impossible. If returning this number requires a lengthy computation or generation of all the data in the message, then you should cache the data so that you do not have to recompute it in subsequent getData calls. The force argument is provided for use by subclasses who must know the length of the data in advance. MATLAB never sets this option when calling this method, and if you know that your provider is never used as a subclass that might set this option, then you can ignore the force argument.

Callers of this method who get [] in response to setting force to true can either consider it an error, or behave in a way that is compatible with content of unknown length.

Specifying force can negate the benefit of streaming (sending data as it is being generated) if it requires all the data to be generated to compute length, so this option is best used for special cases, for example, debugging, or when the length of data is known to be small.

Output Arguments

expand all

Expected content length, in bytes. If you do not override this method, then expectedContentLength returns []. MATLAB determines the content length as follows.

Attributes

Version History

Introduced in R2018a