matlab.net.http.io.ContentProvider 클래스

네임스페이스: matlab.net.http.io
슈퍼클래스: handle, matlab.mixin.Heterogeneous

HTTP 메시지 페이로드에 대한 ContentProvider

설명

ContentProvider는 메시지가 전송되는 중에 HTTP RequestMessage에 대한 데이터를 제공합니다. 간단한 제공자는 데이터를 MATLAB^® 유형에서 바이트 스트림으로 변환합니다. 보다 복잡한 제공자는 서버에 데이터를 스트리밍하여 데이터 전송과 동시에 데이터를 가져오거나 생성할 수 있기 때문에 메시지 시작 전에 모든 데이터를 메모리에 저장할 필요가 없습니다.

일반적으로 (보통 PUT 또는 POST 요청을 통해) 데이터를 웹 서비스로 전송할 때 RequestMessage를 생성하여 데이터를 MessageBody 객체 형식으로 RequestMessage.Body 속성에 삽입합니다. 이 메시지를 RequestMessage.send를 사용하여 전송하면 MATLAB은 데이터를 서버로 전송할 바이트 스트림으로 변환하는데, 이때 메시지의 Content-Type과 Body.Data 데이터 유형에 따라 변환을 수행합니다. 이러한 변환 규칙에 대한 자세한 내용은 MessageBody.Data를 참조하십시오.

RequestMessage.Body 속성에 MessageBody 객체를 삽입하는 대신 ContentProvider 객체를 생성하여 삽입할 수 있습니다. 이렇게 하면 메시지를 전송할 때 MATLAB이 ContentProvider의 메서드를 호출하여 메시지가 전송되는 동안 전송할 데이터 버퍼를 가져옵니다.

메시지에 MessageBody나 ContentProvider를 삽입하면 RequestMessage.send를 호출해도 전체 메시지가 전송되어 응답이 수신되기 전까지 또는 오류가 발생하기 전까지 결과가 반환되지 않습니다(즉, 메서드의 호출이 차단됩니다). 반면 ContentProvider를 사용하면 send 메서드가 차단된 기간 동안 MATLAB이 제공자에게 주기적으로 콜백을 수행하여 전송할 데이터 버퍼를 가져옵니다. ContentProvider는 이러한 콜백을 통해 파일, MATLAB 배열, 하드웨어 센서, MATLAB 함수 등 어떠한 소스에서도 데이터를 가져올 수 있습니다. 제공자의 역할은 이러한 데이터를 웹으로 전송될 수 있는 uint8 버퍼 형태의 바이트 스트림으로 변환하는 것입니다.

ContentProvider는 클래스 작성자가 자체 데이터 생성기나 변환기를 사용하여 서브클래스를 작성하는 데 사용할 수 있는 추상 클래스입니다. 또는 서브클래스를 작성하지 않고도 다양한 소스에서 데이터를 생성하는 MATLAB 제공자 중 하나를 사용(또는 서브클래스화)할 수 있습니다. 이러한 제공자에는 MessageBody에 직접 데이터를 삽입할 때 이루어지는 자동 변환에 비해 데이터를 더욱 유연하게 가져오고 변환할 수 있는 다양한 옵션이 있습니다. 다음과 같은 ContentProvider 서브클래스 중 하나를 사용하십시오.

• FileProvider

• StringProvider

• JSONProvider

• ImageProvider

• FormProvider

• MultipartProvider

• MultipartFormProvider

• GenericProvider

데이터를 스트리밍할 필요가 없더라도, 이러한 제공자 중 하나를 사용하면 데이터가 내부적인 형태에서 uint8 스트림으로 변환되기 때문에 특정 유형의 콘텐츠를 전송하는 과정이 간소화됩니다. 예를 들어, FormProvider를 사용하면 데이터를 QueryParameter 객체로 구성된 배열로 편리하게 표현하여 서버로 양식 응답을 전송할 수 있습니다. MultipartFormProvider를 사용하면 multipart 양식의 응답을 간편하게 생성하여 multipart 양식 응답을 전송할 수 있습니다. 이러한 ContentProvider를 사용하려면 서버에서 수신을 예상하는 콘텐츠의 유형에 대해 알고 있어야 합니다.

