Main Content

expectedContentLength

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

Content length of ContentProvider

expand all in page

Syntax

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

Description

length = expectedContentLength(provider) 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 and RequestMessage.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 empty data and stop=true.

MATLAB calls this method from RequestMessage.send, RequestMessage.complete and in the delegate by delegateTo. MATLAB calls this after ContentProvider.complete and before ContentProvider.start. If this method is called before calling complete, 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's getData method must return stop=true after exactly that number of bytes have been returned. MATLAB always calls getData repeatedly, even if length=0, until getData returns stop=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 setting stop=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. See MultipartProvider for more information.

length = expectedContentLength(provider,force), 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 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.

An example of the use of force is a hypothetical CompressProvider 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, the CompressProvider needs to invoke the other provider's expectedContentLength with force set to true. If that other provider is a streaming JSONProvider, expectedContentLength normally returns [], because determining the length of a JSON string requires processing all of the input data. With force set to true, the JSONProvider's expectedContentLength 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 a matlab.net.http.io.ContentProvider object.

Indicate whether to return the length of the data, specified as true 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.

  • If this ContentProvider is not a multipart delegate (see MultipartProvider), and the message has a Content-Length field with a nonempty value (inserted in the original RequestMessage or added to the Header property by the complete method), then that Content-Length field is the length of the contents.

  • If there is no Content-Length field (or this provider is a multipart delegate), then the payload (or data in the part) ends when this provider's getData method sets the stop return value. In that case, the content length need not be specified.

Attributes

Accessprotected

Version History

Introduced in R2018a

See Also

| | | | | |