Skip to content

Commit

Permalink
Editorial: cleanup exception terminology
Browse files Browse the repository at this point in the history 
Fixes #173.
  • Loading branch information
@annevk
annevk authored Apr 10, 2018
1 parent 67a423f commit 4b7915e
Showing 1 changed file with 83 additions and 138 deletions.
221 changes: 83 additions & 138 deletions xhr.bs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -403,28 +403,23 @@ turn causes the <a>use-CORS-preflight flag</a> to be set.)
<p>Sets the <a>request method</a>, <a>request URL</a>, and
<a>synchronous flag</a>.

<p>Throws a <code>SyntaxError</code> exception if
either <var>method</var> is not a valid HTTP method or
<var>url</var> cannot be parsed.

<p>Throws a <code>SecurityError</code> exception
if <var>method</var> is a case-insensitive match for
`<code>CONNECT</code>`, `<code>TRACE</code>` or `<code>TRACK</code>`.

<p>Throws an <code>InvalidAccessError</code> exception if <var>async</var> is false,
<a>current global object</a> is a {{Window}}
object, and the {{XMLHttpRequest/timeout!!attribute}} attribute is not zero or the
{{XMLHttpRequest/responseType}} attribute is not the empty string.
<p>Throws a "{{SyntaxError!!exception}}" {{DOMException}} if either <var>method</var> is not a
valid HTTP method or <var>url</var> cannot be parsed.

<p>Throws a "{{SecurityError!!exception}}" {{DOMException}} if <var>method</var> is a
case-insensitive match for `<code>CONNECT</code>`, `<code>TRACE</code>`, or `<code>TRACK</code>`.

<p>Throws an "{{InvalidAccessError!!exception}}" {{DOMException}} if <var>async</var> is false,
<a>current global object</a> is a {{Window}} object, and the {{XMLHttpRequest/timeout!!attribute}}
attribute is not zero or the {{XMLHttpRequest/responseType}} attribute is not the empty string.
</dl>

<p class="critical no-backref" id=sync-warning>Synchronous {{XMLHttpRequest}}
outside of workers is in the process of being removed from the web platform as it has
detrimental effects to the end user's experience. (This is a long process that takes many
years.) Developers must not pass false for the <var>async</var> argument when
<a>current global object</a> is a {{Window}}
object. User agents are strongly encouraged to warn about such usage in developer tools and may
experiment with <a lt=throw>throwing</a> an
<code>InvalidAccessError</code> exception when it occurs.
<p class="critical no-backref" id=sync-warning>Synchronous {{XMLHttpRequest}} outside of workers is
in the process of being removed from the web platform as it has detrimental effects to the end
user's experience. (This is a long process that takes many years.) Developers must not pass false
for the <var>async</var> argument when <a>current global object</a> is a {{Window}} object. User
agents are strongly encouraged to warn about such usage in developer tools and may experiment with
<a lt=throw>throwing</a> an "{{InvalidAccessError!!exception}}" {{DOMException}} when it occurs.

<p>The
<dfn id=dom-xmlhttprequest-open method for=XMLHttpRequest><code>open(<var>method</var>, <var>url</var>)</code></dfn>
Expand Down Expand Up @@ -525,16 +520,13 @@ the editing software used to write the XMLHttpRequest Standard.
<dt><code><var>client</var> . <a method for=XMLHttpRequest>setRequestHeader(<var>name</var>, <var>value</var>)</a></code>

<dd>
<p>Combines a <a>header</a> in
<a>author request headers</a>.
<p>Combines a <a>header</a> in <a>author request headers</a>.

<p>Throws an <code>InvalidStateError</code>
exception if either <a>state</a> is not
<p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if either <a>state</a> is not
<i>opened</i> or the <a><code>send()</code> flag</a> is set.

<p>Throws a <code>SyntaxError</code> exception if
<var>name</var> is not a header name or if <var>value</var> is not a header value.

<p>Throws a "{{SyntaxError!!exception}}" {{DOMException}} if <var>name</var> is not a header name
or if <var>value</var> is not a header value.
</dl>

<p class=note>As indicated in the algorithm below certain headers cannot
Expand All @@ -548,25 +540,19 @@ the author as indicated at the end of the
method must run these steps:

