Capítulo 11 API IndexedDB
La API estudiada en el capítulo anterior es útil para almacenamiento de pequeñas cantidades de datos, pero cuando se trata de grandes cantidades de datos estructurados debemos recurrir a un sistema de base de datos. La API IndexedDB es la solución provista por HTML5 a este respecto.
IndexedDB es un sistema de base de datos destinado a almacenar información indexada en el ordenador del usuario. Fue desarrollada como una API de bajo nivel con la intención de permitir un amplio espectro de usos. Esto la convierte en una de las API más poderosa de todas, pero también una de las más complejas. El objetivo fue proveer la estructura más básica posible para permitir a los desarrolladores construir librerías y crear interfaces de alto nivel para satisfacer necesidades específicas. En una API de bajo nivel como esta tenemos que hacernos cargo de cada aspecto y controlar las condiciones de cada proceso en toda operación realizada. El resultado es una API a la que la mayoría de los desarrolladores tardará en acostumbrarse y probablemente utilizará de forma indirecta a través de otras librerías populares construidas sobre ella que seguramente surgirán en un futuro cercano.
La estructura propuesta por IndexedDB es también diferente de SQL u otros sistemas de base de datos populares. La información es almacenada en la base de datos como objetos (registros) dentro de lo que es llamado Almacenes de Objetos (tablas). Los Almacenes de Objetos no tienen una estructura específica, solo un nombre e índices para poder encontrar los objetos en su interior. Estos objetos tampoco tienen una estructura definida, pueden ser diferentes unos de otros y tan complejos como necesitemos. La única condición para los objetos es que contengan al menos una propiedad declarada como índice para que sea posible encontrarlos en el Almacén de Objetos.
La base de datos misma es simple. Debido a que cada base de datos es asociada con un ordenador y un sitio web o aplicación, no existen usuarios para agregar o restricciones de acceso que debamos considerar. Solo necesitamos especificar el nombre y la versión, y la base de datos estará lista.
La interface declarada en la especificación para esta API provee el atributo indexedDB y el método open () para crear la base de datos. Este método retorna un objeto sobre el cual dos eventos serán disparados para indicar el éxito o los errores surgidos durante el proceso de creación de la base de datos.
El segundo aspecto que debemos considerar para crear o abrir una base de datos es la versión. La API requiere que una versión sea asignada a la base de datos. Esto es para preparar al sistema para futuras migraciones. Cuando tenemos que actualizar la estructura de una base de datos en el lado del servidor para agregar más tablas o índices, normalmente detenemos el servidor, migramos la información hacia la nueva estructura y luego encendemos el servidor nuevamente. Sin embargo, en este caso la información es contenida del lado del cliente y, por supuesto, el ordenador del usuario no puede ser apagado. Como resultado, la versión de la base de datos debe ser cambiada y luego la información migrada desde la vieja a la nueva versión.
Para trabajar con versiones de bases de datos, la API ofrece la propiedad versión y el método setVersion (). La propiedad retorna el valor de la versión actual y el método asigna un nuevo valor de versión a la base de datos en uso. Este valor puede ser numérico o cualquier cadena de texto que se nos ocurra.
Lo que solemos llamar registros, en IndexedDB son llamados objetos. Estos objetos incluyen propiedades para almacenar e identificar valores. La cantidad de propiedades y cómo los objetos son estructurados es irrelevante. Solo deben incluir al menos una propiedad declarada como índice para poder encontrarlos dentro del Almacén de Objetos.
Los Almacenes de Objetos (tablas) tampoco tienen una estructura específica. Solo el nombre y uno o más índices deben ser declarados en el momento de su creación para poder encontrar objetos en su interior más tarde.
Como podemos ver en la Figura 11-1, un Almacén de Objetos contiene diversos objetos con diferentes propiedades. Algunos objetos tienen una propiedad dvd, otros tienen una propiedad Libro, etc… Cada uno tiene su propia estructura, pero todos deberán tener al menos una propiedad declarada como índice para poder ser encontrados. En el ejemplo de la Figura 11-1, este índice podría ser la propiedad Id.
Para trabajar con objetos y Almacenes de Objetos solo necesitamos crear el Almacén de Objetos, declarar las propiedades que serán usadas como índices y luego comenzar a almacenar objetos en este almacén. No necesitamos pensar acerca de la estructura o el contenido de los objetos en este momento, solo considerar los índices que vamos a utilizar para encontrarlos más adelante en el almacén.
createObjectStore(nombre, clave, autoIncremento) Este método crea un nuevo Almacén de Objetos con el nombre y la configuración declarada por sus atributos. El atributo nombre es obligatorio. El atributo clave declarará un índice común para todos los objetos. Y el atributo autoIncremento es un valor booleano que determina si el Almacén de Objetos tendrá un generador de claves automático. objectStore(nombre) Para acceder a los objetos en un Almacén de Objetos, una transacción debe ser iniciada y el Almacén de Objetos debe ser abierto para esa transacción. Este método abre el Almacén de Objetos con el nombre declarado por el atributo nombre. deleteObjectStore(nombre) Este método destruye un Almacén de Objetos con el nombre declarado por el atributo nombre.
Los métodos createObjectStore() y deleteObjectStore(), así como otros métodos responsables de la configuración de la base de datos, pueden solo ser aplicados cuando la base de datos es creada o mejorada en una nueva versión.
Para encontrar objetos en un Almacén de Objetos necesitamos declarar algunas propiedades de estos objetos como índices. Una forma fácil de hacerlo es declarar el atributo clave en el método createObjectStore(). La propiedad declarada como clave será un índice común para cada objeto almacenado en ese Almacén de Objetos particular. Cuando declaramos el atributo clave, esta propiedad debe estar presente en todos los objetos.
Además del atributo clave podemos declarar todos los índices que necesitemos para un Almacén de Objetos usando métodos especiales provistos para este propósito:
createIndex(nombre, propiedad, único) Este método crea un índice para un Almacén de Objetos específico. El atributo nombre es un nombre con el que identificar al índice, el atributo propiedad es la propiedad que será usada como índice, y unique es un valor booleano que indica si existe la posibilidad de que dos o más objetos compartan el mismo valor para este índice.
index(nombre) Para usar un índice primero tenemos que crear una referencia al índice y luego asignar esta referencia a la transacción. El método index() crea esta referencia para el índice declarado en el atributo nombre. deleteIndex(nombre) Si ya no necesitamos un índice podemos eliminarlo usando este método.
Un sistema de base de datos trabajando en un navegador debe contemplar algunas circunstancias únicas que no están presentes en otras plataformas. El navegador puede fallar, puede ser cerrado abruptamente, el proceso puede ser detenido por el usuario, o simplemente otro sitio web puede ser cargado en la misma ventana, por ejemplo. Existen muchas situaciones en las que trabajar directamente con la base de datos puede causar mal funcionamiento o incluso corrupción de datos. Para prevenir que algo así suceda, cada acción es realizada por medio de transacciones.
El método que genera una transacción se llama transaction () . Para declarar el tipo de transacción, contamos con los siguientes tres atributos:
READ_ONLY Este atributo genera una transacción de solo lectura. Modificaciones no son permitidas.
READ_WRITE Usando este tipo de transacción podemos leer y escribir. Modificaciones son permitidas.
VERSION_CHANGE Este tipo de transacción es solo utilizada para actualizar la versión de la base de datos.
Las más comunes son las transacciones de lectura y escritura. Sin embargo, para prevenir un uso inadecuado, el tipo READ_ONLY (solo lectura) es configurado por defecto. Por este motivo, cuando solo necesitamos obtener información de la base de datos, lo único que debemos hacer es declarar el destino de la transacción (normalmente el nombre del Almacén de Objetos de donde vamos a leer esta información).
Para interactuar con Almacenes de Objetos, leer y almacenar información, la API provee varios métodos:
add(objeto) Este método recibe un par clave/valor o un objeto conteniendo varios pares clave/valor, y con los datos provistos genera un objeto que es agregado al Almacén de Objetos seleccionado. Si un objeto con el mismo valor de índice ya existe, el método add () retorna un error.
put(objeto) Este método es similar al anterior, excepto que si ya existe un objeto con el mismo valor de índice lo sobrescribe. Es útil para modificar un objeto ya almacenado en el Almacén de Objetos seleccionado.
get(clave) Podemos leer un objeto específico del Almacén de Objetos usando este método. El atributo clave es el valor del índice del objeto que queremos leer. delete(clave) Para eliminar un objeto del Almacén de Objetos seleccionado solo tenemos que llamar a este método con el valor del índice del objeto a eliminar.
¡Suficiente con la teoría! Es momento de crear nuestra primera base de datos y aplicar algunos de los métodos ya mencionados en este capítulo. Vamos a simular una aplicación para almacenar información sobre películas. Puede agregar a la base los datos que usted desee, pero para referencia, de aquí en adelante vamos a mencionar los siguientes:
id: tt0068646 nombre: El Padrino fecha: 1972
id: tt0086567 nombre: Juegos de Guerra fecha: 1983
id: tt0111161 nombre: Cadena Perpetua fecha: 1994
id: tt1285016 nombre: La Red Social fecha: 2010
Plantilla
Como siempre, necesitamos un documento HTML y algunos estilos CSS para crear las cajas en pantalla que contendrán el formulario apropiado y la información retornada. El formulario nos permitirá insertar nuevas películas dentro de la base de datos solicitándonos una clave, el título y el año en el que la película fue realizada.
<!DOCTYPE html>
<html lang=»es»>
<head>
<title>IndexedDB API</title>
<link rel=»stylesheet» href=»indexed.css»>
<script src=»indexed.js»></script>
</head>
<body>
<section id=»cajaformulario»>
<form name=»formulario»>
<p>Clave:<br><input type=»text» name=»clave» id=»clave»></p> <p>Título:<br><input type=»text» name=»texto» id=»texto»></p> <p>Año:<br><input type=»text» name=»fecha» id=»fecha»></p>
<p><input type=»button» name=»grabar» id=»grabar»
value=»Grabar»></p>
</form>
</section>
<section id=»cajadatos»>
No hay información disponible </section>
</body>
</html>
Listado 11-1. Plantilla para IndexedDB API.
Los estilos CSS definen las cajas para el formulario y cómo mostrar la información en pantalla:
#caj aformulario{
float: left;
padding: 20px;
border: 1px solid #999999;
}
#caj adatos{ float: left;
width: 400px;
margin-left: 20px;
padding: 20px;
border: 1px solid #999999;
}
#clave, #texto{ width: 200px;
}
#cajadatos > div{
padding: 5px;
border-bottom: 1px solid #999999;
}
Listado 11-2. Estilos para las cajas.
Hágalo usted mismo: Necesitará un archivo HTML para la plantilla del Listado 111, un archivo CSS llamado indexed.css para los estilos del Listado 11-2 y un archivo Javascript llamado indexed.js para introducir todos los códigos estudiados a continuación.
Abriendo la base de datos
Lo primero que debemos hacer en el código Javascript es abrir la base de datos. El atributo indexedDB y el método open () abren la base con el nombre declarado o crean una nueva si no existe:
function iniciar(){
caj adatos=document.getElementByld(‘caj adatos’);
var boton=document.getElementById(‘grabar’);
boton.addEventListener(‘click’, agregarobjeto, false);
if(‘webkitIndexedDB’ in window){
window.indexedDB=window.webkitIndexedDB; window.IDBTransaction=window.webkitIDBTransaction; window.IDBKeyRange=window.webkitIDBKeyRange;
window.IDBCur sor=window.webkitIDBCursor;
}else if(‘mozIndexedDB’ in window){ window.indexedDB=window.mozIndexedDB;
}
var solicitud=indexedDB.open(‘mibase’);
solicitud.addEventListener(‘error’, errores, false);
solicitud.addEventListener(‘success’, crear, false);
}
Listado 11-3. Abriendo la base de datos.
La función iniciar() del Listado 11-3 prepara los elementos de la plantilla y abre la base de datos. La instrucción indexedDB.open() intenta abrir la base de datos con el nombre mibase y retorna el objeto solicitud con el resultado de la operación. Los eventos error o success son disparados sobre este objeto en caso de error o éxito, respectivamente.
Los eventos son una parte importante de esta API. IndexedDB es una API síncrona y asíncrona. La parte síncrona está siendo desarrollada en estos momentos y está destinada a trabajar con la API Web Workers. En cambio, la parte asíncrona está destinada a un uso web normal y ya se encuentra disponible. Un sistema asíncrono realiza tareas detrás de escena y retorna los resultados posteriormente. Con este propósito, esta API dispara diferentes eventos en cada operación. Cada acción sobre la base de datos y su contenido es procesada detrás de escena (mientras el sistema ejecuta otros códigos) y los eventos correspondientes son disparados luego para informar los resultados obtenidos.
Luego de que la API procesa la solicitud para la base de datos, un evento error o success es disparado de acuerdo al resultado y una de las funciones errores() o
crear () es ejecutada para controlar los errores o continuar con la definición de la base de datos, respectivamente.
Antes de comenzar a trabajar en el contenido de la base de datos, debemos seguir algunos pasos para completar su definición. Como dijimos anteriormente, las bases de datos IndexedDB usan versiones. Cuando la base de datos es creada, un valor nuil (nulo) es asignado a su versión. Por lo tanto, controlando este valor podremos saber si la base de datos es nueva o no:
function errores(e){
alert(‘Error: ‘+e.code+’ ‘+e.message);
}
function crear(e){
bd=e.result || e.target.result; if(bd.version==»){
var solicitud=bd.setVersion(‘1.0’);
solicitud.addEventListener(‘error’, errores, false); solicitud.addEventListener(‘success’, crearbd, false);
}
}
Listado 11-4. Declarando la versión y respondiendo a eventos.
Nuestra función errores() es simple (no necesitamos procesar errores para esta aplicación de muestra). En este ejemplo solo usamos los atributos code y message de la interface IDBErrorEvent para generar un mensaje de alerta en caso de error. La función crear (), por otro lado, sigue los pasos correctos para detectar la versión de la base de datos y proveer un valor de versión en caso de que sea la primera vez que la aplicación es ejecutada en este ordenador. La función asigna el objeto result creado por el evento a la variable bd y usa esta variable para representar la base de datos (esta variable se definió como global para referenciar la base de datos en el resto del código).
IMPORTANTE: En este momento algunos navegadores envían el objeto result a través del evento y otros a través del elemento que disparó el evento. Para seleccionar la referencia correcta de forma automática, usamos la lógica e.result || e.target.result. Seguramente usted deberá usar solo uno de estos valores en sus aplicaciones cuando las implementaciones estén listas.
La interface IDBDatabase provee la propiedad version para informar el valor de la versión actual y también provee el método setVersion() para declarar una nueva versión. Lo que hacemos en la función crear() en el Listado 11-4 es detectar el valor actual de la versión de la base de datos y declarar uno nuevo si es necesario (en caso de que el valor sea una cadena de texto vacía). Si la base de datos ya existe, el valor de la propiedad versión será diferente de nuil (nulo) y no tendremos que configurar nada, pero si esta es la primera vez que el usuario utiliza esta aplicación entonces deberemos declarar un nuevo valor para la versión y configurar la base de datos.
El método setVersion() recibe una cadena de texto que puede ser un número o cualquier valor que se nos ocurra, solo debemos estar seguros de que siempre usamos el mismo valor en cada código para abrir la versión correcta de la base de datos. Este método es, así como cualquier otro procedimiento en esta API, asíncrono. La versión será establecida detrás de escena y el resultado será informado al código principal a través de eventos. Si ocurre un error en el proceso, llamamos a la función errores() como lo hicimos anteriormente, pero si la versión es establecida correctamente entonces la función crearbd () es llamada para declarar los Almacenes de Objetos e índices que usaremos en esta nueva versión.
A este punto debemos comenzar a pensar sobre la clase de objetos que vamos a almacenar y cómo vamos a leer más adelante la información contenida en los Almacenes de Objetos. Si hacemos algo mal o queremos agregar algo en la configuración de nuestra base de datos en el futuro deberemos declarar una nueva versión y migrar los datos desde la anterior, por lo que es importante tratar de organizar todo lo mejor posible desde el principio. Esto es debido a que la creación de Almacenes de Objetos e índices solo es posible durante una transacción setVersion.
function crearbd(){
var almacen=bd.createObj ectStore(‘peliculas’,{keyPath:’id’}); almacen.createIndex(‘BuscarFecha’, ‘fecha’,{unique: false});
}
Listado 11-5. Declarando Almacenes de Objetos e índices.
Para nuestro ejemplo solo necesitamos un Almacén de Objetos (para almacenar películas) y dos índices. El primer índice, id, es declarado como el atributo clave para el método createObjectStore() cuando el Almacén de Objetos es creado. El segundo índice es asignado al Almacén de Objetos usando el método createIndex (). Este índice fue identificado con el nombre BuscarFecha y declarado para la propiedad fecha (esta propiedad es ahora un índice). Más adelante vamos a usar este índice para ordenar películas por año.
Agregando Objetos
Por el momento tenemos una base de datos con el nombre mibase que tendrá el valor de versión 1.0 y contendrá un Almacén de Objetos llamado peliculas con dos índices: id y fecha. Con esto ya podemos comenzar a agregar objetos en el almacén:
function agregarobjeto(){
var clave=document.getElementByld(‘clave’).value; var titulo=document.getElementById(‘texto’).value; var fecha=document.getElementById(‘fecha’).value;
var transaccion=bd.transaction([‘peliculas’],
IDBTransaction.READ_WRITE); var almacen=transaccion.objectStore(‘peliculas’); var solicitud=almacen.add({id: clave, nombre: titulo, fecha:
fecha});
solicitud.addEventListener(‘success’, function(){
mostrar(clave) }, false);
document.getElementById(‘clave’).value=»; document.getElementById(‘texto’).value=»; document.getElementById(‘fecha’).value=»;
}
Listado 11-6. Agregando objetos.
Al comienzo de la función iniciar() habíamos agregado al botón del formulario una escucha para el evento click. Esta escucha ejecuta la función agregarobjeto() cuando el evento es disparado (el botón es presionado). Esta función toma los valores de los campos del formulario (clave, texto y fecha) y luego genera una transacción para almacenar un nuevo objeto usando esta información.
Para comenzar la transacción, debemos usar el método transaction(), especificar el Almacén de Objetos involucrado en la transacción y el tipo de transacción a realizar. En este caso el almacén es peliculas y el tipo es declarado como read_write.
El próximo paso es seleccionar el Almacén de Objetos que vamos a usar. Debido a que la transacción puede ser originada para varios Almacenes de Objetos, tenemos que declarar cuál corresponde con la siguiente operación. Usando el método obj ectStore () abrimos el Almacén de Objetos y lo asignamos a la transacción con la siguiente línea: transaccion.obj ectStore(‘peliculas’).
Es momento de agregar el objeto al Almacén de Objetos. En este ejemplo usamos el método add() debido a que queremos crear un nuevo objeto, pero podríamos haber utilizado el método put () en su lugar si nuestra intensión hubiese sido modificar un viejo objeto. El método add() genera el objeto usando las propiedades id, nombre y fecha y las variables clave, titulo y fecha.
Finalmente, escuchamos al evento disparado por esta solicitud y ejecutamos la función mostrar () en caso de éxito. Existe también un evento error, por supuesto, pero como la respuesta a los errores depende de lo que usted quiera para su aplicación, no consideramos esa posibilidad en este ejemplo.
Si el objeto es correctamente almacenado, el evento success es disparado y la función mostrar () es ejecutada. En el código del Listado 11-6, esta función fue llamada dentro de una función anónima para poder pasar la variable clave. Ahora vamos a tomar este valor para leer el objeto previamente almacenado:
function mostrar(clave){
var transaccion=bd.transaction([‘peliculas’]); var almacen=transaccion.objectStore(‘peliculas’); var solicitud=almacen.get(clave);
solicitud.addEventListener(‘success’, mostrarlista, false);
}
function mostrarlista(e){
var resultado=e.result || e.target.result;
cajadatos.innerHTML='<div>’+resultado.id+’ – ‘+resultado.nombre+’
– ‘+resultado.fecha+'</div>’;
}
Listado 11-7. Leyendo y mostrando el objeto almacenado.
El código del Listado 11-7 genera una transacción read_only y usa el método get () para leer el objeto con la clave recibida. No tenemos que declarar el tipo de transacción porque read_only es establecido por defecto.
El método get() retorna el objeto almacenado con la propiedad id=clave. Si, por ejemplo, insertamos la película El Padrino de nuestra lista, la variable clave tendrá el valor «tt0068646». Este valor es recibido por la función mostrar() y usado por el método get () para leer la película El Padrino. Como puede ver, este código es solo ilustrativo ya que solo puede retornar la misma película que acabamos de almacenar.
Como cada operación es asíncrona, necesitamos dos funciones para mostrar la información. La función mostrar() genera la transacción y lee el objeto, y la función mostrarlista () muestra los valores de las propiedades del objeto en pantalla. Otra vez, solo estamos escuchando al evento success, pero un evento error podría ser disparado en caso de que el objeto no pueda ser leído por alguna circunstancia en particular.
La función mostrarlista() recibe un objeto. Para acceder a sus propiedades solo tenemos que usar la variable representando al objeto y el nombre de la propiedad, como en resultado.id (la variable resultado representa el objeto e id es una de sus propiedades).
Del mismo modo que cualquier código previo, el ejemplo debe ser finalizado agregando una escucha para el evento load que ejecute la función iniciar() tan pronto como la aplicación es cargada en la ventana del navegador:
window.addEventListener(‘load’, iniciar, false);
Listado 11-8. Iniciando la aplicación.
Hágalo usted mismo: Es momento de probar la aplicación en el navegador. Copie todos los códigos Javascript desde el Listado 11-3 al Listado 11-8 en el archivo indexed.js y abra el documento HTML del Listado 11-1. Usando el formulario en la pantalla, inserte información acerca de las películas listadas al comienzo de este capítulo. Cada vez que una nueva película es insertada, la misma información es mostrada en la caja de la derecha.