matlab.net.http.io.ContentProvider 클래스는 handle 클래스입니다.

서브클래스 작성자

가장 단순한 ContentProvider는 MATLAB이 요구하는 대로 데이터 버퍼를 제공하는 getData 메서드만 구현하면 됩니다. 제공자를 사용하려면 RequestMessage의 Body 속성에 제공자를 삽입하십시오. 이 예에서는 RequestMessage생성자의 세 번째 인수인 MyProvider 객체가 Body에 삽입됩니다.

provider = MyProvider;
req = matlab.net.http.RequestMessage('put', headers, provider);
resp = req.send(uri);

다음은 생성자의 인수로서 전달된 파일 이름으로부터 데이터를 읽어 들여 웹으로 전송하는 MyProvider 클래스의 예입니다. 그리고 제공자가 삭제될 때와 마지막에 파일을 닫았습니다.

    classdef MyProvider < matlab.net.http.io.ContentProvider
        properties
            FileID double
        end
 
        methods
            function obj = MyProvider(name)
                obj.FileID = fopen(name);
            end
 
            function [data, stop] = getData(obj, length)
                [data, len] = fread(obj.FileID, length, '*uint8');
                stop = len < length;
                if (stop)
                    fclose(obj.FileID);
                    obj.FileID = [];
                end
            end
 
            function delete(obj)
                if ~isempty(obj.FileID)
                    fclose(obj.FileID);
                    obj.FileID = [];
                end
            end
        end
    end

MATLAB은 전송할 새 메시지를 생성할 때 제공자의 complete 메서드를 호출합니다. 그 목적은 제공자가 새 메시지에 대해 준비하고 이 메시지에 필요한 헤더 필드를 추가하도록 하는 것입니다. MATLAB은 데이터를 전송할 시점이 되면 getData를 최초로 호출하기 전에 먼저 제공자의 start 메서드를 호출합니다.

속성

퍼블릭 속성

Header — 메시지 또는 파트의 헤더 필드

matlab.net.http.HeaderField.empty (디폴트 값) | matlab.net.http.HeaderField

메시지 또는 파트의 헤더 필드로, 하나 이상의 matlab.net.http.HeaderField 객체로 구성된 벡터로 지정됩니다.

서브클래스 작성자만 이 속성을 사용합니다. MATLAB은 제공자의 complete 메서드를 호출하기 전에 먼저 이 속성을 설정합니다. multipart가 아닌 메시지의 경우, MATLAB은 Request.Header의 내용에서 matlab.net.http.field.GenericFields나 값이 비어 있는 필드를 제외한 값으로 이 속성을 초기화합니다. ContentProvider는 이 속성을 사용하여 전송할 데이터를 설명하는 헤더 필드를 추가하거나 이미 메시지에 있는 헤더 필드에 파라미터를 추가합니다. MultipartProvider의 대리자에서, 위임하는 제공자가 해당 파트에 대해 삽입하고자 하는 헤더 필드로 MATLAB은 이 속성을 초기화합니다. 대리자는 이러한 필드를 수정하거나 변경할 수 있습니다.

제공자의 complete 메서드에서 반환되면 multipart 메시지가 아닌 경우 MATLAB은 이 속성을 읽어 해당 내용을 Request의 헤더에 병합합니다. 이 Header의 필드 중에서 Request.Header에 나타나지 않은 Names를 갖는 필드는 Request.Header의 끝에 추가됩니다. 이 Header의 한 필드의 Name이 Request.Header의 그것과 같고, 두 필드 모두 비어 있지 않은 Values를 갖는 경우,

• Request.Header의 필드가 GenericField이면 Header의 필드를 무시하십시오.

• Request.Header의 필드가 GenericField가 아니면 이 필드를 Header의 필드로 대체하십시오.

이러한 필드 중 하나 또는 둘 모두가 빈 Value를 가지면, 해당 필드가 Request.Header에서 제거되고 정상적인 메시지 완료 과정의 일부로 추가되지 않습니다.

