Web Database
- - -Editor's Draft 22 August 2009
- --
+
+
- This Version: +
- http://www.w3.org/TR/2009/WD-webdatabase-20090910/
- Latest Published Version:
- http://www.w3.org/TR/webdatabase/ - :ZZZ -->
- Latest Editor's Draft: +
- Latest Editor's Draft:
- http://dev.w3.org/html5/webdatabase/
The W3C Web Apps Working Group is the W3C working group responsible for this specification's progress along the W3C Recommendation track. - - - This specification is the 22 August 2009 Editor's Draft. - + This specification is the 10 September 2009 First Public Working Draft. +
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables @@ -270,8 +266,7 @@
- 8.1 DNS spoofing attacks @@ -383,7 +378,7 @@ prepareDatabase(function(db) { scripts in Web applications, and does not necessarily imply the existence of an actual
-
If no database with the given name from the origin origin exists, then create the database and let - created be true. Otherwise, let created be false.
+ created be true. If a callback was passed to + the method, then set the new database's version to the empty + string. Otherwise, set the new database's version to the given + database version.
Document object or of any other
Node objects as defined in the DOM Core
- specifications. [DOMCORE]A DOM attribute is said to be getting when its value is + specifications. [DOMCORE]
An IDL attribute is said to be getting when its value is being retrieved (e.g. by author script), and is said to be setting when a new value is assigned to it.
The term "JavaScript" is used to refer to ECMA262, rather than
the official term ECMAScript, since the term JavaScript is more
@@ -456,11 +451,13 @@ interface Dat
If a callback was passed to the method, then let the database's - version be the empty string. Otherwise, let its version be the - given database version
+Otherwise, if a database with the given name already exists, + let created be false.
A future version of this specification will probably define the exact SQL subset required in more detail.
4.3 Asynchronous database API
interface Database {
- void transaction(in SQLTransactionCallback callback, optional in SQLTransactionErrorCallback errorCallback, optional in SQLVoidCallback successCallback);
- void readTransaction(in SQLTransactionCallback callback, optional in SQLTransactionErrorCallback errorCallback, optional in SQLVoidCallback successCallback);
+ void transaction(in SQLTransactionCallback callback, in optional SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
+ void readTransaction(in SQLTransactionCallback callback, in optional SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
readonly attribute DOMString version;
- void changeVersion(in DOMString oldVersion, in DOMString newVersion, in SQLTransactionCallback callback, in SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
+ void changeVersion(in DOMString oldVersion, in DOMString newVersion, in optional SQLTransactionCallback callback, in optional SQLTransactionErrorCallback errorCallback, in optional SQLVoidCallback successCallback);
};
[Callback=FunctionOnly, NoInterfaceObject]
@@ -640,14 +637,15 @@ interface changeVersion()
method.
- ...and the mode being read/write.
4.3.1 Executing SQL statements
The transaction(),
+
...and the mode being read/write.
If any of the optional arguments are omitted, then they must be
+ treated as if they were null.
4.3.1 Executing SQL statements
The transaction(),
readTransaction(),
and changeVersion()
methods invoke callbacks with SQLTransaction
objects.
typedef sequence<any> ObjectArray;
interface SQLTransaction {
- void executeSql(in DOMString sqlStatement, optional in ObjectArray arguments, optional in SQLStatementCallback callback, optional in SQLStatementErrorCallback errorCallback);
+ void executeSql(in DOMString sqlStatement, in optional ObjectArray arguments, in optional SQLStatementCallback callback, in optional SQLStatementErrorCallback errorCallback);
};
[Callback=FunctionOnly, NoInterfaceObject]
@@ -710,19 +708,14 @@ interface changeVersion()
method.)
- Queue a task to invoke the transaction
- callback with the aforementioned SQLTransaction
- object as its only argument, and wait for that task to be
- run.
If the transaction callback is not null, queue
+ a task to invoke the transaction callback with the
+ aforementioned SQLTransaction object as its only
+ argument, and wait for that task to be run.
If the callback couldn't be called (e.g. it was null), or if
- the callback was invoked and raised an exception, jump to the last
+
If the callback raised an exception, jump to the last
step.
While there are any statements queued up in the transaction,
perform the following steps for each queued up statement in the
transaction, oldest first. Each statement has a statement,
@@ -741,11 +734,11 @@ interface SQLResultSet object that represents
the result of the statement.
If the statement has a result set callback, queue a
- task to invoke it with the SQLTransaction
- object as its first argument and the new
- SQLResultSet object as its second argument, and wait
- for that task to be run.
If the statement has a result set callback that is not
+ null, queue a task to invoke it with the
+ SQLTransaction object as its first argument and the
+ new SQLResultSet object as its second argument, and
+ wait for that task to be run.
If the callback was invoked and raised an exception, jump
to the last step in the overall steps.
If the statement had an associated error callback, then
- queue a task to invoke that error callback with the
- SQLTransaction object and a newly constructed
- SQLError object that represents the error that
- caused these substeps to be run as the two arguments,
+
If the statement had an associated error callback that is
+ not null, then queue a task to invoke that error
+ callback with the SQLTransaction object and a newly
+ constructed SQLError object that represents the
+ error that caused these substeps to be run as the two arguments,
respectively, and wait for the task to be run.
If the error callback returns false, then move on to the
@@ -790,24 +783,24 @@ interface SQLError object
- that represents the last error to have occurred in this
- transaction. Rollback the transaction. Any still-pending statements
- in the transaction are discarded.
SQLError object that represents the last error to have
+ occurred in this transaction. Rollback the transaction. Any
+ still-pending statements in the transaction are discarded.
The task source for these tasks is the database
- access task source.
4.4 Synchronous database API
interface DatabaseSync {
+ The task source for these tasks is the database access task
+ source.
4.4 Synchronous database API
interface DatabaseSync {
void transaction(in SQLTransactionSyncCallback callback);
void readTransaction(in SQLTransactionSyncCallback callback);
readonly attribute DOMString version;
- void changeVersion(in DOMString oldVersion, in DOMString newVersion, in SQLTransactionSyncCallback callback);
+ void changeVersion(in DOMString oldVersion, in DOMString newVersion, in optional SQLTransactionSyncCallback callback);
};
[Callback=FunctionOnly, NoInterfaceObject]
@@ -861,14 +854,8 @@ interface Error code
2.)
- If the third argument is null, rollback the transaction,
- throw a SQLException exception, and abort these steps.
- (Error code
- 0.)
Invoke the callback given by the third argument, passing it
- the transaction object as its only
- argument.
If the third argument is not null, invoke the callback given
+ by the third argument, passing it the transaction object as its only argument.
Mark the SQLTransactionSync object as stale.
@@ -911,10 +898,11 @@ interface 4.4.1 Executing SQL statementsThe transaction(), readTransaction(),
and changeVersion()
- methods return SQLTransactionSync objects.
// typedef sequence<any> ObjectArray;
+ methods invoke callbacks that are passed
+ SQLTransactionSync objects.// typedef sequence<any> ObjectArray;
interface SQLTransactionSync {
- SQLResultSet executeSql(in DOMString sqlStatement, optional in ObjectArray arguments);
+ SQLResultSet executeSql(in DOMString sqlStatement, in optional ObjectArray arguments);
};
A SQLTransactionSync object is initially fresh, but it will be marked as stale
once it has been committed or rolled back.
When the executeSql(sqlStatement, arguments) method is invoked, the user
agent must run the following algorithm:
If the SQLTransactionSync object is stale, then throw an INVALID_STATE_ERR
@@ -1002,10 +990,10 @@ interface S
const unsigned short TIMEOUT_ERR = 7;
readonly attribute unsigned short code;
readonly attribute DOMString message;
-};
The code DOM
+};
The code IDL
attribute must return the most appropriate code from the table
below.
The message
- DOM attribute must return an error message describing the error
+ IDL attribute must return an error message describing the error
encountered. The message should be localized to the user's
language.
Errors in the synchronous database API are reported using
SQLException exceptions:
exception SQLException {
@@ -1020,8 +1008,8 @@ interface S
unsigned short code;
DOMString message;
};The code
- DOM attribute must return the most appropriate code from the table
- below.
The message DOM
+ IDL attribute must return the most appropriate code from the table
+ below.
The message IDL
attribute must return an error message describing the error
encountered. The message should be localized to the user's
language.
The error codes are as follows:
Constant
@@ -1140,14 +1128,17 @@ interface S
Treating persistent storage as cookies
- User agents should present the
- database feature
+
If users attempt to protect their privacy by clearing cookies
+ without also clearing data stored in the
+
+ database
- to the user in a way that does not distinguish them from HTTP
- session cookies. [RFC2109] [COOKIES]
- This might encourage users to view such storage with healthy
- suspicion.
+ feature, sites can defeat those attempts by using the two features
+ as redundant backup for each other. User agents should present the
+ interfaces for clearing these in a way that helps users to
+ understand this possibility and enables them to delete data in all
+ persistent storage features simultaneously. [COOKIES]
@@ -1204,12 +1195,7 @@ interface S
retroactively). This information can then be shared with other
sites, using using visitors' IP addresses and other user-specific
data (e.g. user-agent headers and configuration settings) to combine
- separate sessions into coherent user profiles.7.2 Cookie resurrection
If the user interface for persistent storage presents data in the
- persistent storage features described in this specification
- separately from data in HTTP session cookies, then users are likely
- to delete data in one and not the other. This would allow sites to
- use the two features as redundant backup for each other, defeating a
- user's attempts to protect his privacy.
7.3 Sensitivity of data
User agents should treat persistently stored data as potentially
+ separate sessions into coherent user profiles.
7.2 Sensitivity of data
User agents should treat persistently stored data as potentially
sensitive; it's quite possible for e-mails, calendar appointments,
health records, or other confidential documents to be stored in this
mechanism.
To this end, user agents should ensure that when deleting data,
@@ -1252,7 +1238,7 @@ interface S
there is little reason to allow Web authors to control the character
encoding used in the disk representation of the data, as all data in
JavaScript is implicitly UTF-16.8.5 SQL injection
Authors are strongly recommended to make use of the ? placeholder feature of the executeSql() method,
- and to never construct SQL statements on the fly.
References
All references are normative unless marked "Non-normative".
- [COOKIES]
+ and to never construct SQL statements on the fly.
References
All references are normative unless marked "Non-normative".
- [COOKIES]
- - HTML
- 5, I. Hickson. WHATWG, August 2009.
-
- - [RFC2109]
- - HTTP State Management
- Mechanism, D. Kristol, L. Montulli. IETF, February 1997.
+ - HTML5,
+ I. Hickson. WHATWG, August 2009.
- [RFC2119]
- Key words for use in
@@ -1304,4 +1287,4 @@ interface S
- Web
IDL, C. McCormack. W3C, July 2009.
-
+