- From: Eric Uhrhane via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 07 Mar 2012 01:40:11 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv17501
Modified Files:
file-writer.html
Log Message:
Switch to using DOM4 errors; clean up some algorithm sequences.
Index: file-writer.html
===================================================================
RCS file: /sources/public/2009/dap/file-system/file-writer.html,v
retrieving revision 1.37
retrieving revision 1.38
diff -u -d -r1.37 -r1.38
--- file-writer.html 6 Mar 2012 21:28:39 -0000 1.37
+++ file-writer.html 7 Mar 2012 01:40:09 -0000 1.38
@@ -42,9 +42,9 @@
This API includes:
<ul>
<li> A <a>BlobBuilder</a> interface, which enables one to build a
- <code>Blob</code> from a String.
+ <a>Blob</a> from a String.
<li> A <a>FileSaver</a> interface, which provides methods to write a
- <code>Blob</code> to a file, and an event model to monitor the
+ <a>Blob</a> to a file, and an event model to monitor the
progress of those writes.</li>
<li> A <a>FileWriter</a> interface, which expands on FileSaver to add
a richer set of output options.</li>
@@ -65,7 +65,7 @@
<section id='conformance'>
<p>
This specification defines conformance criteria that apply to a single
- product: <a>user agents</a> that implement the interfaces that it
+ product: <a>user agent</a>s that implement the interfaces that it
contains.
</p>
@@ -150,6 +150,10 @@
[[!PROGRESS-EVENTS]].</li>
</ul>
</p>
+ The term <dfn>throw</dfn> in this specification, as it pertains to
+ exceptions, is used as defined in the DOM4 specification [[!DOM4]].
+ <p>
+ </p>
<p>
The term <dfn>Blob</dfn> is defined by the File API specification
[[!FILE-API]].
@@ -173,7 +177,7 @@
files. One can present a link for download, but creating and writing
files of arbitrary type, or modifying downloaded files on their way to
the disk, is difficult or impossible. This specification defines an
- API through which <a>user agents</a> can permit applications to write
+ API through which <a>user agent</a>s can permit applications to write
generated or downloaded files.
</p>
<p>
@@ -222,14 +226,18 @@
<section>
<h2>The <code>BlobBuilder</code> interface</h2>
<p>
- BlobBuilder description
+ The BlobBuilder is used to construct <a>Blob</a>s.
</p>
+ <div class='issue'>The BlobBuilder interface is deprecated in favor of the
+ new constructible Blob. However, at this time implementations
+ generally support BlobBuilder and not constructible Blob.
+ </div>
<dl title='[Constructor] interface BlobBuilder' class='idl'>
<dt>Blob getBlob ()</dt>
<dd>
<p>
Returns the current contents of the <code>BlobBuilder</code> as a
- <code>Blob</code>.
+ <a>Blob</a>.
</p>
<dl class='parameters'>
<dt>optional DOMString contentType</dt>
@@ -290,10 +298,6 @@
</table>
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>SYNTAX_ERR</dt>
- <dd>The user supplied an unsupported value for <a>endings</a>.</dd>
- </dl>
</dd>
<dt>void append ()</dt>
<dd>
@@ -325,7 +329,7 @@
<section>
<h2>Constructor</h2>
<p>
- When the <a>BlobBuilder</a> constructor is invoked, <a>user agents</a>
+ When the <a>BlobBuilder</a> constructor is invoked, <a>user agent</a>s
MUST return a new <a>BlobBuilder</a> object.
</p>
<p>
@@ -351,7 +355,7 @@
<dt>void abort ()</dt>
<dd>
<p>
- When the <code>abort</code> method is called, <a>user agents</a>
+ When the <code>abort</code> method is called, <a>user agent</a>s
MUST run the steps below:
<ol>
<li>If <code>readyState == DONE</code> or
@@ -363,8 +367,8 @@
those <a>task</a>s.</li>
<li><a>Terminate</a> the <a>write algorithm</a> being
processed.</li>
- <li>Set the <code>error</code> attribute to a FileError object
- with the code <a>ABORT_ERR</a>.</li>
+ <li>Set the <code>error</code> attribute to a
+ <code>DOMError</code> object of type "AbortError".</li>
<li><a>Fire a progress event</a> called <code>abort</code></li>
<li><a>Fire a progress event</a> called <code>writeend</code></li>
<li>Terminate this algorithm.</li>
@@ -381,7 +385,7 @@
</dd>
<dt>const unsigned short DONE = 2</dt>
<dd>
- The entire Blob has been written to the file, a file error occurred
+ The entire Blob has been written to the file, an error occurred
during the write, or the write was aborted using <a>abort()</a>. The
FileSaver is no longer writing the blob.
</dd>
@@ -398,7 +402,7 @@
</ul>
</p>
</dd>
- <dt>readonly attribute FileError error</dt>
+ <dt>readonly attribute DOMError error</dt>
<dd>
<p>
The last error that occurred on the <code>FileSaver</code>.
@@ -492,8 +496,8 @@
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute MUST be a
- <code>FileError</code> object with a valid error code that
- indicates the kind of file error that has occurred.</li>
+ <code>DOMError</code> object whose type
+ indicates the kind of error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li><a>Fire a progress event</a> called
<code>error</code>.</li>
@@ -622,12 +626,11 @@
<dd>
<p>
Write the supplied data to the file at <code>position</code>. When
- the <code>write</code> method is called, <a>user agents</a> MUST run
+ the <code>write</code> method is called, <a>user agent</a>s MUST run
the steps below (unless otherwise indicated).
<ol>
- <li>If <code>readyState</code> is <code>WRITING</code>, throw a
- <code>FileException</code> with error code
- <code>INVALID_STATE_ERR</code> and terminate this overall series
+ <li>If <code>readyState</code> is <code>WRITING</code>,
+ <a>throw</a> an <a>InvalidStateError</a> and terminate this series
of steps.</li>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during file write, proceed to the error
@@ -635,8 +638,8 @@
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute MUST be a
- <code>FileError</code> object with a valid error code that
- indicates the kind of file error that has occurred.</li>
+ <code>DOMError</code> object whose type
+ indicates the kind of error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li><a>Fire a progress event</a> called
<code>error</code>.</li>
@@ -686,11 +689,6 @@
The blob to write.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>INVALID_STATE_ERR</dt>
- <dd>A user called <code>write</code> while <code>readyState</code>
- was <code>WRITING</code>.</dd>
- </dl>
</dd>
<dt>void seek ()</dt>
<dd>
@@ -698,27 +696,31 @@
Seek sets the file position at which the next write will occur.
</p>
<p>
- Seek may not be called while the <a>FileWriter</a> is in the
- <code>WRITING</code> state.
+ When the <code>seek</code> method is called, <a>user agent</a>s MUST
+ run the steps below.
+ </p>
+ <ol>
+ <li> If <code>readyState</code> is <code>WRITING</code>,
+ <a>throw</a> an <a>InvalidStateError</a> and terminate this series
+ of steps.</li>
+ <li> Set <code>position</code> to <code>offset</code>.</li>
+ <li> If <code>position > length</code> then set <code>
+ position</code> to </code>length</code>.</li>
+ <li> If <code>position < 0</code> then set <code>
+ position</code> to <code>position + length</code>.</li>
+ <li> If <code>position < 0</code> then set <code>
+ position</code> to <code>0</code>.</li>
+ </ol>
</p>
<dl class='parameters'>
<dt>long long offset</dt>
<dd>
<p>
- An absolute byte offset into the file. If <code>offset</code>
- is greater than <code>length</code>, <code>length</code> is used
- instead. If <code>offset</code> is less than zero,
- <code>length</code> is added to it, so that it is treated as an
- offset back from the end of the file. If it is still less than
- zero, zero is used.<br />
+ If nonnegative, an absolute byte offset into the file.<br />
+ If negative, an offset back from the end of the file.
</p>
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>INVALID_STATE_ERR</dt>
- <dd>A user called <code>seek</code> while <code>readyState</code>
- was <code>WRITING</code>.</dd>
- </dl>
</dd>
<dt>void truncate ()</dt>
<dd>
@@ -729,22 +731,20 @@
length.
</p>
<p>
- When the <code>truncate</code> method is called, <a>user agents</a>
+ When the <code>truncate</code> method is called, <a>user agent</a>s
MUST run the steps below (unless otherwise indicated).
</p>
<ol>
- <li>If <code>readyState</code> is <code>WRITING</code>, throw a
- <code>FileException</code> with error code
- <code>INVALID_STATE_ERR</code> and terminate this overall series of
- steps.</li>
+ <li>If <code>readyState</code> is <code>WRITING</code>, <a>throw</a>
+ an <a>InvalidStateError</a> and terminate this series of steps.</li>
<li>Set <code>readyState</code> to <code>WRITING</code>.</li>
<li>If an error occurs during truncate, proceed to the error steps
below.
<ol>
<li>Set the <code>error</code> attribute; on getting the
<code>error</code> attribute MUST be a
- <code>FileError</code> object with a valid error code that
- indicates the kind of file error that has occurred.</li>
+ <code>DOMError</code> object whose type
+ indicates the kind of error that has occurred.</li>
<li>Set readyState to <code>DONE</code>.</li>
<li><a>Fire a progress event</a> called
<code>error</code>.</li>
@@ -790,12 +790,6 @@
measured in bytes.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>INVALID_STATE_ERR</dt>
- <dd>A user called <code>truncate</code> while
- <code>readyState</code> was <code>WRITING</code>.
- </dd>
- </dl>
</dd>
</dl>
</section>
@@ -844,18 +838,6 @@
The blob to write.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>The user attempted to modify a read-only file.</dd>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The path to the directory containing the file to be written does
- not exist, or the file does not exist and offset is nonzero.</dd>
- <dt>INVALID_STATE_ERR</dt>
- <dd>At the time of the call, <code>readyState</code> was
- <code>WRITING</code>.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The system has disallowed the write for security reasons.</dd>
- </dl>
</dd>
<dt>void seek ()</dt>
<dd>
@@ -873,11 +855,6 @@
zero, zero is used.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>INVALID_STATE_ERR</dt>
- <dd>A user called <code>seek</code> while <code>readyState</code>
- was <code>WRITING</code>.</dd>
- </dl>
</dd>
<dt>void truncate ()</dt>
<dd>
@@ -906,24 +883,17 @@
measured in bytes.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>The user attempted to modify a read-only file.</dd>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The file to be truncated does not exist.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The system has disallowed the truncation for security
- reasons.</dd>
- </dl>
</dd>
</dl>
</section>
<section>
<h2>Errors and Exceptions</h2>
+ <section class=informative>
+ <h3>Occurrence</h3>
<p>
Error conditions can occur when attempting to write files. The list
below of potential error conditions is informative, with links to
- normative descriptions of error codes:
+ normative descriptions of errors:
</p>
<p>
The directory containing the file being written may not exist at the
@@ -931,18 +901,18 @@
may be due to it having been moved or deleted after a reference to it
was acquired (e.g. concurrent modification with another
application).<br/>
- See <a>NOT_FOUND_ERR</a>.
+ See <a>NotFoundError</a>.
</p>
<p>
The file being written may have been removed. If the file is not there,
writing to an offset other than zero is not permitted.<br/>
- See <a>NOT_FOUND_ERR</a>.
+ See <a>NotFoundError</a>.
</p>
<p>
A file may be unwritable. This may be due to permission problems that
occur after a reference to a file has been acquired (e.g. concurrent
lock with another application).<br/>
- See <a>NO_MODIFICATION_ALLOWED_ERR</a>.
+ See <a>NoModificationAllowedError</a>.
</p>
<p>
User agents MAY determine that some files are unsafe for use within web
@@ -950,158 +920,116 @@
considered restricted by the underlying filesystem; attempts to write to
them may be considered a security violation. See the security
considerations.<br/>
- See <a>SECURITY_ERR</a>.
+ See <a>SecurityError</a>.
</p>
<p>
A web application may attempt to initiate a write, seek, or truncate via
a FileWriter in the <code>WRITING</code> state.<br/>
- See <a>INVALID_STATE_ERR</a>.
+ See <a>InvalidStateError</a>.
</p>
<p>
During the writing of a file, the web application may itself wish to
- abort (see abort()) the call to an asynchronous <a>write
+ <code>abort</code> the call to an asynchronous <a>write
method</a>.<br/>
- See <a>ABORT_ERR</a>.
+ See <a>AbortError</a>.
</p>
<p>
A web application may request unsupported line endings.
- See <a>SYNTAX_ERR</a>.
+ See <a>SyntaxError</a>.
</p>
- <section>
- <h2>The FileError Interface</h2>
<p>
- This interface extends the <a>FileError</a> interface described in
- [[!FILE-API]] to add several new error codes. It is used to report
- errors asynchronously. The FileWriter object's error attribute is a
- FileError object, and is accessed asynchronously through the onerror
- event handler when error events are generated.
- </p>
- <dl title='interface FileError' class='idl'>
- <dt>const unsigned short NOT_FOUND_ERR = 1</dt>
- <dd> </dd>
- <dt>const unsigned short SECURITY_ERR = 2</dt>
- <dd> </dd>
- <dt>const unsigned short ABORT_ERR = 3</dt>
- <dd> </dd>
- <dt>const unsigned short NOT_READABLE_ERR = 4</dt>
- <dd> </dd>
- <dt>const unsigned short ENCODING_ERR = 5</dt>
- <dd> </dd>
- <dt>const unsigned short NO_MODIFICATION_ALLOWED_ERR = 6</dt>
- <dd> </dd>
- <dt>const unsigned short INVALID_STATE_ERR = 7</dt>
- <dd> </dd>
- <dt>const unsigned short SYNTAX_ERR = 8</dt>
- <dd> </dd>
- <dt>const unsigned short QUOTA_EXCEEDED_ERR = 10</dt>
- <dd> </dd>
- <dt>readonly attribute unsigned short code</dt>
- <dd> </dd>
- </dl>
- The <a>code</a> attribute MUST return one of the constants of the
- <a>FileError</a> error, which MUST be the most appropriate code from the
- <a>Error Code Descriptions</a>.
- </section>
- <section>
- <h2>The FileException exception</h2>
- This interface extends the <a>FileException</a> interface described in
- [[!FILE-API]] to add several new error codes.
- Any errors that need to be reported synchronously, including all that
- occur during use of any synchronous <a>write method</a> for Web
- Workers [[WEBWORKERS]] are reported using the FileException exception.
- <dl title='exception FileException' class='idl'>
- <dt>const unsigned short NOT_FOUND_ERR = 1</dt>
- <dd> </dd>
- <dt>const unsigned short SECURITY_ERR = 2</dt>
- <dd> </dd>
- <dt>const unsigned short ABORT_ERR = 3</dt>
- <dd> </dd>
- <dt>const unsigned short NOT_READABLE_ERR = 4</dt>
- <dd> </dd>
- <dt>const unsigned short ENCODING_ERR = 5</dt>
- <dd> </dd>
- <dt>const unsigned short NO_MODIFICATION_ALLOWED_ERR = 6</dt>
- <dd> </dd>
- <dt>const unsigned short INVALID_STATE_ERR = 7</dt>
- <dd> </dd>
- <dt>const unsigned short SYNTAX_ERR = 8</dt>
- <dd> </dd>
- <dt>const unsigned short QUOTA_EXCEEDED_ERR = 10</dt>
- <dd> </dd>
- <dt>unsigned short code</dt>
- <dd> </dd>
- </dl>
- The <a>code</a> field MUST return one of the constants of the
- <a>FileException</a> error, which MUST be the most appropriate code from
- the <a>Error Code Descriptions</a>.
+ As documented in [[!FILE-API]], various errors may occur during reading
+ from the Blob that is the source of the data to be written.
+ These include <a>NotFoundError</a>, <a>SecurityError</a>, and
+ <a>NotReadableError</a>.
</section>
<section>
- <h2><dfn>Error Code Descriptions</dfn></h2>
+ <h3>Definitions</h3>
+ <p>
+ Synchronous <a>write method</a>s MUST <a>throw</a> an exception of the
+ most appropriate type in the table below if there has been an error with
+ writing.
+ </p>
+ <p>
+ If an error occurs while processing an asynchronous <a>write method</a>,
+ the <code>error</code> attribute of the <a>FileSaver</a> object MUST
+ return a <code>DOMError</code> object [[!DOM4]] of the most appropriate
+ type from the table below. Otherwise it MUST return <code>null</code>.
+ </p>
+ <dfn>Error Descriptions</dfn>
<table class='simple'>
<thead>
- <tr><th>Name</th><th>Value</th><th>Description</th></tr>
+ <tr><th>Name</th><th>Description</th></tr>
</thead>
<tbody>
<tr>
- <td><dfn>ABORT_ERR</dfn></td><td>20</td>
- <td>User agents MUST use this code if the read operation was
- aborted, typically with a call to <a>abort()</a>.
+ <td><dfn>AbortError</dfn></td>
+ <td>The read operation was aborted, typically with a call to
+ <a>abort()</a>.
</td>
</tr>
<tr>
- <td><dfn>INVALID_STATE_ERR</dfn></td><td>11</td>
- <td>User agents MUST use this code if an application attempts to
- initiate a write, truncate, or seek using a <a>FileWriter</a>
- which is already in the <a>WRITING</a> state.
+ <td><dfn>InvalidStateError</dfn></td>
+ <td>An application attempted to initiate a write, truncate, or
+ seek using a <a>FileWriter</a> which is already in the
+ <a>WRITING</a> state.
</td>
</tr>
<tr>
- <td><dfn>NOT_FOUND_ERR</dfn></td><td>8</td>
- <td>User agents MUST use this code if:
+ <td><dfn>NotFoundError</dfn></td>
+ <td>One or more of the following occurred:
<ul>
<li>the directory containing the file to be written could
not be found at the time the write was processed.</li>
<li>the file to be written does not exist at the time the
write was processed, and an <code>offset</code> other than
zero is specified.</li>
+ <li>the blob that is the source of data to be written could
+ not be found at the time the write was processed.
</ul>
</td>
</tr>
<tr>
- <td><dfn>NO_MODIFICATION_ALLOWED_ERR</dfn></td><td>6</td>
- <td>User agents MUST use this code when attempting to write to a
- file which cannot be modified due to the state of the
- underlying filesystem.
+ <td><dfn>NoModificationAllowedError</dfn></td>
+ <td>The application attempted to write to a file which cannot be
+ modified due to the state of the underlying filesystem.
+ </td>
+ </tr>
+ <tr>
+ <td><dfn>NotReadableError</dfn></td>
+ <td>The source <a>Blob</a> could not be read, typically due to
+ permission problems that occur after the <a>Blob</a> reference
+ was acquired.
</td>
</tr>
<tr>
- <td><dfn>QUOTA_EXCEEDED_ERR</dfn></td><td>10</td>
+ <td><dfn>QuotaExceededError</dfn></td>
<td>
- <a>user agent</a> MUST use this code if the operation failed
- because it would cause the application to exceed its storage
- quota.
+ The operation failed because it would have caused the
+ application to exceed its storage quota.
</td>
</tr>
<tr>
- <td><dfn>SECURITY_ERR</dfn></td><td>18</td>
+ <td><dfn>SecurityError</dfn></td>
<td>
- User agents MAY use this code if:
+ One or more of the following occurred:
<ul>
- <li> it is determined that certain files are unsafe for
+ <li> it was determined that certain files are unsafe for
access within a Web application</li>
- <li>it is determined that too many write calls are being
+ <li>it was determined that too many write calls are being
made on file resources</li>
- <li>it is determined that the file has changed on disk since
- the user selected it</li>
+ <li>it was determined that the file to be written, or the
+ source data to be read, has changed on disk since the user
+ selected it</li>
</ul>
- This is a security error code to be used in situations not
- covered by any other error codes.
+ This is an error to be used in situations not covered by any
+ other error.
</td>
</tr>
<tr>
- <td><dfn>SYNTAX_ERR</dfn></td><td>12</td>
- <td>User agents MUST use this code when an application attempts
- to supply an invalid line ending specifier to the API.
+ <td><dfn>SyntaxError</dfn>
+ <td>The application attempted to supply an invalid line ending
+ specifier to the API.
</td>
</tr>
</tbody>
@@ -1138,7 +1066,7 @@
<section>
<h2>Quotas</h2>
<p>
- Where quotas are concerned, <a>user agents</a> may wish to monitor the
+ Where quotas are concerned, <a>user agent</a>s may wish to monitor the
size of the file(s) being written and possibly interrupt the script and
warn the user if certain limits of file size, remaining space, or disk
bandwidth are reached.
Received on Wednesday, 7 March 2012 01:40:14 UTC