[html5] r2352 - [gwr] (2) Appcache: Change the approach used for the dynamic entries API so that [...]
whatwg at whatwg.org
whatwg at whatwg.org
Fri Oct 17 18:28:19 PDT 2008
Author: ianh
Date: 2008-10-17 18:28:18 -0700 (Fri, 17 Oct 2008)
New Revision: 2352
Modified:
index
source
Log:
[gwr] (2) Appcache: Change the approach used for the dynamic entries API so that it makes more sense in a threaded environment.
Modified: index
===================================================================
--- index 2008-10-18 00:03:44 UTC (rev 2351)
+++ index 2008-10-18 01:28:18 UTC (rev 2352)
@@ -35020,8 +35020,8 @@
void <a href=#dom-appcache-swapcache title=dom-appcache-swapCache>swapCache</a>();
// dynamic entries
- readonly attribute unsigned long <a href=#dom-appcache-length title=dom-appcache-length>length</a>;
- DOMString <a href=#dom-appcache-item title=dom-appcache-item>item</a>(in unsigned long index);
+ readonly attribute <span>DOMStringList</span> <a href=#dom-appcache-items title=dom-appcache-items>items</a>;
+ boolean <a href=#dom-appcache-hasitem title=dom-appcache-hasItem>hasItem</a>(in DOMString url);
void <a href=#dom-appcache-add title=dom-appcache-add>add</a>(in DOMString url);
void <a href=#dom-appcache-remove title=dom-appcache-remove>remove</a>(in DOMString url);
@@ -35113,28 +35113,20 @@
<i>obsolete</i> <a href=#concept-appcache-lifecycle title=concept-appcache-lifecycle>lifecycle
status</a>.</dd>
- </dl><p>The <dfn id=dom-appcache-length title=dom-appcache-length><code>length</code></dfn>
- attribute must return the number of <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entries</a> in the
- <a href=#application-cache>application cache</a> with which the
- <code><a href=#applicationcache>ApplicationCache</a></code> object is associated, if any, and zero
- if the object is not associated with any application cache.</p>
-
- <p>The <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entries</a>
+ </dl><hr><p>The <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entries</a>
in the <a href=#application-cache>application cache</a> are ordered in the same order
as they were added to the cache by the <code title=dom-appcache-add><a href=#dom-appcache-add>add()</a></code> method, with the oldest entry
- being the zeroth entry, and the most recently added entry having the
- index <span><code title=dom-appcache-length><a href=#dom-appcache-length>length</a></code>-1</span>.</p>
+ being the zeroth entry.</p>
- <p>The <dfn id=dom-appcache-item title=dom-appcache-item><code>item(<var title="">index</var>)</code></dfn> method must return the
- <a href=#absolute-url>absolute URL</a> of the <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entry</a> with index
- <var title="">index</var> from the <a href=#application-cache>application cache</a>,
- if one is associated with the <code><a href=#applicationcache>ApplicationCache</a></code>
- object. If the object is not associated with any application cache,
- or if the <var title="">index</var> argument is lower than zero or
- greater than <span><code title=dom-appcache-length><a href=#dom-appcache-length>length</a></code>-1</span>, the method must
- instead raise an <code>INDEX_SIZE_ERR</code> exception.</p>
+ <p>The <dfn id=dom-appcache-items title=dom-appcache-items><code>items</code></dfn> DOM
+ attribute must return a new <code>DOMStringList</code> object. If
+ the <code><a href=#applicationcache>ApplicationCache</a></code> object has an associated
+ <a href=#application-cache>application cache</a> with one or more <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entries</a>, then the
+ <code>DOMStringList</code> object's items must be the <a href=#absolute-url title="absolute URL">absolute URLs</a> of the <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entries</a> in that
+ <a href=#application-cache>application cache</a>, in order; otherwise, the object must
+ have no entries.</p>
- <p>The <dfn id=dom-appcache-add title=dom-appcache-add><code>add(<var title="">url</var>)</code></dfn> method must run the following
+ <p>The <dfn id=dom-appcache-hasitem title=dom-appcache-hasItem><code>hasItem(<var title="">url</var>)</code></dfn> method must run the following
steps:</p>
<ol><li><p>If the <code><a href=#applicationcache>ApplicationCache</a></code> object is not
@@ -35147,6 +35139,25 @@
<li><p>If there is already a resource in in the <a href=#application-cache>application
cache</a> with which the <code><a href=#applicationcache>ApplicationCache</a></code> object is
+ associated that has the address <var title="">url</var>, and that
+ entry is categorized as a <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entry</a>, then return
+ true.</li>
+
+ <li><p>Otherwise, return false.</li>
+
+ </ol><p>The <dfn id=dom-appcache-add title=dom-appcache-add><code>add(<var title="">url</var>)</code></dfn> method must run the following
+ steps:</p>
+
+ <ol><li><p>If the <code><a href=#applicationcache>ApplicationCache</a></code> object is not
+ associated with any application cache, then raise an
+ <code>INVALID_STATE_ERR</code> exception and abort these
+ steps.</li>
+
+ <li><p><a href=#resolve-a-url title="resolve a URL">Resolve</a> the <var title="">url</var> argument. If this fails, raise a
+ <code>SYNTAX_ERR</code> exception and abort these steps.</li>
+
+ <li><p>If there is already a resource in in the <a href=#application-cache>application
+ cache</a> with which the <code><a href=#applicationcache>ApplicationCache</a></code> object is
associated that has the address <var title="">url</var>, then
ensure that entry is categorized as a <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entry</a> and return
and abort these steps.</li>
@@ -35163,28 +35174,10 @@
or equivalent, or if there were network errors, or if the user
canceled the download, then abort these steps.</li>
- <li>
+ <li><p>Add the fetched resource to the <a href=#application-cache>application
+ cache</a> and categorize it as a <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entry</a>.</li>
- <p>Wait for there to be no running scripts, or at least no running
- scripts that can reach an <code><a href=#applicationcache>ApplicationCache</a></code> object
- associated with the <a href=#application-cache>application cache</a> with which this
- <code><a href=#applicationcache>ApplicationCache</a></code> object is associated.</p>
-
- <p>Add the fetched resource to the <a href=#application-cache>application cache</a>
- and categorize it as a <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entry</a> before
- letting any such scripts resume.</p>
-
- </li>
-
- </ol><p class=XXX>We can make the add() API more usable
- (i.e. make it possible to detect progress and distinguish success
- from errors without polling and timeouts) if we have the method
- return an object that is a target of Progress Events, much like the
- <a href="http://dev.w3.org/cvsweb/~checkout~/2006/webapi/XMLHttpRequest-2/Overview.html?content-type=text/html;%20charset=utf-8#xmlhttprequesteventtarget-interface">XMLHttpRequestEventTarget</a>
- interface. This would also make this far more complex to spec and
- implement.</p>
-
- <p>The <dfn id=dom-appcache-remove title=dom-appcache-remove><code>remove(<var title="">url</var>)</code></dfn> method must <a href=#resolve-a-url title="resolve a
+ </ol><p>The <dfn id=dom-appcache-remove title=dom-appcache-remove><code>remove(<var title="">url</var>)</code></dfn> method must <a href=#resolve-a-url title="resolve a
url">resolve</a> the <var title="">url</var> argument and, if
that is successful, remove the <a href=#concept-appcache-dynamic title=concept-appcache-dynamic>dynamic entry</a> categorization
of any entry whose address is the resulting <a href=#absolute-url>absolute
@@ -35196,7 +35189,10 @@
object is not associated with any application cache, then the method
must raise an <code>INVALID_STATE_ERR</code> exception instead.</p>
- <p>If the <dfn id=dom-appcache-update title=dom-appcache-update><code>update()</code></dfn> method is
+ <p class=warning>Authors should bear in mind that multiple scripts
+ could be simultaneously modifying the same application cache.</p>
+
+ <hr><p>If the <dfn id=dom-appcache-update title=dom-appcache-update><code>update()</code></dfn> method is
invoked, the user agent must invoke the <a href=#application-cache-update-process>application cache
update process</a>, in the background, for the <a href=#application-cache>application
cache</a> with which the <code><a href=#applicationcache>ApplicationCache</a></code> object is
Modified: source
===================================================================
--- source 2008-10-18 00:03:44 UTC (rev 2351)
+++ source 2008-10-18 01:28:18 UTC (rev 2352)
@@ -39778,8 +39778,8 @@
void <span title="dom-appcache-swapCache">swapCache</span>();
// dynamic entries
- readonly attribute unsigned long <span title="dom-appcache-length">length</span>;
- DOMString <span title="dom-appcache-item">item</span>(in unsigned long index);
+ readonly attribute <span>DOMStringList</span> <span title="dom-appcache-items">items</span>;
+ boolean <span title="dom-appcache-hasItem">hasItem</span>(in DOMString url);
void <span title="dom-appcache-add">add</span>(in DOMString url);
void <span title="dom-appcache-remove">remove</span>(in DOMString url);
@@ -39876,33 +39876,51 @@
</dl>
- <p>The <dfn title="dom-appcache-length"><code>length</code></dfn>
- attribute must return the number of <span
- title="concept-appcache-dynamic">dynamic entries</span> in the
- <span>application cache</span> with which the
- <code>ApplicationCache</code> object is associated, if any, and zero
- if the object is not associated with any application cache.</p>
+ <hr>
<p>The <span title="concept-appcache-dynamic">dynamic entries</span>
in the <span>application cache</span> are ordered in the same order
as they were added to the cache by the <code
title="dom-appcache-add">add()</code> method, with the oldest entry
- being the zeroth entry, and the most recently added entry having the
- index <span><code
- title="dom-appcache-length">length</code>-1</span>.</p>
+ being the zeroth entry.</p>
- <p>The <dfn title="dom-appcache-item"><code>item(<var
- title="">index</var>)</code></dfn> method must return the
- <span>absolute URL</span> of the <span
- title="concept-appcache-dynamic">dynamic entry</span> with index
- <var title="">index</var> from the <span>application cache</span>,
- if one is associated with the <code>ApplicationCache</code>
- object. If the object is not associated with any application cache,
- or if the <var title="">index</var> argument is lower than zero or
- greater than <span><code
- title="dom-appcache-length">length</code>-1</span>, the method must
- instead raise an <code>INDEX_SIZE_ERR</code> exception.</p>
+ <p>The <dfn title="dom-appcache-items"><code>items</code></dfn> DOM
+ attribute must return a new <code>DOMStringList</code> object. If
+ the <code>ApplicationCache</code> object has an associated
+ <span>application cache</span> with one or more <span
+ title="concept-appcache-dynamic">dynamic entries</span>, then the
+ <code>DOMStringList</code> object's items must be the <span
+ title="absolute URL">absolute URLs</span> of the <span
+ title="concept-appcache-dynamic">dynamic entries</span> in that
+ <span>application cache</span>, in order; otherwise, the object must
+ have no entries.</p>
+ <p>The <dfn title="dom-appcache-hasItem"><code>hasItem(<var
+ title="">url</var>)</code></dfn> method must run the following
+ steps:</p>
+
+ <ol>
+
+ <li><p>If the <code>ApplicationCache</code> object is not
+ associated with any application cache, then raise an
+ <code>INVALID_STATE_ERR</code> exception and abort these
+ steps.</p></li>
+
+ <li><p><span title="resolve a URL">Resolve</span> the <var
+ title="">url</var> argument. If this fails, raise a
+ <code>SYNTAX_ERR</code> exception and abort these steps.</p></li>
+
+ <li><p>If there is already a resource in in the <span>application
+ cache</span> with which the <code>ApplicationCache</code> object is
+ associated that has the address <var title="">url</var>, and that
+ entry is categorized as a <span
+ title="concept-appcache-dynamic">dynamic entry</span>, then return
+ true.</p></li>
+
+ <li><p>Otherwise, return false.</p></li>
+
+ </ol>
+
<p>The <dfn title="dom-appcache-add"><code>add(<var
title="">url</var>)</code></dfn> method must run the following
steps:</p>
@@ -39939,31 +39957,12 @@
or equivalent, or if there were network errors, or if the user
canceled the download, then abort these steps.</p></li>
- <li>
+ <li><p>Add the fetched resource to the <span>application
+ cache</span> and categorize it as a <span
+ title="concept-appcache-dynamic">dynamic entry</span>.</p></li>
- <p>Wait for there to be no running scripts, or at least no running
- scripts that can reach an <code>ApplicationCache</code> object
- associated with the <span>application cache</span> with which this
- <code>ApplicationCache</code> object is associated.</p>
-
- <p>Add the fetched resource to the <span>application cache</span>
- and categorize it as a <span
- title="concept-appcache-dynamic">dynamic entry</span> before
- letting any such scripts resume.</p>
-
- </li>
-
</ol>
- <p class="XXX">We can make the add() API more usable
- (i.e. make it possible to detect progress and distinguish success
- from errors without polling and timeouts) if we have the method
- return an object that is a target of Progress Events, much like the
- <a
- href="http://dev.w3.org/cvsweb/~checkout~/2006/webapi/XMLHttpRequest-2/Overview.html?content-type=text/html;%20charset=utf-8#xmlhttprequesteventtarget-interface">XMLHttpRequestEventTarget</a>
- interface. This would also make this far more complex to spec and
- implement.</p>
-
<p>The <dfn title="dom-appcache-remove"><code>remove(<var
title="">url</var>)</code></dfn> method must <span title="resolve a
url">resolve</span> the <var title="">url</var> argument and, if
@@ -39978,6 +39977,11 @@
object is not associated with any application cache, then the method
must raise an <code>INVALID_STATE_ERR</code> exception instead.</p>
+ <p class="warning">Authors should bear in mind that multiple scripts
+ could be simultaneously modifying the same application cache.</p>
+
+ <hr>
+
<p>If the <dfn
title="dom-appcache-update"><code>update()</code></dfn> method is
invoked, the user agent must invoke the <span>application cache
More information about the Commit-Watchers
mailing list