- From: Eric Uhrhane via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 07 Mar 2012 22:47:20 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/file-system
In directory hutz:/tmp/cvs-serv22124
Modified Files:
file-dir-sys.html
Log Message:
Switch to DOM4 events, misc cleanup.
Index: file-dir-sys.html
===================================================================
RCS file: /sources/public/2009/dap/file-system/file-dir-sys.html,v
retrieving revision 1.41
retrieving revision 1.42
diff -u -d -r1.41 -r1.42
--- file-dir-sys.html 5 Mar 2012 21:49:36 -0000 1.41
+++ file-dir-sys.html 7 Mar 2012 22:47:17 -0000 1.42
@@ -8,7 +8,7 @@
var respecConfig = {
specStatus: "ED",
shortName: "file-system-api",
- publishDate: "2011-02-28",
+ publishDate: "2012-03-07",
previousPublishDate: "2010-10-26",
previousMaturity: "WD",
edDraftURI: "http://dev.w3.org/2009/dap/file-system/file-dir-sys.html",
@@ -159,7 +159,24 @@
</pre>
</section>
</section>
-
+ <section>
+ <h2>Terminology</h2>
+
+ </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>
+ <dfn>DOMError</dfn> is defined in the DOM4 specification [[!DOM4]].
+ <p>
+ </p>
+ <dfn>File</dfn> is defined in the File API specification [[!FILE-API]].
+ <p>
+ </p>
+ <dfn>FileWriter</dfn> and <dfn>FileWriterSync</dfn> are defined in the
+ FileWriter specification [[!FILE-WRITER]].
+ <p>
+ </section>
<section>
<h2>Data Persistence and accessing the API</h2>
<section class='informative'>
@@ -393,11 +410,6 @@
application expects to need.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>SECURITY_ERR</dt>
- <dd>The application does not have permission to access the
- filesystem interface.</dd>
- </dl>
</dd>
<dt>EntrySync resolveLocalFileSystemSyncURL ()</dt>
<dd>
@@ -412,16 +424,6 @@
this API.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>ENCODING_ERR</dt>
- <dd>The URL was invalid.</dd>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The URL was structurally correct, but refers to a resource
- that does not exist.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The application does not have permission to access the
- filesystem interface or the element referred to by the URL.</dd>
- </dl>
</dd>
</dl>
</section>
@@ -745,7 +747,7 @@
</dd>
<dt>EntryCallback successCallback</dt>
<dd>
- A callback that is called to return the File selected or
+ A callback that is called to return the <a>File</a> selected or
created.
</dd>
<dt>optional ErrorCallback errorCallback</dt>
@@ -868,7 +870,7 @@
<dt>void createWriter ()</dt>
<dd>
<p>
- Creates a new <code>FileWriter</code> associated with the file
+ Creates a new <a>FileWriter</a> associated with the file
that this <code>FileEntry</code> represents.
</p>
<dl class='parameters'>
@@ -885,7 +887,7 @@
<dt>void file ()</dt>
<dd>
<p>
- Returns a <code>File</code> that represents the current state of
+ Returns a <a>File</a> that represents the current state of
the file that this <code>FileEntry</code> represents.
</p>
<dl class='parameters'>
@@ -982,14 +984,14 @@
<h2>The <code>FileWriterCallback</code> interface</h2>
<p>
This interface is the callback used to create a
- <code>FileWriter</code>.
+ <a>FileWriter</a>.
</p>
<dl title='[Callback=FunctionOnly] interface FileWriterCallback'
class='idl'>
<dt>void handleEvent (FileWriter fileWriter)</dt>
<dd>
<p>
- Used to supply a <code>FileWriter</code> as a response to a user
+ Used to supply a <a>FileWriter</a> as a response to a user
query.
</p>
</dd>
@@ -999,14 +1001,14 @@
<section>
<h2>The <code>FileCallback</code> interface</h2>
<p>
- This interface is the callback used to obtain a <code>File</code>.
+ This interface is the callback used to obtain a <a>File</a>.
</p>
<dl title='[Callback=FunctionOnly] interface FileCallback'
class='idl'>
<dt>void handleEvent (File file)</dt>
<dd>
<p>
- Used to supply a <code>File</code> as a response to a user query.
+ Used to supply a <a>File</a> as a response to a user query.
</p>
</dd>
</dl>
@@ -1037,10 +1039,10 @@
<dd>
<p>
There was an error with the request. Details are provided by the
- <a>FileError</a> parameter.
+ <code>err</code> parameter.
</p>
<dl class='parameters'>
- <dt>FileError err</dt>
+ <dt>DOMError err</dt>
<dd>
The error that was generated.
</dd>
@@ -1097,16 +1099,6 @@
<p>
Look up metadata about this entry.
</p>
- <dl class='exception' title='FileException'>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The entry no longer exists.</dd>
- <dt>INVALID_STATE_ERR</dt>
- <dd>This FileSystemSync is no longer valid for some reason other
- than it having been deleted.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
<dt>readonly attribute DOMString name</dt>
<dd>
@@ -1151,22 +1143,6 @@
name if unspecified.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>ENCODING_ERR</dt>
- <dd>The name supplied was invalid.</dd>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The target directory does not exist.</dd>
- <dt>INVALID_MODIFICATION_ERR</dt>
- <dd>The user attempted to move an entry into its parent without
- changing its name, or attempted to move a directory into a
- directory that it contains directly or indirectly.</dd>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>The either the source entry, its parent directory, or the
- target directory is not writable.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
<dt>EntrySync copyTo (DirectoryEntrySync parent, DOMString
newName)</dt>
@@ -1188,24 +1164,6 @@
name if unspecified.
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>ENCODING_ERR</dt>
- <dd>The name supplied was invalid.</dd>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The target directory does not exist.</dd>
- <dt>INVALID_MODIFICATION_ERR</dt>
- <dd>The user attempted to copy an entry into its parent without
- changing its name, or attempted to copy a directory into a
- directory that it contains directly or indirectly.</dd>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>The target directory is not writable.</dd>
- <dt>QUOTA_EXCEEDED_ERR</dt>
- <dd>The operation would cause the application to exceed its
- storage quota.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
<dt>DOMString toURL ()</dt>
<dd>
@@ -1223,18 +1181,6 @@
a directory that is not empty. It is an error to attempt to
delete the root directory of a filesystem.
</p>
- <dl class='exception' title='FileException'>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The target directory does not exist.</dd>
- <dt>INVALID_MODIFICATION_ERR</dt>
- <dd>The user attempted to remove a directory that was not
- empty.</dd>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>The target or its containing directory is not writable.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
<dt>DirectoryEntrySync getParent ()</dt>
<dd>
@@ -1256,13 +1202,6 @@
Creates a new DirectoryReaderSync to read EntrySyncs from this
DirectorySync.
</p>
- <dl class='exception' title='FileException'>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The directory no longer exists.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
<dt>FileEntrySync getFile ()</dt>
<dd>
@@ -1294,26 +1233,6 @@
</ul>
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>ENCODING_ERR</dt>
- <dd>The path was invalid.</dd>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The path was structurally correct, but refers to a resource
- that does not exist.</dd>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>The target directory or file is not writable.</dd>
- <dt>PATH_EXISTS_ERR</dt>
- <dd>The user attempted to create a file where an element already
- exists.
- <dt>QUOTA_EXCEEDED_ERR</dt>
- <dd>The operation would cause the application to exceed its
- storage quota.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The application does not have permission to access the
- element referred to by path.</dd>
- <dt>TYPE_MISMATCH_ERR</dt>
- <dd>The path supplied exists, but is not a directory.</dd>
- </dl>
</dd>
<dt>DirectoryEntrySync getDirectory ()</dt>
<dd>
@@ -1345,26 +1264,6 @@
</ul>
</dd>
</dl>
- <dl class='exception' title='FileException'>
- <dt>ENCODING_ERR</dt>
- <dd>The path was invalid.</dd>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The path was structurally correct, but refers to a resource
- that does not exist.</dd>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>The target directory is not writable.</dd>
- <dt>PATH_EXISTS_ERR</dt>
- <dd>The user attempted to create a directory where an element
- already exists.
- <dt>QUOTA_EXCEEDED_ERR</dt>
- <dd>The operation would cause the application to exceed its
- storage quota.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The application does not have permission to access the
- element referred to by path.</dd>
- <dt>TYPE_MISMATCH_ERR</dt>
- <dd>The path supplied exists, but is not a directory.</dd>
- </dl>
</dd>
<dt>void removeRecursively ()</dt>
<dd>
@@ -1375,20 +1274,6 @@
directory MAY be deleted. It is an error to attempt to delete the
root directory of a filesystem.
</p>
- <dl class='exception' title='FileException'>
- <dt>NOT_FOUND_ERR</dt>
- <dd>This DirectoryEntrySync refers to a resource that does not
- exist.</dd>
- <dt>INVALID_STATE_ERR</dt>
- <dd>This DirectoryEntrySync is no longer valid for some reason
- other than it having been deleted.</dd>
- <dt>NO_MODIFICATION_ALLOWED_ERR</dt>
- <dd>At least one of the target directory, its parent, or some of
- its contents, is not writable.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The application does not have permission to access the target
- directory, its parent, or some of its contents.</dd>
- </dl>
</dd>
</dl>
</section>
@@ -1416,16 +1301,6 @@
<p>
Read the next block of entries from this directory.
</p>
- <dl class='exception' title='FileException'>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The directory no longer exists.</dd>
- <dt>INVALID_STATE_ERR</dt>
- <dd>The directory has been modified since the first call to
- readEntries began to be processed.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
</dl>
</section>
@@ -1436,164 +1311,91 @@
This interface represents a file on a file system.
</p>
<dl title='interface FileEntrySync : EntrySync' class='idl'>
- <dt>FileWriterSync createWriter ()</dt>
+ <dt><a>FileWriterSync</a> createWriter ()</dt>
<dd>
<p>
- Creates a new <code>FileWriterSync</code> associated with the file
+ Creates a new <a>FileWriterSync</a> associated with the file
that this <code>FileEntrySync</code> represents.
</p>
- <dl class='exception' title='FileException'>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The entry no longer exists.</dd>
- <dt>INVALID_STATE_ERR</dt>
- <dd>This FileEntrySync is no longer valid for some reason other
- than it having been deleted.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
<dt>File file ()</dt>
<dd>
<p>
- Returns a <code>File</code> that represents the current state of
+ Returns a <a>File</a> that represents the current state of
the file that this <code>FileEntrySync</code> represents.
</p>
- <dl class='exception' title='FileException'>
- <dt>NOT_FOUND_ERR</dt>
- <dd>The entry no longer exists.</dd>
- <dt>INVALID_STATE_ERR</dt>
- <dd>This FileEntrySync is no longer valid for some reason other
- than it having been deleted.</dd>
- <dt>SECURITY_ERR</dt>
- <dd>The <a>user agent</a> determined that it was not safe to carry
- out this action.</dd>
- </dl>
</dd>
</dl>
</section>
</section>
<section>
- <h2>Dealing with errors and exceptions</h2>
- <section>
- <h2>The <code>FileError</code> interface</h2>
- <p>
- This interface extends the <a>FileError</a> interface described in
- [[!FILE-WRITER]] to add several new error codes.
- It is used to report errors asynchronously.
- </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 INVALID_MODIFICATION_ERR = 9</dt>
- <dd> </dd>
- <dt>const unsigned short QUOTA_EXCEEDED_ERR = 10</dt>
- <dd> </dd>
- <dt>const unsigned short TYPE_MISMATCH_ERR = 11</dt>
- <dd> </dd>
- <dt>const unsigned short PATH_EXISTS_ERR = 12</dt>
- <dd> </dd>
- <dt>attribute unsigned short code</dt>
- <dd>
- The <a>code</a> attribute, on getting, MUST return one of the
- constants of the <a>FileError</a> error, which MUST be the most
- appropriate code from the table below.
- </dd>
- </dl>
- </dl>
- </section>
-
- <section>
- <h2>The FileException exception</h2>
- This interface extends the <a>FileException</a> interface described in
- [[!FILE-WRITER]] to add several new error codes. Any errors that need
- to be reported synchronously, including all that occur during use of
- the synchronous filesystem methods, 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 INVALID_MODIFICATION_ERR = 9</dt>
- <dd> </dd>
- <dt>const unsigned short QUOTA_EXCEEDED_ERR = 10</dt>
- <dd> </dd>
- <dt>const unsigned short TYPE_MISMATCH_ERR = 11</dt>
- <dd> </dd>
- <dt>const unsigned short PATH_EXISTS_ERR = 12</dt>
- <dd> </dd>
- <dt>readonly unsigned short code</dt>
- <dd>
- The <a>code</a> attribute, on getting, MUST return one of the
- constants of the <a>FileException</a> exception, which MUST be the
- most appropriate code from the table below.
- </dd>
- </dl>
+ <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 errors:
+ </p>
+ <p>
+ An operation on a file may fail due to the file [or a parent directory]
+ having been removed before the operation is attempted. See
+ <a>NotFoundError</a>.
+ </p>
+ <p>
+ An operation on a file may not make sense, e.g. moving a directory into
+ one of its own children. See <a>InvalidModificationError</a>.
+ </p>
+ <p>
+ An operation on a file may not make sense if the underlying filesystem
+ has had changes made since the reference was obtained. See
+ <a>TypeMismatchError</a>, <a>InvalidStateError</a>.
+ </p>
+ <p>
+ Users may accidentally attempt to create a file where another already
+ exists. See <a>PathExistsError</a>.
+ </p>
</section>
-
<section>
- <h2>Error Code Descriptions</h2>
+ <h3>Definitions</h3>
+ <p>
+ Synchronous methods 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 method,
+ the <code>err</code> argument to the <a>ErrorCallback</a> MUST
+ be a <code>DOMError</code> object [[!DOM4]] of the most appropriate
+ type from the table below.
+ </p>
+ <h4>Error Descriptions</h4>
<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>ABORT_ERR</td><td>3</td>
- <td>
- This value MUST NOT be used in this API.
- </td>
- </tr>
<tr>
- <td>ENCODING_ERR</td><td>5</td>
+ <td><dfn>EncodingError</dfn></td>
<td>
- <a>user agent</a> MUST use this code when a URL supplied to
- the API is malformed.
+ A path or URL supplied to the API was malformed.
</td>
</tr>
<tr>
- <td>INVALID_MODIFICATION_ERR</td><td>9</td>
+ <td><dfn>InvalidModificationError</dfn></td>
<td>
- <a>user agent</a> MAY use this code if the modification
- requested is illegal. Examples of invalid modifications
- include moving a directory into its own child or moving a file
- into its parent directory without changing its name.
+ The modification requested was illegal. Examples of invalid
+ modifications include moving a directory into its own child or
+ moving a file into its parent directory without changing its
+ name.
</td>
</tr>
<tr>
- <td>INVALID_STATE_ERR</td><td>7</td>
+ <td><dfn>InvalidStateError</dfn></td>
<td>
- <a>user agent</a> MAY use this code if an operation depends on
- state cached in an interface object that has changed since it
- was read from disk.
+ An operation depended on state cached in an interface object,
+ but that state that has changed since it was read from disk.
<div class='issue'>
Which values will actually go stale? Modification
time, name, more rarely type. If an atomic save [replacing
@@ -1603,73 +1405,59 @@
</td>
</tr>
<tr>
- <td>NOT_FOUND_ERR</td><td>1</td>
+ <td><dfn>NotFoundError</dfn></td>
<td>
- <a>user agent</a> MUST use this code if a required file or
- directory could not be found at the time an operation was
- processed.
+ A required file or directory could not be found at the time an
+ operation was processed.
</td>
</tr>
<tr>
- <td>NOT_READABLE_ERR</td><td>4</td>
+ <td>NotReadableErr</td>
<td>
- <a>user agent</a> MUST use this code if a file or directory
- cannot be read, typically due due to permission problems that
- occur after a reference to a file has been acquired (e.g.
- concurrent lock with another application).
+ A required file or directory could be read.
</td>
</tr>
<tr>
- <td>NO_MODIFICATION_ALLOWED_ERR</td><td>6</td>
- <td><a>user agent</a> MUST use this code when attempting to
- write to a file or directory which cannot be modified due to
- the state of the underlying filesystem.
+ <td><dfn>NoModificationAllowedError</dfn></td>
+ <td>
+ The user attempted to write to a file or directory
+ which could not be modified due to the state of the underlying
+ filesystem.
</td>
</tr>
<tr>
- <td>PATH_EXISTS_ERR</td><td>12</td>
- <td><a>user agent</a> MUST use this code when failing to
- create a file or directory due to the existence of a file or
- directory with the same path.
+ <td><dfn>PathExistsError</dfn></td>
+ <td>
+ The <a>user agent</a> failed to create a file or directory due
+ to the existence of a file or directory with the same path.
</td>
</tr>
<tr>
- <td>QUOTA_EXCEEDED_ERR</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 cause the application to
+ exceed its storage quota.
</td>
</tr>
<tr>
- <td>SECURITY_ERR</td><td>2</td>
+ <td><dfn>SecurityError</dfn></td>
<td>
- <a>user agent</a> MAY use this code if:
<ul>
- <li> it is determined that certain files are unsafe for
- access within a Web application</li>
- <li>it is determined that too many calls are being made on
- file resources</li>
+ <li>A required file was unsafe for access within a Web
+ application</li>
+ <li>Too many calls are being made on filesystem
+ resources</li>
</ul>
This is a security error code to be used in situations not
covered by any other error codes.
</td>
</tr>
<tr>
- <td>SYNTAX_ERR</td><td>8</td>
- <td>
- This error code is not used in this specification; it is
- included here only for completeness, as it is used in
- [[!FILE-WRITER]].
- </td>
- </tr>
- <tr>
- <td>TYPE_MISMATCH_ERR</td><td>11</td>
+ <td><dfn>TypeMismatchError</dfn></td>
<td>
- <a>user agent</a> MUST use this code when the user has
- attempted to look up a file or directory, but the Entry
- found is of the wrong type [e.g. is a DirectoryEntry when the
- user requested a FileEntry].
+ The user has attempted to look up a file or directory, but the
+ Entry found is of the wrong type [e.g. is a DirectoryEntry
+ when the user requested a FileEntry].
</td>
</tr>
</tbody>
@@ -1690,11 +1478,6 @@
or existence would violate these rules. The implementation MUST NOT
accept a noncompliant path where it designates the new name of a file or
directory to be moved, copied, or created.
- <div class='issue'>
- <p>
- TODO(ericu): Spec the exception given for noncompliant paths.
- </p>
- </div>
</p>
<section>
<h2>Case-sensitivity</h2>
Received on Wednesday, 7 March 2012 22:47:23 UTC