MultipartProvider의 대리자인 경우 Header의 전체 내용이 해당 파트의 헤더로 사용됩니다. multipart 대리자는 Request.Header에 자신의 Header와 관련 있는 필드가 포함되어 있다고 간주해서는 안 됩니다. 제공자는 MyDelegator가 MultipartProvider인지 보고 multipart 여부를 확인할 수 있지만, 이런 테스트가 필요한 경우는 드뭅니다.

MATLAB은 제공자의 complete 메서드 호출 후 반환된 경우에만 이 속성을 읽어 들입니다. MATLAB이 start를 호출하면 이 배열의 변경 사항은 무시됩니다.

클래스 작성자는 슈퍼클래스에서 complete를 호출하기 전에 서브클래스가 이 Header에(서브클래스의 complete 메서드에) 필드를 추가했을 수 있다는 사실에 유의해야 합니다. 이러한 필드를 그대로 유지하고 같은 이름을 갖는 필드를 추가하지 않는 것이 좋습니다. 단, 필드에 파라미터를 추가하는 것은 허용됩니다. 예를 들어, 슈퍼클래스는 문자 집합 파라미터를 갖지 않는 기존 Content-Type 필드에 문자 집합 파라미터를 추가할 수 있습니다.

특성:

GetAccess	public
SetAccess	public

ForceChunked — 청크 형식의 전송 코딩을 강제할지 여부를 나타내는 표시

false (디폴트 값) | true

청크 형식의 전송 코딩을 강제할지 여부를 나타내는 표시로, 부울로 지정됩니다. 이 속성은 서브클래스 작성자에게만 사용하며, multipart 대리자가 아닌 제공자에게만 적용됩니다. 서브클래스는 ForceChunked를 설정하여 청크 형식의 전송 코딩을 사용하여 내용을 전송할지 여부를 제어합니다. false(디폴트 값)인 경우, MATLAB은 메시지의 전송 준비가 완료된 시점에 콘텐츠 길이를 알고 있는지에 따라 청크 형식으로 콘텐츠를 전송할지 여부를 결정합니다.

• MATLAB이 콘텐츠 길이를 알고 있는 경우(메시지가 Content-Length 필드를 포함하거나 이 제공자의 expectedContentLength 메서드가 숫자를 반환한 경우), MATLAB은 청크 형식으로 콘텐츠를 전송할지 여부를 결정합니다.

• MATLAB이 콘텐츠 길이를 알지 못하는 경우(헤더에 Content-Length 필드가 없고 expectedContentLength가 비어 있는 값을 반환한 경우), MATLAB은 항상 청크 형식으로 메시지를 전송합니다.

ForceChunked가 true이면 MATLAB은 알려진 길이가 청크 크기보다 작은 경우를 제외하고 콘텐츠 길이를 알고 있는지에 관계없이 청크 형식으로 메시지를 전송합니다. HTTP는 청크 형식 메시지가 Content-Length 필드를 갖는 것을 허용하지 않으므로 이 속성이 true인 경우 메시지가 Content-Length 필드를 포함하면 안 됩니다. 단, 사용자가 예상 데이터 길이를 반환하는지 MATLAB이 확인하기를 원하는 경우에는 expectedContentLength 메서드에서 여전히 0이 아닌 값을 반환할 수 있습니다.

MATLAB이 청크 형식 메시지를 전송하기로 결정한 경우, 각 청크의 크기는 getData가 반환한 데이터의 길이와 동일합니다.

MATLAB은 complete 메서드를 호출한 다음 start를 호출하기 전에 이 값을 읽어 들입니다. 이때, 이 필드를 설정하지는 않습니다.

특성:

GetAccess	public
SetAccess	public

Request — 전송할 요청 메시지

matlab.net.http.RequestMessage

전송할 요청 메시지로, matlab.net.http.RequestMessage 객체로 지정됩니다.

서브클래스 작성자만 이 속성을 사용합니다. RequestMessage.send 메서드와 RequestMessage.complete 메서드는 이 제공자의 다른 메서드를 호출하기 전에, 그리고 추가 헤더 필드를 추가하거나 메시지의 유효성을 검사하기 전에 Body에 이 제공자가 배치된 RequestMessage에 이 속성을 설정합니다. 제공자는 이 메시지를 검토해 원본 요청에 어떤 데이터가 포함되었는지 확인할 수 있습니다.

