IDBTransaction

Cet article nécessite une relecture technique. Voici comment vous pouvez aider.

Cet article nécessite une relecture rédactionnelle. Voici comment vous pouvez aider.

L'interface IDBTransaction de l'API IndexedDB d'effectuer des transactions asynchrones sur une base de données en utilisant ses gestionnaires d'événements.

Toute lecture et écriture de données se font par des transactions. On prend une connexion à la base de données pour démarrer une transaction dont on réglera le mode (exemple readonly ou readwrite ), afin d' accéder à un magasin d'objets.

On peut également l'utiliser pour annuler les transactions.

Depuis Firefox 40, les transactions IndexedDB diminuent en efficacité pour gagner en efficience (voir bug 1112702.) Auparavant, dans une transaction en readwrite l'événement complete était déclanché seulement lorsque toutes les données étaient écrites sur le disque. Maintenant l'événement complete est déclenché après que l'OS ai envoyé l'ordre d'écrire les données, mais potentiellement avant qu'elles aient été écrites sur le disque. L'événement complete peut ainsi se déclancher plus rapidement qu'auparavant, cependant, il existe une chance infime pour que l'ensemble de la transaction soit perdue si le système d'exploitation plante ou s'il y a une perte de courant avant que les données aient été écites sur le disque. Étant donné que ces événements catastrophiques sont rares la plupart des utilisateurs ne devraient pas avoir à s'en préoccuper davantage.

Si vous devez vous assurer de l'efficacité d'une transaction pour une raison quelconque (par exemple, vous stockez des données critiques qui ne peuvent être recalculé plus tard), vous pouvez forcer l'enregistrement complet sur disque avant de déclencher l'événement complete en utilisant le mode readwriteflush (non standard) expérimentale ( voir IDBDatabase.transaction ). C'est expérimentale, et ne peut être utilisé que si le dom.indexedDB.experimental pref est réglé sur true dans about: config.

Les transactions s'exécute suivant l'ordre de création, et non suivant leur utilisation. Regardez par exemple ceci:

var trans1 = db.transaction("foo", "readwrite");
var trans2 = db.transaction("foo", "readwrite");
trans2.put("2", "key");
trans1.put("1", "key");

Après l'exécution de ce code le magasin d'objets doit contenir la valeur "2", puisque trans2 s'exécute après trans1.

Note : This feature is available in Web Workers.

Méthodes

Hérite de: EventTarget

IDBTransaction.abort
Annule toutes les modifications éffectué par les accès aux magasins d'objets de la transaction puis déclenche l'événement abort.
IDBTransaction.objectStore
Renvoie l' accès à un des magasins d'objets de la transaction.

Propriétés

IDBTransaction.db Lecture seule
Renvoie la connexion à la base de donnée associée à la transaction.
IDBTransaction.mode Lecture seule
Renvoie le mode d'accès aux magasins d'objets de la transaction et à la base de données. La valeur par défaut étant readonly.
IDBTransaction.objectStoreNames Lecture seule
Renvoie la liste des noms des magasins d'objets de la transaction .
IDBTransaction.error Lecture seule
Renvoie un des nombreux types d'erreurs quand la transaction échoue.

Gestionnaires d'événement

IDBTransaction.onabort Lecture seule
S'exécute au déclenchement d'un événement abort, quand la transaction a été annulé avec la méthode abort.
IDBTransaction.oncomplete Lecture seule
S'exécute au déclenchement d'un événement complete quand la transaction se termine avec succès.
IDBTransaction.onerror Lecture seule
S'exécute au déclenchement d'un événement error quand la transaction échoue.

Constantes

Obsolète depuis Gecko 13 (Firefox 13 / Thunderbird 13 / SeaMonkey 2.10)
Cette fonctionnalité a été supprimée des standards du Web. Bien que quelques navigateurs puissent encore la supporter, elle est en cours d'éradication. Ne l'utilisez ni dans d'anciens projets, ni dans de nouveaux. Les pages et applications Web l'utilisant peuvent cesser de fonctionner à tout moment.

Pour Gecko 25+ ces constantes ne sont plus disponibles. Vous devez utiliser directement leurs valeurs. (bug 888598)

Les transactions peuvent avoir l'un de ces modes:

Constante Valeur Déscription
READ_ONLY

"readonly"

(0 dans Chrome)

permet de prendre des objets dans les magasins d'objets, de lire les index et de faire des curseurs.

READ_WRITE

"readwrite"

(1 dans Chrome)

Permet en plus de que l'on peut faire en readonly, d'ajouter et mettre à jour des objets dans les magasins d'objets.
VERSION_CHANGE

"versionchange"

(2 dans Chrome)