<ol>
<li><p>If <a>state</a> is not
<i>opened</i>, <a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If <a>state</a> is not <i>opened</i>, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>If the <a><code>send()</code> flag</a> is set,
<a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If the <a><code>send()</code> flag</a> is set, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p><a for=header/value>Normalize</a> <var>value</var>.

<li>
<p>If <var>name</var> is not a
<a for=header>name</a> or <var>value</var>
is not a <a for=header>value</a>,
<a>throw</a> a
<code>SyntaxError</code> exception.

<p class="note no-backref">An empty byte sequence represents an empty
<a>header</a>
<p>If <var>name</var> is not a <a for=header>name</a> or <var>value</var> is not a
<a for=header>value</a>, then <a>throw</a> a "{{SyntaxError!!exception}}" {{DOMException}}.

<p class="note no-backref">An empty byte sequence represents an empty <a>header</a>
<a for=header>value</a>.

<li><p>Terminate these steps if <var>name</var> is a
Expand Down Expand Up @@ -598,21 +584,15 @@ client.send();
<dl class=domintro>
<dt><code><var>client</var> . <a attribute for=XMLHttpRequest>timeout</a></code>
<dd>
<p>Can be set to a time in milliseconds. When set to a non-zero value
will cause <a for=/>fetching</a> to
terminate after the given time has passed. When the time has passed, the request has
not yet completed, and the <a>synchronous flag</a> is unset, a
<a event><code>timeout</code></a> event will then be
<a>dispatched</a>,
or a <code>TimeoutError</code> exception will be
<a lt=throw>thrown</a> otherwise
(for the <a><code>send()</code></a> method).
<p>When set: throws an
<code>InvalidAccessError</code> exception if
the <a>synchronous flag</a> is set and
<a>current global object</a> is a {{Window}}
object.

<p>Can be set to a time in milliseconds. When set to a non-zero value will cause
<a for=/>fetching</a> to terminate after the given time has passed. When the time has passed, the
request has not yet completed, and the <a>synchronous flag</a> is unset, a
<a event><code>timeout</code></a> event will then be <a>dispatched</a>, or a
"{{TimeoutError!!exception}}" {{DOMException}} will be <a lt=throw>thrown</a> otherwise (for the
<a><code>send()</code></a> method).

<p>When set: throws an "{{InvalidAccessError!!exception}}" {{DOMException}} if the
<a>synchronous flag</a> is set and <a>current global object</a> is a {{Window}} object.
</dl>

<p>The <dfn attribute for=XMLHttpRequest><code>timeout</code></dfn>
Expand All @@ -622,10 +602,8 @@ attribute must return its value. Initially its value must be zero.
attribute must run these steps:

<ol>
<li><p>If <a>current global object</a> is a {{Window}}
object and the <a>synchronous flag</a> is set,
<a>throw</a> an
<code>InvalidAccessError</code> exception.
<li><p>If <a>current global object</a> is a {{Window}} object and the <a>synchronous flag</a> is
set, then <a>throw</a> an "{{InvalidAccessError!!exception}}" {{DOMException}}.

<li><p>Set its value to the new value.
</ol>
Expand All @@ -646,11 +624,8 @@ of <a for=/>fetching</a>.
to be excluded in a cross-origin request and when cookies are to be ignored in its response.
Initially false.

<p>When set: throws an
<code>InvalidStateError</code> exception if
<a>state</a> is not <i>unsent</i> or
<i>opened</i>, or if the <a><code>send()</code> flag</a> is set.

<p>When set: throws an "{{InvalidStateError!!exception}}" {{DOMException}} if <a>state</a> is not
<i>unsent</i> or <i>opened</i>, or if the <a><code>send()</code> flag</a> is set.
</dl>

<p>The
Expand All @@ -662,14 +637,11 @@ attribute must return its value. Initially its value must be false.
attribute must run these steps:

<ol>
<li><p>If <a>state</a> is not
<i>unsent</i> or <i>opened</i>,
<a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If <a>state</a> is not <i>unsent</i> or <i>opened</i>, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>If the <a><code>send()</code> flag</a> is set,
<a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If the <a><code>send()</code> flag</a> is set, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>Set the {{XMLHttpRequest/withCredentials}}
attribute's value to the given value.
Expand Down Expand Up @@ -702,29 +674,26 @@ object has an associated {{XMLHttpRequestUpload}} object.
<h4 id=the-send()-method>The <code>send()</code> method</h4>

<dl class=domintro>
<dt><code><var>client</var> . <a method for=XMLHttpRequest>send([<var>body</var> = null])</a></code>
<dt><code><var>client</var> . <a method for=XMLHttpRequest lt="send(body)">send([<var>body</var> = null])</a></code>
<dd>
<p>Initiates the request. The optional argument provides the
<a>request body</a>. The argument is ignored if
<a>request method</a> is <code>GET</code> or
<code>HEAD</code>.

<p>Throws an <code>InvalidStateError</code> exception if either
<a>state</a> is not <i>opened</i> or the
<a><code>send()</code> flag</a> is set.
<p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if either <a>state</a> is not
<i>opened</i> or the <a><code>send()</code> flag</a> is set.
</dl>

<p>The <dfn method for=XMLHttpRequest><code>send(<var>body</var>)</code></dfn>
method must run these steps:

<ol>
<li><p>If <a>state</a> is not
<i>opened</i>, <a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If <a>state</a> is not <i>opened</i>, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>If the <a><code>send()</code> flag</a> is set,
<a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If the <a><code>send()</code> flag</a> is set, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>If the <a>request method</a> is <code>GET</code> or
<code>HEAD</code>, set <var>body</var> to null.
Expand Down Expand Up @@ -1080,13 +1049,12 @@ method must run these steps:
<ol>
<li><p>If the <a><code>send()</code> flag</a> is unset, return.

<li><p>If <var>response</var> is a
<a>network error</a>, run the
<a>request error steps</a> for event <a event><code>error</code></a> and
exception <code>NetworkError</code>.
<li><p>If <var>response</var> is a <a>network error</a>, then run the <a>request error steps</a>
for event <a event><code>error</code></a> and exception "{{NetworkError!!exception}}"
{{DOMException}}.

<li><p>If the <a>timed out flag</a> is set, then run the <a>request error steps</a> for event
<a event><code>timeout</code></a> and exception <code>TimeoutError</code>.
<a event><code>timeout</code></a> and exception "{{TimeoutError!!exception}}" {{DOMException}}.

<li>
<p>Otherwise, if <var>response</var>'s <a for=response>body</a>'s <a for=body>stream</a> is
Expand All @@ -1102,7 +1070,7 @@ method must run these steps:

<li><p>Otherwise, if <var>response</var>'s <a for=response>aborted flag</a> is set, then run the
<a>request error steps</a> for event <a event><code>abort</code></a> and exception
<code>AbortError</code>.
"{{AbortError!!exception}}" {{DOMException}}.
</ol>

<p>The <dfn>request error steps</dfn> for event <var>event</var> and optionally an
Expand Down Expand Up @@ -1491,20 +1459,17 @@ resources using <a>utf-8</a>.
<dd>
<p>Acts as if the `<code>Content-Type</code>` header for <a>response</a> is <var>mime</var>.

<p>Throws an <code>InvalidStateError</code> exception if
<a>state</a> is
<i>loading</i> or <i>done</i>.
<p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if <a>state</a> is <i>loading</i>
or <i>done</i>.
</dl>

<p>The
<dfn method for=XMLHttpRequest><code>overrideMimeType(<var>mime</var>)</code></dfn>
method must run these steps:

<ol>
<li><p>If <a>state</a> is
<i>loading</i> or <i>done</i>,
<a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If <a>state</a> is <i>loading</i> or <i>done</i>, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>Set <a>override MIME type</a> to `<code>application/octet-stream</code>`.

Expand Down Expand Up @@ -1535,15 +1500,12 @@ method must run these steps:
<p>When set: setting to "<code>document</code>" is ignored if
<a>current global object</a> is <em>not</em> a
{{Window}} object.
<p>When set: throws an
<code>InvalidStateError</code> exception if
<a>state</a> is <i>loading</i> or
<i>done</i>.
<p>When set: throws an
<code>InvalidAccessError</code> exception if the
<a>synchronous flag</a> is set and
<a>current global object</a> is a {{Window}}
object.