대리자에게 표시되는 이 속성의 값은 위임 주체에게 표시되는 값과 동일합니다. ContentProviders는 자신이 대리자인 경우 요청 메시지의 본문 중 일부만 제공할 수도 있으므로 이 요청의 헤더 필드가 자신이 제공하는 데이터와 관련이 있다고 간주하면 안 됩니다. 일반적으로 대리자는 이 요청의 헤더 필드 중에서 Content-Type과 같이 데이터와 관련 있는 필드를 무시해야 합니다.

제공자가 이 메시지에 헤더 필드를 추가하거나 기존 헤더 필드를 수정하려는 경우, complete 메서드에서 이러한 필드를 Header 속성에 추가해야 합니다. complete의 호출자(RequestMessage 또는 위임하는 제공자)는 이러한 필드를 어떻게 처리할지 결정합니다. RequestMessage.send와 RequestMessage.complete는 항상 이러한 필드를 RequestMessage의 Header로 복사합니다. 위임하는 제공자는 이러한 필드를 자신의 Header 속성에 복사하거나 (MultipartProvider의 경우와 같이) 메시지에 삽입할 수 있습니다. 자세한 내용은 Header 속성을 참조하십시오.

이 속성은 읽기 전용입니다.

특성:

GetAccess	public
SetAccess	matlab.net.http.RequestMessage

보호 속성

CurrentDelegate — 이 제공자가 위임하는 ContentProvider

matlab.net.http.io.ContentProvider | 비어 있음

이 제공자가 위임하는 ContentProvider로, matlab.net.http.io.ContentProvider 객체로 지정됩니다. 이 속성은 호출하는 제공자(위임 주체)가 delegateTo 메서드에서 설정하며, 현재 위임된 제공자를 나타냅니다. 현재 위임이 없는 경우, 이 값은 비어 있습니다.

complete 메서드는 이 속성을 비어 있는 값으로 설정합니다.

특성:

GetAccess	protected
SetAccess	protected

MyDelegator — 이 제공자에게 위임된 ContentProvider

matlab.net.http.io.ContentProvider.empty (디폴트 값) | matlab.net.http.io.ContentProvider

이 제공자에게 위임된 ContentProvider로, matlab.net.http.io.ContentProvider 객체로 지정됩니다.

ContentProvider가 메시지 데이터의 일부 또는 전부를 전송하는 작업에 대한 책임을 다른 제공자에게 위임한 경우, 이 속성은 대리자에게 위임한 제공자를 식별합니다. 예를 들어, MultipartProvider는 메시지의 여러 파트를 다른 제공자들에게 위임하므로, 자신에 대한 핸들을 각 대리자에 삽입합니다. 그러지 않으면 MyDelegator는 비어 있습니다. delegateTo 메서드는 대리자에 이 속성을 설정합니다.

특성:

GetAccess	protected
SetAccess	protected

메서드

퍼블릭 메서드

string	ContentProvider를 string형으로 표시
show	ContentProvider 정보 표시

보호 메서드

complete	ContentProvider에 대한 HTTP 헤더 완성
preferredBufferSize	ContentProvider의 기본 설정 버퍼 크기
expectedContentLength	ContentProvider의 콘텐츠 길이
start	ContentProvider로부터 데이터 전송 시작
restartable	ContentProvider의 재시작 가능 여부 표시
reusable	ContentProvider의 재사용 가능 여부 표시
delegateTo	다른 제공자에게 위임

추상 메서드

getData

ContentProvider로부터 HTTP 요청 메시지에 포함하여 전송할 다음 데이터 버퍼

세부 정보

재시작 가능성과 재사용 가능성

제공자는 재시작 및/또는 재사용이 가능합니다. 재시작이 가능하다는 것은 이전 호출이 정상적으로 완료되지 않은 경우에도 MATLAB이 start를 호출할 때마다 동일한 데이터 스트림으로 동일한 메시지를 여러 차례 재전송할 수 있음을 의미합니다. 이 동작은 서버가 메시지를 다른 서버로 리디렉션할 수 있으므로, 즉 데이터의 재전송이 필요하기 때문에 요구됩니다. 이 경우, MATLAB은 complete를 다시 호출하지 않고 start를 호출합니다. MATLAB은 restartable 메서드를 호출하여 제공자의 재시작 가능 여부를 파악합니다. false가 반환되면 MATLAB이 이미 시작된 제공자에 대해 start를 호출해야 하는 경우 중간에 complete가 호출되지 않았다면(이 메서드는 새 메시지인 경우에만 호출됨) 예외를 발생시킵니다.