Permet toute les opérations, y compris celles qui suppriment ou ajoutent des magasins d'objets ou des index. Ce mode met à jour le numéro de version de la base de données, il se sert au début de IDBDatabase.setVersion. Les transactions dans ce mode ne peuvent pas fonctionner en même temps que d'autres.
??? readwriteflush

Depuis Firefox 40, si vous devez vous assurer de l'efficacité d'une transaction pour une raison quelconque (par exemple, vous stockez des données critiques qui ne peuvent être recalculé plus tard), vous pouvez forcer l'enregistrement complet sur disque avant de déclencher l'événement complete en utilisant le mode readwriteflush (non standard) expérimentale ( voir IDBDatabase.transaction ). C'est expérimentale, et ne peut être utilisé que si le dom.indexedDB.experimental pref est réglé sur true dans about: config.

Même si ces constantes sont désormais obsolètes, vous pouvez toujours les utiliser pour assurer la compatibilité descendante si nécessaire (dans Chrome the change was made in version 21). Vous devez metre ce code dans le cas où l'objet n'est plus disponible:

var myIDBTransaction = window.IDBTransaction || window.webkitIDBTransaction || { READ_WRITE: "readwrite" };

Exemple

Dans le code suivant, on ouvre une connexion à la base de donnée. Sur cette connexion on démarre une transaction en lecture/écriture pour accéder au magasin d'objets "toDoList" et  ajouter un enregistrement. Notez également les gestionnaires d'événements oncomplete et onerror de la transaction qui affiche sur la page le résultat de la transaction.

//Connexion à la base de données
var DBOpenRequest = window.indexedDB.open("toDoList", 4);

DBOpenRequest.onsuccess = function(event) {
	note.innerHTML += 'Connexion établie.'; 
  
	//Affecte la connexion à la variable db. 
	db = DBOpenRequest.result; 

	// Exécutez la fonction addData () pour emmagasiné les données dans la base
	addData(); 
};
function addData() { 
	// Un nouvel objet prêt à être emmagasiné
	newItem = [ { taskTitle: "Walk dog", hours: 19, minutes: 30, day: 24, month: "December", year: 2013, notified: "no" } ]; 
	
	// Ouvre une transaction de lecture / écriture  prête au traitement des données sur la connexion
	var transaction = db.transaction(["toDoList"], "readwrite"); 
	
	// En cas de succès de l'ouverture de la transaction 
	transaction.oncomplete = function(event) { 
		note.innerHTML += '<li>Transaction complété : modification de la base de données terminée.</li>'; 
	}; 
	// En  cas d'échec de l'ouverture de la transaction 
	transaction.onerror = function(event) { 
		note.innerHTML += '<li>L\'erreur: "' + transaction.error +'" c\'est produite échec de la transaction.</li>';  
	}; 
	
	// Ouvre l'accès au un magasin "toDoList" de la transaction
	var objectStore = transaction.objectStore("toDoList"); 
	
	// Ajoute un enregistrement
	var objectStoreRequest = objectStore.add(newItem[0]); 
	objectStoreRequest.onsuccess = function(event) { 
		// signale l'ajout de l'enregistrement
		note.innerHTML += '<li>Enregistrement ajouté.</li>'; 
	};
 };
 

Pour un exemple de travail complet, voir notre To-do Notifications app (view example live).

Spécifications

Spécification Statut Commentaire
Indexed Database API
La définition de 'IDBTransaction' dans cette spécification.
Recommendation Définition initial

Compatibilité avec les navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support basique 23webkit
24[1]
10 moz
16.0 (16.0)
10, en partie 15 7.1
Disponible dans workers (Oui) 37.0 (37.0) ? (Oui) ?
propriété objectStoreNames 48.0 Pas de support Pas de support Pas de support Pas de support
Fonctionnalité Android Android Webview Firefox Mobile (Gecko) Firefox OS IE Phone Opera Mobile Safari Mobile Chrome pour Android
Support basique 4.4 (Oui) 22.0 (22.0) 1.0.1 10 22 8 (Oui)
Disponible dans workers (Oui) (Oui) 37.0 (37.0) (Oui) ? (Oui) ? (Oui)
propriété objectStoreNames Pas de support 48.0 Pas de support Pas de support Pas de support Pas de support Pas de support 48.0
  • [1] Les anciennes versions de Chrome sérialisent toutes les transactions. Donc, même si vous avez seulement transactions en lecture seule et aucune transaction de lecture-écriture, vos transactions sont exécutées une à la fois. Toutes les transactions ultérieures ne sont pas exécutées jusqu'à ce que toutes les transactions en lecture seule soient terminées. Pour le statut, voir bug 64076.

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : gadgino
 Dernière mise à jour par : gadgino,