Skip to content
Permalink
Browse files

[gwr] (2) Appcache: Change the approach used for the dynamic entries …

…API so that it makes more sense in a threaded environment.

git-svn-id: http://svn.whatwg.org/webapps@2352 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information...
Hixie committed Oct 18, 2008
1 parent 3d938e9 commit a902de4c00a9cbd6ded85dfb982257382e4b4f26
Showing with 88 additions and 88 deletions.
  1. +39 −43 index
  2. +49 −45 source
82 index
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);

<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>

<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>
being the zeroth entry.</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-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-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
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>, 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
or equivalent, or if there were network errors, or if the user
canceled the download, then abort these steps.</li>

<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>
<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>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
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
94 source
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);


</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>

<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>
being the zeroth entry.</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
or equivalent, or if there were network errors, or if the user
canceled the download, then abort these steps.</p></li>

<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>
<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>

</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
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

0 comments on commit a902de4

Please sign in to comment.
You can’t perform that action at this time.