재사용이 가능하다는 것은 MATLAB이 complete 메서드를 호출할 때마다 서로 다른 메시지나 동일한 메시지에 대해 제공자를 재사용할 수 있음을 의미합니다. MATLAB은 reusable 메서드를 호출하여 제공자의 재사용 가능 여부를 파악합니다. false가 반환되면 MATLAB이 이미 시작된 제공자에 대해 complete를 호출해야 하는 경우 예외를 발생시킵니다. 제공자가 재사용 가능하다면 제공자가 재시작이 가능한 경우에도 start에 대한 다음 호출이 성공할 것이라고 가정할 수 있습니다.

ContentProvider는 restartable과 reusable 둘 다에 대해 false를 반환합니다. 따라서 재시작 가능하거나 재사용 가능한 제공자를 사용하여 이 기본 클래스를 직접 확장하는 경우에는 두 메서드 중 하나가 또는 둘 다가 true를 반환하도록 재정의해야 합니다. matlab.net.http.io 네임스페이스에 포함된 ContentProvider의 모든 구체 서브클래스는 재시작 및 재사용이 모두 가능하기 때문에 두 메서드에 대해 true를 반환합니다. 이러한 서브클래스를 재사용 또는 재시작이 가능하지 않은 제공자를 사용하여 확장하는 경우에는 두 메서드 중 하나가 또는 둘 다가 false를 반환하도록 재정의해야 합니다.

이 예에서 MyProvider 클래스는 메시지의 끝에서 파일을 닫기 때문에 재시작이나 재사용이 가능하지 않습니다. 이 제공자를 재사용 가능하도록 만들려면 fopen을 생성자가 아닌 complete 메서드에서 호출하여 메시지에 사용되기 전의 상태로 제공자를 복원해야 합니다.

     classdef MyProvider < matlab.net.http.io.ContentProvider
        properties
            FileID double
            Name string
        end
 
        methods
            function obj = MyProvider(name)
                obj.Name = name;
            end
 
            function [data, stop] = getData(obj, length)
                ...as above...
            end
 
            function complete(obj, uri)
                obj.FileID = fopen(name);
                [e-mail]();
            end
 
            function tf = reusable(~)
                tf = true;
            end
            
            function delete(obj)
                ...as above...
            end
        end
      end

이 제공자를 재시작 가능하도록 만들려면 restartable 메서드와 start 메서드를 추가하고 start 메서드에서 fseek 함수를 실행하여 파일을 되돌리십시오.

            function start(obj)
                [e-mail]();
                fseek(obj.FileID, 0, -1);
            end
 
            function tf = restartable(~)
                tf = true;
            end

본문에 ContentProvider를 포함하는 RequestMessage에서 complete나 send를 호출하면 MATLAB은 자동 필드를 추가하기 전에 먼저 제공자의 Request 속성을 제공자가 배치된 RequestMessage로 설정하고 Header 속성을 Request의 헤더로 설정합니다. 그런 다음 아래와 같은 순서로 제공자에 있는 다음과 같은 메서드를 호출합니다.

• complete - 사용자가 RequestMessage.send나 RequestMessage.complete를 호출하면 메시지 완료 시에 호출됩니다. 메시지 완료 이벤트는 일반적으로 메시지당 한 번만 발생합니다. MATLAB에서는 제공자가 Header 속성을 해당 제공자의 메시지에 추가할 헤더 필드로 설정할 것으로 예상합니다. MATLAB이 이 메서드를 이후에 호출하면 제공자는 이 메서드가 새 메시지에 사용된다고 간주해야 합니다. 대부분의 제공자는 자신의 헤더를 추가하기 위해 이 메서드를 구현해야 하며, 제공자가 이 추상 클래스의 직접적인 서브클래스가 아닌 경우, 슈퍼클래스의 complete를 호출하여 추가적인 디폴트 동작을 호출해야 합니다. MATLAB은 제공자의 재사용 가능한 메서드가 true를 반환하지 않는 이상 제공자의 complete를 두 번 이상 호출하지 않습니다. 이 추상 클래스는 기본적으로 재사용 불가하지만, matlab.net.http.io 네임스페이스의 구체 제공자는 모두 재사용 가능합니다.

