요약
The XMLHttpRequest Object 규격은 서버와 클라이언트간 데이터를 전달하기 위한 스크립트화된 클라이언트 기능을 제공하는 API를 정의한다.
이 문서의 상태
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the 26 October 2007 Working Draft of The XMLHttpRequest Object specification. Please send comments to public-webapi@w3.org (archived) with either [XHR] or [XMLHttpRequest] at the start of the subject line.
This document is produced by the Web API Working Group, part of the Rich Web Clients Activity in the W3C Interaction Domain. Changes made to this document can be found in the W3C public CVS server.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
목차
1. 소개
이 절은 비규범적이다.
XMLHttpRequest object는 HTTP 클라이언트 인터페이스를 구현한다. 이 인터페이스는 스크립트 엔진을 통해 노출되며 폼 데이터를 보내거나 서버로부터 데이터를 받아오는 기능을 수행한다.
XMLHttpRequest라는 이름은 웹의 호환성을 위해 지어졌지만 이름의 각 부분은 잠재적으로 오해를 일으킬 수 있다. 첫째, XMLHttpRequest는 XML을 포함한 텍스트 기반의 어떠한 포맷도 지원한다. 둘째, XMLHttpRequest는 HTTP와 HTTPS 프로토콜 모두 사용할 수 있다. (몇몇 구현은 HTTP와 HTTPS 이외의 프로토콜을 지원하기도 하지만 그러한 기능은 본 규격에서는 다루지 않는다.). 마지막으로 XMLHttpRequest의 "request"는 HTTP에 정의된 용어에 비해 광의적으로 사용된다. 즉, HTTP method들을 위한 HTTP request와 response를 수행하기 위한 행위들을 포함한다.
1.1. 사용예
이 절은 비규범적이다.
몇몇 [ECMAScript] 예제들은 본 규격에 열거되었다. 추가로 아래 코드를 참고할 수 있다.
네트워크를 통해 전달된 XML 문서를 가지고 무엇인가를 하는 간단한 코드:
function test(data) { // taking care of data}function handler() { if(this.readyState == 4 && this.status == 200) { // so far so good if(this.responseXML != null && this.responseXML.getElementById('test').firstChild.data) // success! test(this.responseXML.getElementById('test').firstChild.data); else test(null); } else if (this.readyState == 4 && this.status != 200) { // fetched the wrong page or network error... test(null); }}var client = new XMLHttpRequest();client.onreadystatechange = handler;client.open("GET", "test.xml");client.send();
만약 서버에게 로그 메시지를 전달하고 싶다면:
function log(message) { var client = new XMLHttpRequest(); client.open("POST", "/log"); client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8"); client.send(message);}
만약 서버에 있는 문서의 상태를 확인하고 싶다면:
function fetchStatus(address) { var client = new XMLHttpRequest(); client.onreadystatechange = function() { // in case of network errors this might not give reliable results if(this.readyState == 4) returnStatus(this.status); } client.open("HEAD", address); client.send();}
다이어그램, 예제, 노트 그리고 비규범적이라고 명시된 절을 제외한 본 문서의 모든 부분은 규범적이다.
이 문서에서 사용된 must, must not, should 와 may 이라는 용어는 RFC 2119 [RFC2119]에 따라 해석된다.
본 규격은 다음과 같은 종류의 산출물을 정의한다.:
- 준수하는 유저 에이전트
유저 에이전트는 본 규격에 준수하기 위해 반드시(must) 이 규격에 정의된 대로 동작해야 한다.
만약 유저에이전트가 XML 유저에이전트에 준수하지 않는다면 XML response entity body는 반드시(must) 항상 null이어야 한다.
유저 에이전트는 본 규격에 정의된 알고리즘으로 얻을 수 있는 결과물과 구별 불가능한 결과물을 얻는 알고리즘을 구현할 수 있다. (may)
본 규격에서 사용하는 "준수하는 유저 에이전트(들)"와 "유저 에이전트(들)"는 이 종류의 산출물은 가르킨다.
- 준수하는 XML 유저 에이전트
준수하는 유저 에이전트이면서 동시에 namespace well-formed를 보고하는 준수하는 XML처리기인 유저 에이전트를 말한다.[XML] [XMLNS]
1.2.1. 의존성
본 규격은 몇몇 기초 규격에 기반을 두고 있다.
- DOM
준수하는 유저에이전트는 반드시(must) DOM Core와 DOM Events에 정의된 기능의 부분 집합을 지원해야한다. [DOM3Events] [DOM3Core]
이 규격이 의존하고 있는 반드시(must) Window Objects 1.0 규격에 정의된 기능의 부분 집합을 지원해야 한다. [Window ]
- HTTP
준수하는 유저에이전트는 반드시(must) 특정버전의 HTTP를 지원해야 한다. 꼭(should) Method형식에 맞는 HTTP method를 제공해야 하며, 반드시(must) 최소한 아래의 method들을 지원해야 한다.:
GET POST HEAD PUT DELETE OPTIONS
HTTP에 관한 다른 요구사항은 다음 문서에 정의되어 있다. [RFC2616]
1.2.2. 용어
s1 과 s2 문자열의 case-insensitive match는 두 문자열을 모두 대문자로 만들고 나서 (a-z를 A-Z로 매핑함으로써) 두 문자열이 동일함을 의미한다.
두 개의 URI는 RFC 3987에 정의된 sceheme-based normalization을 수행한 후에 scheme, ihost, port가 모두 동일 할 경우 same-origin 이라고 정의된다. 만약 URI가 두 URI 모두 ihost를 가지고 있지 않을 경우 반드시(must not) same-origin으로 간주되지 말아야 한다. [RFC3987]
1.2.3. 확장
본 규격에 정의된 API의 확장은 강력히 추천되지 않는다. 유저 에이전트들, 워킹 그룹, 그 밖에 관심있는 단체들은 반드시 이러한 확장을 public-webapi@w3.org 와 같은 공개적인 방법으로 논의 해야한다.
2. XMLHttpRequest 객체
XMLHttpRequest 객체는 스크립트에 의해 프로그램적으로 originating server에 접속할 수 있다.
XMLHttpRequest 인터페이스를 구현하는 객체는 반드시(must) EventTarget 인터페이스를 구현해야 한다. [DOM3Events]
Window 인터페이스를 구현하는 객체는 반드시(must) XMLHttpRequest() 생성자를 제공해야한다. [Window]
ECMAScript에서는 다음과 같이 쓰일 수 있다:
var client = new XMLHttpRequest();
XMLHttpRequest() 생성자가 호출될 경우 연관된 Window 객체에 대한 영속적인 포인터가 반드시(must) 새로 생성된 객체에 저장되어야 한다. 이것은 Window 포인터이다. 연관된 Window 객체는 XMLHttpRequest() 생성자가 호출된 것 중 하나이다. 이 포인터는 반드시(must) 해당 윈도우가 속해있는 브라우징 콘텍스트가 파괴된 경우에도 유지되어야 한다. (예를들면 부모 콘텍스트로 부터 제거하는 것과 같이).
브라우징 콘텍스트라는 용어는 Window Object 1.0 규격에 의해 정의된다. [Window]
만약 win이 Window 객체라면, client 는 아래 예제에서 win 에 대한 포인터를 가질 것이다:
var client = new win.XMLHttpRequest()
interface XMLHttpRequest { // event handler attribute EventListener onreadystatechange; // state const unsigned short UNSENT = 0; const unsigned short OPENED = 1; const unsigned short HEADERS_RECEIVED = 2; const unsigned short LOADING = 3; const unsigned short DONE = 4; readonly attribute unsigned short readyState; // request void open(in DOMString method, in DOMString url); void open(in DOMString method, in DOMString url, in boolean async); void open(in DOMString method, in DOMString url, in boolean async, in DOMString user); void open(in DOMString method, in DOMString url, in boolean async, in DOMString user, in DOMString password); void setRequestHeader(in DOMString header, in DOMString value); void send(); void send(in DOMString data); void send(in Document data); void abort(); // response DOMString getAllResponseHeaders(); DOMString getResponseHeader(in DOMString header); readonly attribute DOMString responseText; readonly attribute Document responseXML; readonly attribute unsigned short status; readonly attribute DOMString statusText;};XMLHttpRequest 객체는 다섯 가지 상태를 가질 수 있다: UNSENT, OPENED, HEADERS_RECEIVED, LOADING 그리고 DONE. 현재 상태는 readyState 속성에 의해 노출된다. 아래 정의된 방법이 언제 상태 전이가 일어나는지를 정의한다.
생성되었을 때, XMLHttpRequest객체는 반드시(must) UNSENT 상태여야 한다. 이 상태는 값이 0인 UNSENT 상수에 의해 표현된다.
OPENED 상태는 open() 메서드가 성공적으로 불렸을 때의 객체의 상태이다. 이 상태에서는 setRequestHeader()를 이용해 request 헤더를 설정할 수 있으며, send()를 통해 request를 할 수 있다. 이 상태는 값이 1인 OPENED 상수에 의해 표현된다.
OPENED 상태는 연관된 send() 플래그를 가지는데, "true" 또는 "false"의 값을 가진다. send() 플래그의 초기값은 "false"이다.
HEADERS_RECEIVED 상태는 모든 response 헤더가 받아진 객체의 상태이다. 이 상태는 값이 2인 상수에 의해 표현된다.
LOADING 상태는 response entity body가 받아지고 있는 중의 객체의 상태이다. 이 상태는 값이 3인 LOADING 상수에 의해 표현된다.
DONE 상태는 데이터의 전송이 끝나거나 전송 중 무한 리다이렉션 같은 오류가 발생한 객체의 상태이다. 이 상태는 값이 4인 DONE 상수에 의해 표현된다.
DONE는 연관된 error 플래그를 가지며 그 값은 "true" 또는 "false"이다. error 플래그의 초기값은 "false"이다.
response entity body는 현재까지 수신된 entity body의 일부이거나 (LOADING 상태), 완전한 entity body 이다. (DONE 상태). 만약 entity body가 없다면 response entity body 는 "null"이다.
text response entity body는 response entity body를 나타내는 DOMString이거나 null이다. Text response entity body는 다음과 같은 알고리즘의 리턴값이다:
만약 response entity body가 "null"이면, null을 리턴하고 종료한다.
charset을 "null"로 하자.
만약 Content-Type 헤더가 없거나 MIME type이 text/xml , application/xml이거나 +xml로 끝나는 Content-Type 헤더를 가졌다면 (파라메터는 무시한다), character encoding을 판별하기 위해 XML 규격에 설명되어 있는 방법을 사용한다. charset을 판별된 character encoding 값으로 한다.
만약 MIME type이 text/html인 Content-Type 헤더를 가졌다면, character encoding을 판별하기 위해 HTML 5 규격에 설명되어 있는 방법을 사용한다. charset을 판별된 character encoding 값으로 한다. [HTML5]
만약 Content-Type헤더에 지정된 MIME type이 파라메터를 가지고 있고, charset이 "null" 이라면 charset이 그 파라메터의 값으로 한다.
XML과 HTML 규격에 정의된 알고리즘은 이미 Content-Type 값을 참고한다.
만약 charset이 "null"이면, 아래 테이블의 각 행을 첫 줄부터 시작해서 대조하여 처음으로 첫번째 열과 일치하는 행의 두번째 컬럼 값을 charset의 값으로 한다. 만약 일치 하는 행이 없다면 charset 는 "null"로 남는다.
| 16진수 바이트열 | 설명 |
|---|
| 00 00 FE FF | UTF-32BE BOM |
| FF FE 00 00 | UTF-32LE BOM |
| FE FF | UTF-16BE BOM |
| FF FE | UTF-16LE BOM |
| EF BB BF | UTF-8 BOM |
만약 charset 이 "null"이면 charset를 UTF-8로 한다.
Response entity body를 charset를 이용해 디코딩 한 값을 리턴한다. 만약 실패한다면 null을 리턴한다.
XML response entity body는 response entity body를 나타내는 Document이거나 null이다. XML response entity body 는 다음과 같은 알고리즘의 리턴값이다:
만약 response entity body가 "null"이면, null을 리턴하고 종료한다.
만약 Content-Type 헤더가 존재하고 MIME type이 text/xml , application/xml이거나 +xml로 끝나는 Content-Type 헤더를 가지지 않았다면 (파라메터는 무시한다), null을 리턴하고 종료한다. (만약 Content-Type 가 전혀 없다면 종료하지 않는다.)
Response entity body를 XML 규격에 정의된 방법을 따라서 document tree로 파싱한다. parsed document의 값을 그 결과값으로 한다. 만약 지원되지 않는 character encoding이거나 namespace well-formedness 에러 등에 의해 실패한다면 null을 리턴하고 종료한다. [XML] [XMLNS ]
Document tree에 있는 스크립트는 실행되지 않으며, 여기서 참조된 리소스들도 로딩되지 않는다. 또한 연관된 XSLT도 적용되지 않는다.
parsed document값을 가지는 Document 인터페이스를 구현한 객체를 리턴한다.
onreadystatechange of type EventListener bubbling phase 동안readystatechange 이벤트가 전달될 경우 이 객체에 등록된 다른 적절한 이벤트 핸들러와 함께 반드시(must) 호출되어야 하는 EventListener를 값을 취하는 속성이다. 초기값은 반드시 (must) null이다.
readyState of type unsigned short, readonly 이 속성을 읽을 경우 반드시(must) 해당 객체의 현재 상태 값을 리턴해야 한다.
open(method, url, async, user, password), method 호출될 경우 유저 에이전트는 반드시(must) 다음 단계를 따라야 한다. (다른 방식으로 지시되지 않는 한):
만약 method인자가 RFC 2616의 5.1.1절에 정의된 Method 형식에 맞지 않은 경우 SYNTAX_ERR 예외를 발생하고 종료한다. [RFC2616]
만약 주어진 method 인자가 보안상의 이유로 지원되지 않을경우 유저 에이전트는 꼭(should) SECURITY_ERR 예외를 발생하고 종료해야 한다.
저장된 method값을 method로 한다.
만약 method가 GET, POST, HEAD, PUT, DELETE 또는 OPTIONS 와 case-insensitively match하다면 stored method에 이를 a-z를 A-Z로 매핑함으로써 대문자로 변환한 값을 저장한다.
url에 Fragment identifier가 있다면 이를 제외한 부분을 저장된 url값에 저장한다.
만약 저장된 url이 상대적 경로라면, Window포인터에 연관된 Document 객체의 현재 baseURI 속성을 이용해 해결한다. 만약 이것이 실패한다면 SYNTAX_ERR 예외를 발생시키고 종료한다.
만약 저장된 url이 지원되지 않는 scheme을 가졌을 경우, NOT_SUPPORTED_ERR 예외를 발생시키고 종료한다.
만약 "user:password" 형식의 userinfo 값이 해당 scheme에서 지원되지 않고, 저장된 url값에 이 형식이 존재한다면, SYNTAX_ERR 예외를 발생시키고 종료한다. [RFC3986]
만약 저장된 url 값이 "user:password" 형식을 가진다면 저장된 user 가 user 부분, 저장된 password 가 password 부분이 되도록한다.
만약 저장된 url 이 "user" 형식만 가진다면, 저장된 user값이 user 부분이 되도록 한다.
만약 저장된 url이 Window 포인터에 연관된 Document 객체와 same-origin이 아니라면, 유저 에이전트는 꼭(should) SECURITY_ERR예외를 발생시키고 종료해야 한다. 용어 origin은 HTML 5 규격에 의해 정의된다. [HTML5]
async 값을 async 인자의 값이 주어졌을 경우에는 그 값으로, 생략되었을 경우에는 true로 한다.
만약 user 인자가 주어졌고, 그 형식이 해당 인증 scheme에 적합하지 않은 경우, SYNTAX_ERR 예외를 발생시키고 종료한다.
만약 user 인자가 주어졌고 null이 아니라면 저장된 user 값을 해당 인증 scheme에 지정된 방법으로 인코딩한 값으로 한다. 만약 scheme에서 encoding이 지정되지 않은 경우에는 UTF-8로 인코딩 한 값으로 한다.
이 단계는 url 인자에 의해 지정된 user 값보다 우선 순위를 가진다.
만약 user 인자가 생략되지 않았고 null이라면 저장된 user 값을 지운다.
만약 password 인자가 주어졌고, 그 형식이 해당 인증 scheme에 적합하지 않은 경우, SYNTAX_ERR 예외를 발생시키고 종료한다.
만약 password 인자가 주어졌고 null이 아니라면 저장된 user 값을 해당 인증 scheme에 지정된 방법으로 인코딩한 값으로 한다. 만약 scheme에서 encoding이 지정되지 않은 경우에는 UTF-8로 인코딩 한 값으로 한다.
만약 password 인자가 생략되지 않았고 null이라면 저장된 password 값을 지운다.
send() 알고리즘을 취소하고, response entity body를 "null"로 하고, request header의 목록들을 리셋한다.
유저 에이전트는 꼭(should) 해당 객체가 수행하는 모든 네트워크 활동을 취소해야 한다.
객체의 상태를 OPENED 상태로 세팅하고, send()플래그 값을 "false"로 새팅한다. 그리고 동기적으로 readystatechange 이벤트를 해당 객체에 보내고, 메서드 호출을 리턴한다.
본 규격의 향후 버전 또는 확장은 cross-site request에 대한 방법을 정의할 가능성이 높다.
- , method
각각의 request는 연관된 값을 지닌 request header 목록을 가진다. 이 메서드는 그 값을 조작하거나 새로운 request header를 지정하는데 사용할 수 있다.
호출 될 경우, 유저 에이전트는 반드시(must) 다음 단계를 따라야한다. (다른 방법으로 지시되지 않았을 경우):
만약 객체의 상태가 OPENED 가 아닐 경우 INVALID_STATE_ERR 예외를 발생하고 종료한다.
만약 send()플래그가 "true"라면, INVALID_STATE_ERR 예외를 발생하고 종료한다.
만약 header 인자가 RFC 2616의 4.2절에 정의된 field-name 형식과 맞지 않거나 null 일 경우 SYNTAX_ERR 예외를 발생하고 종료한다. [RFC2616]
만약 value 인자가 null 이라면 종료한다. (예외를 발생시키지 않는다.)
만약 value 인자가 RFC 2616의 4.2절에 정의된 field-value 형식에 맞지 않는다면 SYNTAX_ERR 예외를 발생시키고 종료한다. [RFC2616]
만약 header 인자가 아래의 값 중 하나와 case-insensitively match한다면 꼭(should) 보안상의 이유로 종료되어야 한다:
Accept-Charset Accept-Encoding Connection Content-Length Content-Transfer-Encoding Date Expect Host Keep-Alive Referer TE Trailer Transfer-Encoding Upgrade Via
역시 보안상의 이유로 만약 header 인자의 첫 여섯글자가 Proxy-와 case-insensitively match 한다면 종료해야 한다.
만약 header 인자가 request header 목록에 없다면 연관된 value를 목록에 추가하고 종료한다.
만약 header 인자가 request header 목록에 있다면, 복수의 header를 사용하거나 값을 합치거나 그 두 개의 조합을 사용한다. (RFC 2616 4.2절) [RFC2616]
유저 에이전트가 캐싱, 인증, 프록시, 쿠키와 관련해서 header를 어떻게 다루는지 보려면 send() 메서드를 참조하다.
// 다음의 스크립트는:var client = new XMLHttpRequest();client.open('GET', 'demo.cgi');client.setRequestHeader('X-Test', 'one');client.setRequestHeader('X-Test', 'two');client.send();// ...아래와 같은 request header를 보내게 된다:...X-Test: one, two...
send(data), method send() 메서드는 요청을 시작하며, 이의 선택적 인자는 entity body를 제공한다. 저작자들은 send()를 null이 아닌 data 인자와 함께 호출하기 전에 setRequestHeader()로 Content-Type header를 지정 했는지 확인 하도록 강력히 권장된다.
호출될 경우 유저 에이전트는 반드시(must) 다음의 단계를 따라야 한다. (다른 방식으로 지정되지 않았을 경우). 이 알고라즘은 open() 또는 abort()메서드가 호출됨으로써 취소될 수 있다. send() 알고리즘이 중단될 경우에 유저 에이전트는 반드시(must) 현재 진행 중인 단계를 끝내고 종료해야 한다.
아래 알고리즘은 async가 false일 경우, 스크립트를 통해 중단될 수 없다. 오직 async가 true 이고 해당 메서드가 리턴한 이후에만 중단될 수 있다.
만약 객체의 상태가 OPENED 가 아니라면 INVALID_STATE_ERR 예외를 발생 시키고 종료한다.
만약 send()플래그가 "true"라면 INVALID_STATE_ERR 예외를 발생시키고 종료한다.
만약 async가 true라면 send()플래그를 "true"로 한다.
만약 data 인자가 생략되지 않았고, null이 아니라면 이 값을 RFC 2616의 7.2절에 정의된 대로 entity body 값으로 사용하되 다음의 규칙을 따른다. [RFC2616]
- data가
DOMString이다. 전송을 위해 data를 UTF-8로 인코딩한다.
- data가
Document이다. data를 namespace well-formed한 XML document로 직렬화(serialize)하고 data.xmlEncoding에서 주어진 값으로 인코딩한다. 만약 주어지지 않았을 경우 UTF-8로 인코딩한다. 만약 Document가 직렬화(serialize) 되지 못해서 실패한다면, data가 null인 것 처럼 동작한다.
만약 Content-Type 헤더가 request header 목록에 존재하지 않는다면, request header 목록에 application/xml를 값으로 Content-Type 헤더를 추가한다.
Document에 대한 이후의 변경은 전송되는 값에 영향을 미치지 않는다.
- data가
DOMString도 아니고, Document도 아니다. data의 호스트 언어에서 지정된 문자열화(stringification) 방법을 사용하고, data가 DOMString인 것처럼 동작한다. 만약 실패할 경우 data가 null인 것처럼 동작한다.
만약 data 인자가 생략되었거나, null이라면 이 요청에서 entity body가 사용되지 않는다.
이 단계 직후에 stored url에 stored method의 HTTP method, stored user의 user (만약 있다면), stored password의 password (만약 있다면), entity body와 request header 목록을 이용해 요청을 한다.
동기적으로 readystatechange 이벤트를 객체에 보낸다.
객체의 상태는 변경되지 않는다. 이 이벤트는 역사적인 이유로 보내지는 것이다.
만약 async 가 true 라면 send() 메서드 호출을 리턴한다. (하지만 이 알고리즘을 종료하지는 않는다.)
리소스가 다운로드 되는 동안 아래의 규칙이 적용된다.
- 만약 response가 HTTP redirect라면
만약 redirect가 보안상의 문제 점이 없고, (예를 들면 same-origin이라면) 무한 루프에 빠질 위험이 없다면 그 scheme은 투명하게(transparently) 지원되며, redirect를 따라간 후 이 단계 맨 처음으로 돌아한다.
HTTP는 유저에이턴트가 redirect 하는 동안 request method와 entity body를 유지하도록 요구한다. 또한 이러한 자동 redirection이 사용자에게 알려지도록 요구한다.
그렇지 않다면 다음의 단계를 따른다:
response entity body를 "null"로 세팅하고 error flag를 "true"로 하고 request header 목록을 리셋한다.
동기적으로 객체의 상태를 DONE으로 전환한다.
만약 async 가 false 라면 NETWORK_ERR 예외를 발생시키고 전체 알고리즘을 종료한다.
동기적으로 readystatechange 이벤트를 객체에 보낸다.
전체 알고리즘을 종료한다.
향후 버전의 XMLHttpRequest 객체는 여기에서도 error 이벤트를 보내게 될 가능성이 높다.
- 만약 사용자가 다운로드를 취소한다면
다음 단계를 수행한다:
response entity body를 "null"로 세팅하고 error flag를 "true"로 하고 request header 목록을 리셋한다.
동기적으로 객체의 상태를 DONE으로 전환한다.
만약 async 가 false 라면 ABORT_ERR 예외를 발생시키고 전체 알고리즘을 종료한다.
동기적으로 readystatechange 이벤트를 객체에 보낸다.
전체 알고리즘을 종료한다.
향후 버전의 XMLHttpRequest 객체는 여기에서도 abort 이벤트를 보내게 될 가능성이 높다.
- 네트워크 에러가 발생한 경우라면
DNS 에러 또는 다른 종류의 네트워크 에러의 경우 다음의 단계를 수행한다. 여기에는 HTTP status code 410과 같은 어떤 종류의 에러를 나타내는 HTTP response를 포함하지 않는다.
response entity body를 "null"로 세팅하고 error flag를 "true"로 하고 request header 목록을 리셋한다.
동기적으로 객체의 상태를 DONE으로 전환한다.
만약 async 가 false 라면 NETWORK_ERR 예외를 발생시키고 전체 알고리즘을 종료한다.
동기적으로 readystatechange 이벤트를 객체에 보낸다.
전체 알고리즘을 종료한다.
향후 버전의 XMLHttpRequest 객체는 여기에서도 error 이벤트를 보내게 될 가능성이 높다.
- 만약 모든 HTTP 헤더들을 수신했다면
message body(있다면)를 수신하기 전에 만약 모든 HTTP header들을 수신했다면 다음 단계를 따른다:
동기적으로 객체의 상태를 HEADERS_RECEIVED으로 전환한다.
동기적으로 readystatechange 이벤트를 객체에 보낸다.
- 만약 response entity body의 첫 바이트 (또는 더 많은 바이트)를 수신했다면
- 만약 response entity body가 없다면
만약 response entity body의 첫 바이트 (또는 더 많은 바이트)를 수신했거나 response entity body가 없다면 다음의 단계를 따른다:
동기적으로 객체의 상태를 LOADING으로 전환한다.
동기적으로 readystatechange 이벤트를 객체에 보낸다.
마지막으로, 리소스의 다운로드가 완료되면 다음 단계로 이동한다.
해당 요청이 로딩을 성공적으로 끝내면, 동기적으로 상태를 DONE로 전환하고, 동기적으로 readystatechange 이벤트를 객체에 보낸다. 만약 async가 false라면 이 메서드를 리턴한다.
만약 유저 에이전트가 사용자가 프록시를 설정할 수 있도록 허용한다면 꼭(should) 적절히 요청을 수정해야 한다; 즉, origin server 대신 proxy host에 접속하고, Request-Line을 수정하며 Proxy-Authorization 헤더를 지정된 대로 보내야 한다.
만약 유저 에이전트가 HTTP 인증을 지원한다면 꼭(should) 이 객체로부터 발생한 request에 대해 보호된 영역으로 간주해야 한다. 즉, accessed URI를 포함하고 Authorization 헤더를 보내며 401 Unauthorized 요청을 적절히 처리해야한다. 만약 인증이 실패할 경우, 유저 에이전트는 꼭(should) 사용자에게 자격(credentials)에 대해 물어야 한다. [RFC2617]
만약 유저 에이전트가 HTTP State Management를 지원한다면 꼭(should) 적절히 쿠키를 저장하고, 제거하고, 보내야 한다. (Set-Cookie와 Set-Cookie2 response 헤더에 의해 받아지고, Cookie헤더에 의해 보내진다.) [RFC2965]
만약 유저 에이전트가 HTTP cache를 구현한다면 꼭(should) Cache-Control request 헤러들 준수해야 한다. (예, Cache-Control: no-cache는 cache를 사용하지 않는다.) 유저 에이전트는 사용자에 의해 명시적으로 요청된 경우가 아니라면 Cache-Control이나 Pragma헤더를 자동으로 보내서는 안된다(must not). (예, (강제로-)페이지를 Reloading할 경우). 유저 에이전트의 조건 요청에 따른 304 Not Modified response는 반드시(must) 적절한 콘텐트로 200 OK response처럼 보여져야 한다. 유저 에이전트는 304 Not Modified가 반드시(must) 전달되어야 할때 반드시(must) If-None-Match, If-Modified-Since와 같은 request header를 설정함으로써 자동 캐시 검증 방법보다 높은 우선 순위의 검증 방법을 제공할 수 있어야한다. [RFC2616]
만약 유저 에이전트가 서버 기반 content-nogotiation을 구현한다면 꼭(should) Accept-Language, Accept-Encoding와 Accept-Charset 헤더를 적절히 세팅해야한다; 자동으로 Accept 헤더를 세팅해서는 안된다(must not). 이러한 request에 대한 response에는 자동으로 디코딩된 content-encoding 들이 반드시must있어야 한다. [RFC2616]
abort(), method 호출될 경우 유저 에이전트는 반드시(must) 다음의 단계를 수행해야한다. (다른 방법으로 지시되지 않을 경우):
send()알고리즘을 취소하고, response entity body를 "null"로 세팅하고, error flag를 "true"로 한 뒤 등록된 모든 request header들을 제거한다.
유저 에이전트는 꼭(should) 해당 객체가 수행하는 모든 네트워크 활동을 취소해야 한다.
만약 상태가 UNSENT 또는 OPENED 이고 send()플래그 가 "false"이거나, 상태가 DONE 히면 다음 단계로 간다.
그렇지 않을 경우 상태를 DONE으로 바꾸고, send()플래그를 "false"로 한 뒤, 동기적으로 객체에게 readystatechange 이벤트를 보낸다.
객체 상태를 UNSENT로 바꾼다. (readystatechange 이벤트를 발생시키지는 않는다.)
향후 버전의 XMLHttpRequest 객체는 여기에서도 abort 이벤트를 발생시킬 가능성이 높다.
- , method
호출될 경우 유저 에이전트는 반드시(must) 다음의 단계를 수행해야한다:
만약 상태가 UNSENT 또는OPENED라면 INVALID_STATE_ERR 예외를 발생시키고 종료한다.
만약 error flag 가 "true" 라면, null을 리턴하고 종료한다.
모든 HTTP 헤더를 리턴한다. 이는 단일 문자열로 이루어지며 각각의 헤더 라인은 상태 라인을 제외하고는 U+000D CR U+000A LF 짝으로 분리된다.
// 아래의 스크립트는:var client = new XMLHttpRequest();client.open("GET", "test.txt", true);client.send();client.onreadystatechange = function() { if(this.readyState == 3) { print(this.getAllResponseHeaders()); }}// ...다음과 유사한 텍스트를 출력해야 한다:Date: Sun, 24 Oct 2004 04:58:38 GMTServer: Apache/1.3.31 (Unix)Keep-Alive: timeout=15, max=99Connection: Keep-AliveTransfer-Encoding: chunkedContent-Type: text/plain; charset=utf-8
- , method
호출될 경우 유저 에이전트는 반드시(must) 다음의 단계를 수행해야한다:
만약 상태가 UNSENT 또는 OPENED라면 INVALID_STATE_ERR 예외를 발생시키고 종료한다.
만약 header 인자가 field-name형식에 맞지 않는 다면 빈 문자열을 리턴하고 종료한다.
만약 error 플래그 가 "true"라면 null을 리턴하고 종료한다.
만약 header 인자가 마지막으로 보낸 request의 헤더들 중 여러 개와 case-insensitively match 한다면, 이 헤더들의 값을 U+002C COMMA와 그 뒤에 U+0020 SPACE로 구별되는 한 개의 문자열로 합쳐서 리턴하고 종료한다.
만약 header 인자가 마지막으로 보낸 request의 헤더들 중 한 개와 case-insensitively match 한다면, 이 헤더의 값 리턴하고 종료한다.
null을 리턴한다.
// 아래의 스크립트는:var client = new XMLHttpRequest();client.open("GET", "test.txt", true);client.send();client.onreadystatechange = function() { if(this.readyState == 3) { print(client.getResponseHeader("Content-Type")); }}// ...다음과 같은 문자열을 출력해야 한다:Content-Type: text/plain; charset=utf-8
responseText of type DOMString, readonly 얻을때, 유저 에이전트는 반드시(must) 다음과 같은 단계를 수행해야 한다:
만약 상태가 LOADING 또는 DONE이 아니라면 INVALID_STATE_ERR 예외를 발생시키고 종료한다.
text response entity body를 리턴한다.
responseXML of type Document, readonly 얻을때, 유저 에이전트는 반드시(must) 다음과 같은 단계를 수행해야 한다:
만약 상태가 DONE이 아니라면 INVALID_STATE_ERR 예외를 발생시키고 종료한다.
XML response entity body를 리턴한다.
status of type unsigned short, readonly 얻을때, 존재한다면 이는 반드시(must) 서버에서 보내진 HTTP status code를 리턴해야 한다. (보통 성공적인 요청에 대해서는 200 이다). 존재하지 않는 다면 유저 에이전트는 반드시(must) INVALID_STATE_ERR 예외를 발생시켜야 한다.
statusText of type DOMString, readonly 얻을때, 존재한다면 이는 반드시(must) 서버에서 보내진 HTTP status text를 리턴해야 한다. (status code 바로 뒤에 있다). 존재하지 않는다면 유저 에이전트는 반드시(must) INVALID_STATE_ERR 예외를 발생시켜야 한다.
2.1. XMLHttpRequest 객체의 이벤트
이 절은 XMLHttpRequest 인터페이스를 구현한 객체가 보내는 다양한 이벤트에 대해 설명한다. 이 버전의 규격에서는 한 개의 이벤트만 정의되어 있다.
readystatechange - 유저 에이전트가
readystatechange 이벤트를 발생시킬 경우에는 (위에서 지시된바와 같이) bubble 하지 말아야 하며(must not), cancelable 하지 않아야 하고(must not), 반드시(must) Event 인터페이스를 구현해야한다. 이의 namespaceURI 속성은 반드시(must) null이어야 한다. [DOM3Events]
2.2. XMLHttpRequest 객체의 예외
이 규격에서 정의된 몇몇 알고리즘은 예외를 발생시킬 수 있다. 이 예외들은 모두 DOM Level 3 Core에서 정의된 ExceptionCode의 일부이며 DOMException 객체를 사용한다. 여기에 더해 본 규격에서는 ExceptionCode 에 아래와 같은 새로운 상수들을 정의한다. [DOM3Core]
const unsigned short SECURITY_ERR = 18;const unsigned short NETWORK_ERR = 101;const unsigned short ABORT_ERR = 102;
SECURITY_ERR 예외는 유저 에이전트의 보안 정책에 위배되거나 보안상의 위험이 있는 방식으로 동작을 수행하거나 데이터에 접근할 경우 발생한다.
SECURITY_ERR 예외는 궁극적으로 DOM Level 3 Core 규격의 향후 버전에 동일한 정의와 상수값으로 포함되어야 한다. 그 때까지 구현자에 대한 가이드로서 여기에 정의된다. (이것은 다른 예외들과 다른 상수값을 가지는 이유이기도 하다.)
NETWORK_ERR 예외는 동기적인 요청에서 네트워크 에러가 생겼을때 발생한다.
ABORT_ERR 예외는 동기적인 요청에서 사용자가 요청을 취소했을 때 발생한다.
본 규격에 정의되지 않은 것들
이 절은 비규범적이다.
본 규격은 향후 버전의 규격에서 고려되고 있는 다음과 같은 기능들을 포함하지 않는다:
load 이벤트와 onload 속성; error 이벤트와 onerror 속성; progress 이벤트와 onprogress 속성; abort 이벤트와 onabort 속성; - 타이머가 제안되었으며,
ontimeout 속성이 고려 중; - redirect를 막는 속성;
text/html 문서에 대한 responseXML; - Cross-site
XMLHttpRequest; - 바이트 스트립을 다루기위한
responseBody; - MIME 타입을 수정하기 위한
overrideMimeType; getRequestHeader()와 removeRequestHeader().
참조
- [DOM3Core]
- Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. W3C, April 2004.
- [DOM3Events]
- Document Object Model (DOM) Level 3 Events Specification (work in progress), Björn Höhrmann, editor. W3C, April 2006.
- [ECMAScript]
- ECMAScript Language Specification, Third Edition. ECMA, December 1999.
- [HTML5]
- HTML 5 (work in progress), Ian Hickson, editor. WHATWG, 2007.
- [RFC2119]
- Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
- [RFC2616]
- Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, editors. IETF, June 1999.
- [RFC2617]
- HTTP Authentication: Basic and Digest Access Authentication, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart, editors. IETF, June 1999.
- [RFC2965]
- HTTP State Management Mechanism, D. Kristol, L. Montulli, editors. IETF, October 2000.
- [RFC3986]
- Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, editors. IETF, January 2005.
- [RFC3987]
- Internationalized Resource Identifiers (IRIs), M. Duerst, M. Suignard, editors. IETF, January 2005.
- [Window]
- Window Object 1.0 (work in progress), I. Davis, M. Stachowiak, editors. W3C, April 2006.
- [XML]
- Extensible Markup Language (XML) 1.0 (Fourth Edition), T. Bray, J. Paoli, C. Sperberg-McQueen, E. Maler, F. Yergeau, editors. W3C, September 2006.
- [XMLNS]
- Namespaces in XML (Second Edition), T. Bray, D. Hollander, A. Layman, R. Tobin, editors. W3C, August 2006.
감사의 말
이 절은 비규범적이다.
The editor would like to thank to the following people who have contributed to this specification (ordered by first name):
- Ahmed Kamel
- Alex Hopmann
- Alex Vincent
- Alexey Proskuryakov
- Asbjørn Ulsberg
- Boris Zbarsky
- Björn Höhrmann
- Cameron McCormack
- Christophe Jolif
- Charles McCathieNevile
- Dan Winship
- David Håsäther
- Dean Jackson
- Denis Sureau
- Doug Schepers
- Douglas Livingstone
- Elliotte Harold
- Eric Lawrence
- Gideon Cohn
- Gorm Haug Eriksen
- Hallvord R. M. Steen
- Håkon Wium Lie
- Ian Davis
- Ian Hickson
- Ivan Herman
- Jeff Walden
- Jens Lindström
- Jim Deegan
- Jim Ley
- Joe Farro
- Jonas Sicking
- Julian Reschke
- Karl Dubost
- Maciej Stachowiak
- Magnus Kristiansen
- Marc Hadley
- Marcos Caceres
- Mark Baker
- Mark Nottingham
- Mohamed Zergaoui
- Pawel Glowacki
- Robin Berjon
- Ruud Steltenpool
- Simon Pieters
- Stewart Brodie
- Sunava Dutta
- Zhenbin Xu
Special thanks to the Microsoft employees who first implemented the XMLHttpRequest interface, which was first widely deployed by the Windows Internet Explorer browser.
Special thanks also to the WHATWG for drafting an initial version of this specification in their Web Applications 1.0 document (now renamed to HTML 5). [HTML5]
Thanks also to all those who have helped to improve this specification by sending suggestions and corrections. (Please, keep bugging us with your issues!)
