matlab.net.http.io.StringProvider class

Package: matlab.net.http.io
Superclasses: matlab.net.http.io.ContentProvider

ContentProvider to send MATLAB strings

Description

Use a StringProvider object to send a MATLAB^® string or character vector in a RequestMessage. By default, if a RequestMessage.Body.Data property contains a string or character vector, then it is converted to binary according to the encoding (charset) specified or implied by the Content-Type field in the message, so you would not normally need to use this object to send plain text in cases where MATLAB can determine what encoding to use.

Use this object in a Request.Body property to send a string encoded using a charset that might be different from the one that MATLAB would use for the Content-Type in the header. You specify that charset in the ContentProvider constructor or by setting the Charset property. If the message contains no Content-Type, this provider adds one specifying "text/plain" and the specified charset.

The matlab.net.http.io.StringProvider class is a handle class.

Creation

Description

provider = StringProvider constructs a StringProvider to send the data in the Data property encoded with the value specified in the Charset property. Set these properties before sending a message that contains this provider.

provider = StringProvider(data,charset) constructs a StringProvider to send the specified data encoded with the specified charset. The constructor sets the Data property to the value of data and the Charset property to the value of charset. The charset argument is optional.

Properties

Public Properties

Data — Data to send

string | character vector

Data to send, specified as a string or character vector. This is the value of Data that was provided to the constructor. You also can set this property directly, after calling the constructor, or in your subclass.

Subclass authors can set this property to new data at any time. The next call to getData converts this data, up to the value of the getData length argument.

Attributes:

GetAccess	public
SetAccess	public
Dependent	true

Charset — Character set used for encoding

'' (default) | character vector

Character set used for encoding, specified as a character vector.

Attributes:

GetAccess	public
SetAccess	public
Dependent	true

Header — Header fields of message or part

matlab.net.http.HeaderField.empty (default) | matlab.net.http.HeaderField

Header fields of the message or part, specified as a vector of one or more matlab.net.http.HeaderField objects.

This property is only used by subclass authors. MATLAB sets this property before calling the provider's complete method. For non-multipart messages, MATLAB initializes this property to the contents of Request.Header, minus any matlab.net.http.field.GenericFields or empty-valued fields. The ContentProvider uses this property to add header fields that describe the data to be sent, or to add parameters to header fields already in the message. In a delegate for a MultipartProvider, MATLAB initializes this property to header fields that the delegating provider intends to insert for the part. Delegates can modify or change these fields.

Upon return from the provider's complete method, if this not a multipart message, then MATLAB reads this property and merges its contents into the header of Request. Fields in this Header with Names that do not already appear in Request.Header are added to the end of Request.Header. If a field in this Header has a Name that is the same as one in Request.Header, and both have nonempty Values, then:

• If the one in Request.Header is a GenericField, then ignore the one in Header.

• If the one in Request.Header is not a GenericField, then replace it with the one in Header.

If one or both of these has an empty Value, then the field is removed from Request.Header and it is not added as part of normal message completion.

If this is a delegate of a MultipartProvider, then the entire contents of this Header is used as the header of the part. Multipart delegates must not assume that Request.Header contains any fields pertaining to their own Header. A provider can determine whether it is a multipart delegate by checking whether MyDelegator is a MultipartProvider, though this test is unlikely to be needed.

MATLAB reads this property only on return from calling the provider's complete method. Changes to this array are ignored once MATLAB calls start.

Class authors should be aware that their subclasses might have added fields to this Header (in their complete method) before calling complete in their superclass. It is best to preserve such fields and not to add fields with the same names. However, adding a parameter to a field is permissible. For example, a superclass can add a charset parameter to an existing Content-Type field that does not already have one.

Attributes:

GetAccess	public
SetAccess	public

ForceChunked — Indicate whether to force chunked transfer coding

false (default) | true

Indicate whether to force chunked transfer coding, specified as boolean. This property is of interest only to subclass authors, and is applicable only to providers that are not multipart delegates. Subclasses set ForceChunked to control whether contents should be sent using chunked transfer coding. If false (default), MATLAB decides whether to send the contents chunked, based on whether it knows the content length at the time the message is ready to be sent:

• If MATLAB knows the content length (which is the case if the message contains a Content-Length field, or if this provider's expectedContentLength method returned a number), then MATLAB decides whether to send it chunked or not.

• If MATLAB does not know the content length (no Content-Length field in the header and expectedContentLength returned empty), then MATLAB always sends the message chunked.

If ForceChunked is true, then MATLAB sends the message chunked regardless of whether it knows the content length, unless the known length is smaller than the chunk size. If this property is true, then the message must not contain a Content-Length field, because HTTP does not allow a chunked message to have a Content-Length field. However, you can still return a nonzero value in the expectedContentLength method if you want MATLAB to verify that you are returning the expected length of data.

When MATLAB chooses to send the message chunked, the size of each chunk is equal to the length of data returned by getData.

MATLAB reads this value after calling the complete method, before calling start. It does not set this field.

Attributes:

GetAccess	public
SetAccess	public

Request — Request message to send

matlab.net.http.RequestMessage

Request message to send, specified as a matlab.net.http.RequestMessage object.

This property is used only by subclass authors. The RequestMessage.send and RequestMessage.complete methods set this property to the RequestMessage in whose Body this provider has been placed, before calling any other methods in this provider, and before adding any additional header fields or validating the message. The provider can examine this message to see what was contained in the original request.

Delegates see the same value for this property as the delegator. ContentProviders should be aware that, if they are delegates, they are not necessarily providing the entire body of the request message, so they should not assume that header fields in this Request are pertinent to the data they are providing. Usually, delegates should ignore header fields in this request relevant to the data, such as Content-Type.

If the provider wishes to add any header fields to this message, or to modify existing ones, it should do so in its complete method by adding those fields to the Header property. The caller of complete (RequestMessage or a delegating provider) determines what to do with those fields. RequestMessage.send and RequestMessage.complete always copy these fields to the Header of the RequestMessage. A delegating provider can copy the fields to its own Header property or insert them into the message (as in the case of MultipartProvider). For more information, see the Header property.

This property is read-only.

Attributes:

GetAccess	public
SetAccess	matlab.net.http.RequestMessage

Protected Properties

CurrentDelegate — ContentProvider to which this provider is delegating

matlab.net.http.io.ContentProvider | empty

ContentProvider to which this provider is delegating, specified as a matlab.net.http.io.ContentProvider object. This property is set in the calling provider (the delegator) by the delegateTo method to indicate the current delegated provider. If there is no current delegation, then the value is empty.

The complete methods set this property to empty.

Attributes:

GetAccess	protected
SetAccess	protected

MyDelegator — ContentProvider that delegated to this provider

matlab.net.http.io.ContentProvider.empty (default) | matlab.net.http.io.ContentProvider

ContentProvider that delegated to this provider, specified as a matlab.net.http.io.ContentProvider object.

If a ContentProvider delegates responsibility for sending all or a portion of the message data to another provider, then this property identifies the delegating provider to the delegate. For example, a MultipartProvider delegates parts of the message to other providers, so it inserts a handle to itself in each delegate. Otherwise, MyDelegator is empty. The delegateTo method sets this property in the delegate.

Attributes:

GetAccess	protected
SetAccess	protected

Methods

Public Methods

getData

Next buffer of data to send in HTTP request message from StringProvider

Specialized Operators and Functions

These methods specialize standard MATLAB operators and functions and inherited methods for objects in this class.

string	Provider information as string
show	Display provider information

Protected Methods

complete	Complete HTTP header for StringProvider
preferredBufferSize	Preferred buffer size for ContentProvider
expectedContentLength	Content length of ContentProvider
start	Start data transfer from StringProvider
restartable	Indicate whether ImageProvider is restartable
reusable	Indicate whether ImageProvider is reusable
delegateTo	Delegate to another provider

Examples

Using StringProvider

The following code prepares a message that sends the string "myText" using the Content-Type "text/plain" to the server using Shift_JIS encoding:

ctf = ContentTypeField(MediaType('text/plain','charset','Shift_JIS');
r = RequestMessage('put',ctf,StringProvider('myText'));

In this example, the header has no Content-Type field, so StringProvider inserts one based on the constructor arguments.

r = RequestMessage('put',[],StringProvider('myText','Shift_JIS'));
show(r.complete('www.someurl.com'))

PUT / HTTP/1.1
      Host: www.someurl.com
      Content-Type: text/plain; charset=Shift_JIS
      User-Agent: MATLAB/9.2.0.512567 (R2017b)
      Connection: close
      Date: Fri, 20 Jun 2017 14:26:42 GMT

In this example, the charset specified to the StringProvider constructor used to convert the data is different from the charset in the Content-Type field. StringProvider does not alter an existing Content-Type field that already specifies a character set, so the server assumes that the data is US-ASCII, not Shift-JIS.

ctf = ContentTypeField(MediaType('text/plain','charset','US-ASCII'));
      r = RequestMessage('put',ctf,StringProvider('myText','Shift_JIS'));

In this example, MATLAB adds a charset parameter to the Content-Type field that did not specify a charset, because the default for "application/json" is UTF-8, which is different from Shift_JIS.

ctf = ContentTypeField(MediaType('application/json'));
      r = RequestMessage('put',ctf,StringProvider('myText','Shift_JIS'));
      show(r.complete('www.someurl.com'))

PUT / HTTP/1.1
      Host: www.someurl.com
      Content-Type: application/json; charset=Shift_JIS
      User-Agent: MATLAB/9.2.0.512567 (R2017b)
      Connection: close
      Date: Fri, 20 Jun 2017 14:26:42 GMT

When there is no Content-Type header field and no charset is specified to StringProvider, MATLAB uses a heuristic to find the "minimal" encoding that can represent the data, one of which includes the default encoding for the platform. In this example when run on Windows, the Unicode^® characters in the string are within the Windows-1252 range, but outside the US-ASCII range, so Windows-1252 is used:

r = RequestMessage('put',[],StringProvider('€abc'));
      show(r.complete('www.someurl.com'))

PUT / HTTP/1.1
      Host: www.someurl.com
      Content-Type: text/plain; charset=windows-1252
      User-Agent: MATLAB/9.2.0.512567 (R2017b)
      Connection: close
      Date: Fri, 20 Jun 2017 14:26:42 GMT

In this case, the Content-Type field specifies "application/json" with no charset, and none is specified to StringProvider. Since the default charset for "application/json" is UTF-8, StringProvider uses that to convert and does not specify the charset explicitly in the Content-Type field.

ctf = ContentTypeField(MediaType('application/json'));
      r = RequestMessage('put',ctf,StringProvider('myText')); % uses UTF-8

More About

Class Hierarchy