• preferredBufferSize/expectedContentLength - RequestMessage.send가 complete를 호출한 이후, 그리고 start를 호출하기 전 시점에 호출됩니다. 대부분의 제공자는 디폴트 동작만으로도 충분하기 때문에 이러한 메서드를 구현하지 않습니다. 단, 제공자는 force 인수를 지원하기 위해 이 메서드를 재정의할 수 있습니다.

이러한 메시지로부터 반환된 뒤에 MATLAB은 RequestMessage의 헤더를 서버로 전송합니다. 본문을 전송할 때가 되면 MATLAB은 이러한 메서드를 호출합니다.

• start - MATLAB이 서버가 요청 메시지의 본문을 수신할 준비가 되었다고 판단하면, 이전 메서드를 호출한 이후 시점에 RequestMessage.send에서 호출됩니다. MATLAB이 중간에 complete를 호출하지 않고 이 메서드를 한 번 더 호출하면 제공자는 동일한 헤더를 갖는 동일한 메시지의 본문을 다시 한번 전송하라는 요청을 받았다고 간주해야 합니다. MATLAB은 제공자의 restartable 메서드가 true를 반환하지 않는 이상 complete를 마지막으로 호출한 이후 start를 두 번 이상 호출하지 않습니다. 이 추상 클래스는 기본적으로 재시작 불가하지만, matlab.net.http.io 네임스페이스의 구체 제공자는 모두 재시작 가능합니다.

• getData - RequestMessage.send가 차단되어 있는 동안 MATLAB이 서버가 새 데이터 버퍼를 수신할 준비가 되었다고 판단할 때마다 start가 호출 이후에 여러 차례 호출됩니다. 이 메서드는 uint8 데이터로 구성된 벡터를 반환해야 합니다. 제공자는 stop 표시자를 반환하여 데이터의 끝부분에 도달했음을 알립니다. 모든 제공자는 이 메서드를 구현해야 합니다.

getData가 stop 표시자를 반환하면 MATLAB은 요청 메시지를 종료하고 서버의 응답을 기다립니다.

위임

RequestMessage.Body에 삽입된 ContentProvider는 메시지의 일부 또는 전체 데이터를 제공하는 작업을 하나 이상의 다른 제공자에게 위임할 수 있습니다. 예를 들어, MultipartProvider는 여러 파트로 이루어진 메시지를 생성하는데, 각 파트는 MultipartProvider 생성자에 지정된 다른 제공자에 의해 제공됩니다. 여기서 MultipartProvider는 위임 주체가 되고, 다른 제공자들은 대리자가 됩니다. 대리자들은 차례로 호출되어 자체 헤더 필드 및 데이터의 일부를 제공합니다.

제공자는 delegateTo를 호출하여 다른 제공자에게 작업을 위임합니다. 호출된 delegateTo 메서드는 CurrentDelegate를 대리자로 설정하고 대리자의 MyDelegator를 현재 제공자(즉, 위임 주체)로 설정한 다음, 해당 대리자의 complete 메서드와 start 메서드를 호출하고 GetDataFcn 함수 핸들을 반환합니다. 그런 다음 위임 주체의 getData 메서드가 대리자의 GetDataFcn을 호출하여 데이터를 받고, 수신한 데이터를 변경하거나 변경하지 않고 MATLAB에 반환합니다. 제공자는 일반적으로 자신이 대리자인지, 위임 주체가 누구인지 확인할 필요가 없습니다.

클래스 계층 구조

버전 내역

R2018a에 개발됨

참고 항목

RequestMessage | MessageBody | FileProvider | StringProvider | JSONProvider | ImageProvider | MultipartProvider | FormProvider | MultipartFormProvider | QueryParameter | ContentConsumer