<p>When set: throws an "{{InvalidStateError!!exception}}" {{DOMException}} if <a>state</a> is
<i>loading</i> or <i>done</i>.

<p>When set: throws an "{{InvalidAccessError!!exception}}" {{DOMException}} if the
<a>synchronous flag</a> is set and <a>current global object</a> is a {{Window}} object.
</dl>


Expand All @@ -1561,15 +1523,11 @@ attribute must run these steps:
{{Window}} object and the given value is
"<code>document</code>", terminate these steps.

<li><p>If <a>state</a> is
<i>loading</i> or <i>done</i>,
<a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If <a>state</a> is <i>loading</i> or <i>done</i>, then <a>throw</a> an
"{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>If <a>current global object</a> is a {{Window}}
object and the <a>synchronous flag</a> is set,
<a>throw</a> an
<code>InvalidAccessError</code> exception.
<li><p>If <a>current global object</a> is a {{Window}} object and the <a>synchronous flag</a> is
set, then <a>throw</a> an "{{InvalidAccessError!!exception}}" {{DOMException}}.

<li><p>Set the
{{XMLHttpRequest/responseType}}
Expand Down Expand Up @@ -1647,10 +1605,8 @@ steps:
<dd>
<p>Returns the <a>text response</a>.

<p>Throws an <code>InvalidStateError</code>
exception if
{{XMLHttpRequest/responseType}} is not
the empty string or "<code>text</code>".
<p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if
{{XMLHttpRequest/responseType}} is not the empty string or "<code>text</code>".
</dl>

<p>The
Expand All @@ -1659,15 +1615,10 @@ attribute must return the result of running these
steps:

<ol>
<li><p>If {{XMLHttpRequest/responseType}} is not the empty string or "<code>text</code>", then
<a>throw</a> an "{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>If {{XMLHttpRequest/responseType}} is not the
empty string or "<code>text</code>",
<a>throw</a> an
<code>InvalidStateError</code> exception.


<li><p>If <a>state</a> is not
<i>loading</i> or <i>done</i>, return the empty string.
<li><p>If <a>state</a> is not <i>loading</i> or <i>done</i>, then return the empty string.

<li><p>Return the <a>text response</a>.
</ol>
Expand All @@ -1680,27 +1631,22 @@ steps:
<dd>
<p>Returns the <a>document response</a>.

<p>Throws an <code>InvalidStateError</code>
exception if
{{XMLHttpRequest/responseType}} is not
the empty string or "<code>document</code>".
<p>Throws an "{{InvalidStateError!!exception}}" {{DOMException}} if
{{XMLHttpRequest/responseType}} is not the empty string or "<code>document</code>".
</dl>

<p>The
<dfn attribute for=XMLHttpRequest><code>responseXML</code></dfn>
attribute must return the result of running these steps:

<ol>
<li><p>If
{{XMLHttpRequest/responseType}} is not
the empty string or "<code>document</code>",
<a>throw</a> an
<code>InvalidStateError</code> exception.
<li><p>If {{XMLHttpRequest/responseType}} is not the empty string or "<code>document</code>", then
<a>throw</a> an "{{InvalidStateError!!exception}}" {{DOMException}}.

<li><p>If <a>state</a> is not <i>done</i>,
return null.
<li><p>If <a>state</a> is not <i>done</i>, then return null.

<li><p>Assert: <a>response object</a> is not failure.

<!-- Assert: response object is not failure -->
<li><p>If <a>response object</a> is non-null, then return it.

<li><p>Return the <a>document response</a>.
Expand All @@ -1714,8 +1660,7 @@ reasons. It also returns HTML resources as <a for=/>documents</a>.

<p><em>This section is non-normative.</em>

<p>The following events are dispatched on {{XMLHttpRequest}}
and/or {{XMLHttpRequestUpload}} objects:
<p>The following events are dispatched on {{XMLHttpRequest}} or {{XMLHttpRequestUpload}} objects:

<table>
<thead>
Expand Down

0 comments on commit 4b7915e

Please sign in to comment.