diff options
Diffstat (limited to 'LayoutTests/storage/indexeddb/tutorial.html')
| -rw-r--r-- | LayoutTests/storage/indexeddb/tutorial.html | 433 |
1 files changed, 433 insertions, 0 deletions
diff --git a/LayoutTests/storage/indexeddb/tutorial.html b/LayoutTests/storage/indexeddb/tutorial.html new file mode 100644 index 0000000..2e7e41f --- /dev/null +++ b/LayoutTests/storage/indexeddb/tutorial.html @@ -0,0 +1,433 @@ +<html><title>IndexedDB Tutorial</title> +<script> + +// This is a tutorial that highlights many of the features of IndexedDB along witha number of +// caveats that currently exist in Chromium/WebKit but which will hopefully be improved upon +// over time. +// +// The latest version of the spec can be found here: +// http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html but note that there are quite a +// few bugs currently opened against it and some major unresolved issues (like whether dynamic +// transactions should be in for v1). Many of the bugs are filed here: +// http://www.w3.org/Bugs/Public/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&component=Indexed+Database+API&longdesc_type=allwordssubstr&longdesc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&email2=&bug_id_type=anyexact&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&known_name=IndexedDB&query_based_on=IndexedDB&field0-0-0=noop&type0-0-0=noop&value0-0-0= +// Discussion happens on public-webapps@w3.org +// +// Although not user friendly, additional capabilities and example code can be found in the +// tests for IndexedDB which are here: +// http://trac.webkit.org/browser/trunk/LayoutTests/storage/indexeddb +// +// This document is currently maintained by Jeremy Orlow <jorlow@chromium.org> + + +// This is not an ideal layout test since it doesn't verify things as thoroughly as it could, +// but adding such content would make it much more cluttered and thus wouldn't serve its primary +// goal of teaching people IndexedDB. That said, it does have a good amount of coverage and +// serves as a living document describing what's expected to work and how within WebKit so it +// seems well worth having checked in. +if (window.layoutTestController) + layoutTestController.dumpAsText(true); + + +function setup() +{ + // As this API is still experimental, it's being shipped behind vendor specific prefixes. + if ('webkitIndexedDB' in window) { + indexedDB = webkitIndexedDB; + IDBCursor = webkitIDBCursor; + IDBKeyRange = webkitIDBKeyRange; + IDBTransaction = webkitIDBTransaction; + } + + // This tutorial assumes that Mozilla and WebKit match each other which isn't true at the + // moment, but we can hope it'll become true over time. + if ('moz_indexedDB' in window) { + indexedDB = moz_indexedDB; + // Not implemented by them yet. I'm just guessing what they'll be. + IDBCursor = moz_IDBCursor; + IDBKeyRange = moz_IDBKeyRange; + IDBTransaction = moz_IDBTransaction; + } +} + +function log(txt) +{ + document.write(txt + "<br>"); +} + +function logError(txt) +{ + log("<font color=red>" + txt + "</font>"); +} + +function start() +{ + setup(); + + // This is an example of one of the many asynchronous commands in IndexedDB's async interface. + // Each returns an IDBRequest object which has "success" and "error" event handlers. You can use + // "addEventListener" if you'd like, but I'm using the simpler = syntax. Only one or the other + // will fire. You're guaranteed that they won't fire until control is returned from JavaScript + // execution. + var request = indexedDB.open("myDB", "This is a description of the database."); // Chromium/WebKit doesn't yet require the description, but it will soon. + request.onsuccess = onOpen; + request.onerror = unexpectedError; +} + +function unexpectedError() +{ + // If an asynchronous call results in an error, an "error" event will fire on the IDBRequest + // object that was returned and the event's code and message attributes will be populated with + // the correct values. + logError("Error " + event.code + ": " + event.message); + + // Unfortunately, Chromium/WebKit do not implicitly abort a transaction when an error occurs + // within one of its async operations. In the future, when an error occurs and the event is + // not canceled, the transaction will be aborted. + if (currentTransaction) + currentTransaction.abort(); +} + +function onOpen() +{ + // If an asynchronous call results in success, a "success" event will fire on the IDBRequest + // object that was returned and the call's result will be placed in the event's "result" + // attribute. In some cases, the expected result will be null. + window.db = event.result; + + // The IDBDatabase object has a "version" attribute. This can only be set by calling + // "setVersion" on the database and supplying a new version. This also starts a new + // transaction which is very special. There are many details and gotchas surrounding + // setVersion which we'll get into later. + if (db.version == "1.0") { + // We could skip setting up the object stores and indexes if this were a real application + // that wasn't going to change things without changing the version number. But since this + // is both a tutorial and a living document, we'll go on and set things up every time we run. + } + var request = db.setVersion("1.0"); + request.onsuccess = onSetVersion; + request.onerror = unexpectedError; +} + +function onSetVersion() +{ + // We are now in a setVersion transaction. Such a transaction is the only place where one + // can add or remove indexes and objectStores. The result (property of event) is an + // IDBTransaction object that has "complete", "abort", and "timeout" event handlers which tell + // us when the transaction has committed, aborted, or timed out. + window.currentTransaction = event.result; + currentTransaction.oncomplete = onSetVersionComplete; + currentTransaction.onabort = unexpectedAbort; + + // Delete existing object stores. + while (db.objectStores.length) + db.removeObjectStore(db.objectStores[0]); + + // Now that we have a blank slate, let's create an objectStore. An objectStore is simply an + // ordered mapping of keys to values. We can iterate through ranges of keys or do individual + // lookups. ObjectStores don't have any schema. + // + // Keys can be integers, strings, or null. (The spec also defines dates and there's talk of + // handling arrays, but these are not implemented yet in Chromium/WebKit.) Values can be + // anything supported by the structured clone algorithm + // (http://dev.w3.org/html5/spec/Overview.html#internal-structured-cloning-algorithm) which + // is a superset of what can be expressed in JSON. (Note that Chromium/WebKit does not fully + // implement the structured clone algorithm yet, but it definitely handles anything JSON + // serializable.) + // + // There are two types of objectStores: ones where the path is supplied manually every time a + // value is inserted and those with a "key path". A keyPath is essentially a JavaScript + // expression that is evaluated on every value to extract a key. For example, if you pass in + // the value of "{fname: 'john', lname: 'doe', address: {street: 'Buckingham Palace", number: + // 76}, siblings: ["Nancy", "Marcus"], id: 22}" and an objectStore has a keyPath of "id" then + // 22 will be the key for this value. In objectStores, each key must be unique. + // + // Note that the exact syntax allowed for keyPaths is not yet well specified, but + // Chromium/WebKit currently allows paths that are multiple levels deep within an object and + // allows that to be intermixed with array dereferences. So, for example, a key path of + // "address.number" or "siblings[0]" would be legal (provided every entry had an address with + // a number attribute and at least one sibling). You can even go wild and say + // "foo[0][2].bar[0].baz.test[1][2][3]". It's possible this will change in the future though. + // + // If you set autoIncrement (the third optional parameter), IndexedDB will generate a key + // for your entry automatically. And if you have a keyPath set, it'll set the value at + // the location of the keyPath _in the database_ (i.e. it will not modify the value you pass + // in to put/add). Unfortunately autoIncrement is not yet implemented in Chromium/WebKit. + // + // Let's now create an objectStore for people. We'll supply a key path in this case. + var objectStore = db.createObjectStore("people", "id"); + + // Notice that it returned synchronously. The rule of thumb is that any call that touches (in + // any way) keys or values is asynchronous and any other call (besides setVersion and open) are + // asynchronous. + // + // Now let's create some indexes. Indexes allow you to create other keys via key paths which + // will also point to a particular value in an objectStore. In this example, we'll create + // indexes for a persons first and last name. Indexes can optionally be specified to not be + // unique, which is good in the case of names. The first parameter is the name of the index. + // Second is the key path. The third specifies uniqueness. + var fname = objectStore.createIndex("fname", "fname", false); + var lname = objectStore.createIndex("lname", "lname", false); + + // Note that if you wanted to delete these indexes, you can either call objectStore.removeIndex + // or simply delete the objectStores that own the indexes. (Note that removeObjectStore and + // removeIndex may be changed to deleteObjectStore and deleteIndex in the future.) + // + // If we wanted to, we could populate the objectStore with some data here or do anything else + // allowed in a normal (i.e. non-setVersion) transaction. This is useful so that data migrations + // can be atomic with changes to the objectStores/indexes. + // + // Because we haven't actually made any new asynchronous requests, this transaction will + // start committing as soon as we leave this function. This will cause oncomplete event handler + // for the transaction will fire shortly after. IndexedDB transactions commit whenever control is + // returned from JavaScript with no further work being queued up against the transaction. This + // means one cannot call setTimeout, do an XHR, or anything like that and expect my transaction + // to still be around when that completes. + +} + +function unexpectedAbort() +{ + logError("A transaction aborted unexpectedly!"); +} + +function onSetVersionComplete() +{ + // Lets create a new transaction and then not schedule any work on it to watch it abort itself. + // Transactions (besides those created with setVersion) are created synchronously. All three + // parameters are optional for transaction. + // + // The first specifies which object stores to lock. The spec specifies "dynamic transactions" + // which don't require this and which have finer grained locks, but no one yet supports this and + // it may even be dropped from the first version of the spec, so I don't suggest you rely on it. + // Chromium/WebKit also does not yet support anything finer grained than database level locking, + // so in this tutorial we'll just pass in the empty array which means "lock the world". + // + // The second parameter specifies the locking mode. The default is READ_ONLY (i.e. a shared lock). + // That's fine for this case, but later we'll ask for IDBTransaction.READ_WRITE. At the moment, + // Chromium/WebKit pretends every transaction is READ_WRITE, which is kind of bad. (Note that + // SNAPSHOT_READ will soon be removed from the spec.) + // + // The last parameter is the timeout length. At the moment, Chromium/WebKit defaults to 0 which + // means never, but it's possible we'll change this in the future, so set it if you really care. + window.currentTransaction = db.transaction([], IDBTransaction.READ_WRITE, 0); + currentTransaction.oncomplete = unexpectedComplete; + currentTransaction.onabort = onTransactionAborted; + + // Verify that "people" is the only object store in existance. The objectStores attribute is + // a DOMStringList which is somewhat like an array. + var objectStoreList = db.objectStores; + if (objectStoreList.length != 1 + || !objectStoreList.contains("people") + || objectStoreList.item(0) != "people" + || objectStoreList[0] != "people") { + logError("Something went wrong."); + } + + // Let's grab a handle to the objectStore. This handle is tied to the transaction that creates + // it and thus becomes invalid once this transaction completes. + var objectStore = currentTransaction.objectStore("people"); + if (!objectStore) + logError("Something went wrong."); + + // If we try to grab an objectStore that doesn't exist, IndexedDB throws an exception. + try { + currentTransaction.objectStore("x"); + logError("Something went wrong."); + } catch (e) { + // Note that the error messages in exceptions are mostly lies at the moment. The reason is + // that the spec re-uses exception codes for existing exceptions and there's no way we can + // disambiguate between the two. The best work-around at the moment is to look at + // http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html#the-idbdatabaseexception-interface + // to figure out what the number corresponds to. We will try to resolve this soon in spec-land. + } + + // Verify that fname and lname are the only indexes in existance. + if (objectStore.indexNames.length != 2) + logError("Something went wrong."); + + // Note that no async actions were ever queued up agianst our transaction, so it'll abort once + // we leave this context. +} + +function unexpectedComplete() +{ + logError("A transaction committed unexpectedly!"); +} + +function onTransactionAborted() +{ + // Now let's make a real transaction and a person to our objectStore. + window.currentTransaction = db.transaction(["people"], IDBTransaction.READ_WRITE, 0); + currentTransaction.onabort = unexpectedAbort; + + var people = currentTransaction.objectStore("people"); + var request = people.put({fname: 'John', lname: 'Doe', id: 1}); // If our objectStore didn't have a key path, the second parameter would have been the key. + request.onsuccess = onPutSuccess; + request.onerror = unexpectedError; + + // While we're at it, why not add a few more? Multiple queued up async commands will be executed + // sequentially (though there is talk of prioritizing cursor.continue--see discussion below). Since + // we don't care about the individual commands' successes, we'll only bother with on error handlers. + // + // Remember that our implementation of unexpectedError should abort the "currentTransaction" in the + // case of an error. (Though no error should occur in this case.) + people.put({fname: 'Jane', lname: 'Doe', id: 2}).onerror = unexpectedError; + people.put({fname: 'Philip', lname: 'Fry', id: 3}).onerror = unexpectedError; + + // Not shown here are the .remove method (which is soon to be renamed .delete) and .add (which is + // like .put except that it fires an onerror if the element already exists). +} + +function onPutSuccess() +{ + // Result is the key used for the put. + if (event.result !== 1) + logError("Something went wrong."); + + // We should be able to request the transaction via event.transaction from within any event handler + // (like this one) but this is not yet implemented in Chromium/WebKit. As a work-around, we use the + // global "currentTransaction" variable we set above. + currentTransaction.oncomplete = onPutTransactionComplete; +} + +function onPutTransactionComplete() +{ + // OK, now let's query the people objectStore in a couple different ways. First up, let's try get. + // It simply takes in a key and returns a request whose result will be the value. + window.currentTransaction = db.transaction(["people"], IDBTransaction.READ_WRITE, 0); + currentTransaction.onabort = unexpectedAbort; + + var people = currentTransaction.objectStore("people"); + var request = people.get(1); + request.onsuccess = onGetSuccess; + request.onerror = unexpectedError; + + // Note that multiple objectStore (or index) method calls will return different objects (that still + // refer to the same objectStore/index on disk). + people.someProperty = true; + if (currentTransaction.objectStore("people").someProperty) + logError("Something went wrong."); +} + +function onGetSuccess() +{ + if (event.result.fname !== "John") + logError("Something went wrong."); + + // Events have a .source attribute which is the object that fired the event. In this case, it's our + // "people" objectStore object. + var people = event.source; + + // Now let's try opening a cursor from id 1 (exclusive/open) to id 3 (inclusive/closed). This means + // we'll get the objects for ids 2 and 3. You can also create cursors that are only right or only + // left bounded or ommit the bound in order to grab all objects. You can also specify a direction + // which can be IDBCursor.NEXT (default) for the cursor to move forward, NEXT_NO_DUPLICATE to only + // return unique entires (only applies to indexes with unique set to false), PREV to move backwards, + // and PREV_NO_DUPLICATE. + var keyRange = IDBKeyRange.bound(1, 3, true, false); + var request = people.openCursor(keyRange, IDBCursor.NEXT); + request.onsuccess = onObjectStoreCursor; + request.onerror = unexpectedError; +} + +function onObjectStoreCursor() +{ + // The result of openCursor is an IDBCursor object or null if there are no (more--see below) + // records left. + var cursor = event.result; + if (cursor === null) { + cursorComplete(event.source); // The soruce is still an objectStore. + return; + } + + // We could use these values if we wanted to. + var key = cursor.key; + var value = cursor.value; + + // cursor.count is probably going to be removed. + // cursor.update and .remove are not yet implemented in Chromium/WebKit. + + // cursor.continue will reuse the same request object as what openCursor returned. In the future, + // we MAY prioritize .continue() calls ahead of all other async operations queued up. This will + // introduce a level of non-determinism but should speed things up. Mozilla has already implemented + // this non-standard behavior, from what I've head. + event.result.continue(); +} + +function cursorComplete(objectStore) +{ + // While still in the same transaction, let's now do a lookup on the lname index. + var lname = objectStore.index("lname"); + + // Note that the spec has not been updated yet, but instead of get and getObject, we now + // have getKey and get. The former returns the objectStore's key that corresponds to the key + // in the index. get returns the objectStore's value that corresponds to the key in the + // index. + var request = lname.getKey("Doe"); + request.onsuccess = onIndexGetSuccess; + request.onerror = unexpectedError; +} + +function onIndexGetSuccess() +{ + // Because we did "getKey" the result is the objectStore's key. + if (event.result !== 1) + logError("Something went wrong."); + + // Similarly, indexes have openCursor and openKeyCursor. We'll try a few of them with various + // different IDBKeyRanges just to demonstrate how to use them, but we won't bother to handle + // the onsuccess conditions. + var lname = event.source; + lname.openCursor(IDBKeyRange.leftBound("Doe", false), IDBCursor.NEXT_NO_DUPLICATE); + lname.openCursor(null, IDBCursor.PREV_NO_DUPLICATE); + lname.openCursor(IDBKeyRange.rightBound("ZZZZ")); + lname.openCursor(IDBKeyRange.only("Doe"), IDBCursor.PREV); + lname.openCursor(); + lname.openKeyCursor(); + + // We should be able to request the transaction via event.transaction from within any event handler + // (like this one) but this is not yet implemented in Chromium/WebKit. As a work-around, we use the + // global "currentTransaction" variable we set above. + currentTransaction.oncomplete = onAllDone; +} + +function onAllDone() +{ + log("Everything worked!"); +} + +// The way setVersion is supposed to work: +// To keep things simple to begin with, objectStores and indexes can only be created in a setVersion +// transaction and one can only run if no other connections are open to the database. This is designed +// to save app developers from having an older verison of a web page that expects a certain set of +// objectStores and indexes from breaking in odd ways when things get changed out from underneith it. +// In the future, we'll probably add a more advanced mechanism, but this is it for now. +// Because a setVersion transaction could stall out nearly forever until the user closes windows, +// we've added a "blocked" event to the request object returned by setVersion. This will fire if the +// setVersion transaction can't begin because other windows have an open connection. The app can then +// either pop something up telling the user to close windows or it can tell the other windows to call +// .close() on their database handle. .close() halts any new transactions from starting and waits for +// the existing ones to finish. It then closes the connection and any indexedDB calls afterwards are +// invalid (they'll probably throw, but this isn't specified yet). We may specify .close() to return +// an IDBRequest object so that we can fire the onsuccess when the close completes. +// Once inside a setVersion transaction, you can do anything you'd like. The one connection which +// was allowed to stay open to complete the setVersion transaction will stay alive. Multiple +// setVersion transactions can be queued up at once and will fire in the order queued (though +// this obviously only works if they're queued in the same page). +// +// The current status of setVersion in Chromium/WebKit: +// In Chromium/WebKit we currently don't enforce the "all connections must be closed before a +// setVersion transaction starts" rule. We also don't implement database.close() or have a blocked +// event on the request .setVersion() returns. +// +// The current status of workers: +// Chromium/WebKit do not yet support workers using IndexedDB. Support for the async interface +// will likely come before the sync interface. For now, a work-around is using postMessage to tell +// the page what to do on the worker's behalf in an ad-hoc manner. Anything that can be serialized +// to disk can be serialized for postMessage. + +</script> +<body onload="start()"> +Please view source for more information on what this is doing and why...<br><br> +</body> +</html> |