Jaiberdroid en 5 Minutos

José Antonio Fuentes Santiago edited this page Oct 27, 2013 · 16 revisions

Table of Contents

Añadiendo Jaiberdroid a tu proyecto

Existen varios métodos para agregar la librería Jaiberdroid a tus proyectos. La primera de ellas es más pesada ya que requiere descargar todo el proyecto y enlazarlo. La segunda, es más sencillo ya que tan sólo hay que agregar jaiberdroid.x.x.jar.

Método 1: enlazar el proyecto

Eclipse

  1. Una vez descargado el proyecto Jaiberdroid, se deberá importar al entorno.
  2. Ahora en tu proyecto, abre sus propiedades (clic derecho sobre el proyecto, opción Settings).
  3. En la pestaña Android, apartado Library, pulsa el botón Add... y selecciona tu proyecto.
Nota: se tiene constancia de que hay problemas con el enlace de proyectos de librería si no están en el mismo directorio, por lo que es bueno que tengas tu proyecto y Jaiberdroid en el mismo directorio.

Método 2: incluir el .jar de la librería

  1. Dentro de tu proyecto, comprueba si existe un directorio libs. En el caso de no existir deberás crearlo.
  2. Ahora tan sólo tendrás que copiar el fichero jaiberdroid.x.x.jar a dicho directorio.
Note: si se lanza una excepción "Unable to resolve superclass" al ejecutar tu aplicación, ve a las Propiedades del Proyecto->Java Build Path->Order and Export y marca la casilla Android Private Libraries.

Configuración

Jaiberdroid necesita tres parámetros de configuración para funcionar, dichos parámetros serán definidos en un xml dentro de la carpeta values. Pasemos a verlos rápidamente:

  • jaiberdroid_entities: array de cadenas (string-array) en la que cada elemento define una clase de entidad a utilidad. Se deberá especificar su paquete y nombre.
  • jaiberdroid_database: cadena (string) que almacena el nombre de la base de datos.
  • jaiberdroid_version: cadena (string) que contiene el número de versión de la base de datos.
  • jaiberdroid_debug: valor booleano (true o false) que indica si se muestran todas las consultas SQL ejecutadas, junto con otras trazas de depuración. Si este campo no existe, por defecto la depuración estará desactivada.
A continuación, se muestra un ejemplo de fichero de configuración:
<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string-array name="jaiberdroid_entities">
    <item>paquete.de.clase.Entidad1</item>
    <item>paquete.de.clase.Entidad2</item>
    <item>paquete.de.clase.EntidadN</item>
  </string-array>

  <string name="jaiberdroid_database">mi_base_de_datos</string>
  <string name="jaiberdroid_version">1</string>
  <string name="jaiberdroid_debug">true</string>
</resources>

Uso de Jaiberdroid

Carga de Jaiberdroid

Para iniciar el sistema Jaiberdroid tan sólo hay que ejecutar dos métodos:

 JaiberdroidInstance.createInstance(this);
 JaiberdroidInstance.start();

Con la primera instrucción indicamos que se realice la carga del sistema. Procederá a inicializar el sistema.

La segunda instrucción obtiene las entidades definidas en la configuración jaiberdroid_entities y analiza su estructura. Devolverá una JaiberdroidException en el caso de que ocurra algún problema en dicha carga. También obtendrá la versión y nombre de la base de datos y creará la misma.

Cuando termines de utilizar la librería, sería recomendable ejecutar la siguiente llamada:

 JaiberdroidInstance.stop();

Dicho método detendrá la librería y liberará la memoria utilizada. Una vez realizada esta operación no se podrá volver a utilizar la librería, por lo que siempre deberá ponerse en el cierre de la aplicación.

Clases de entidad

Las clases de entidad en Jaiberdroid son clases que definen una tabla de base de datos. Para que una clase sea de entidad, hay que añadir la etiqueta @Table. Dicha etiqueta indicará la naturaleza de la clase a Jaiberdroid.

A continuación se añadirá la etiqueta @Column a cada atributo que represente una columna de base de datos. Es obligatorio crear un atributo de tipo int llamado _id, ya que todas las tablas en SQLite para Android usan dicho identificador como Clave Primaria.

Finalmente, se deberán tener los métodos get y set para cada atributo mapeado. De forma que Jaiberdroid pueda ejecutarlos a la hora de leer y asignar los valores de los atributos.

@Table
public class File {
  @Column(primary = true, nullable = false)
  private int _id;
  @Column(nullable = false. unique = true)
  private String name;
  @Column(index = true)
  private String path;
  @Column()
  private Long date;
  @Column(nullable = false, index = true, ascOrder = false)
  private int version;

  public final int get_id() {
    return _id;
  }
  public final void set_id(int _id) {
    this._id = _id;
  }
  public final String getName() {
    return name;
  }
  public final void setName(String name) {
    this.name = name;
  }
  public final String getPath() {
    return path;
  }
  public final void setPath(String path) {
    this.path = path;
  }
  public final Long getDate() {
    return date;
  }
  public final void setDate(Long date) {
    this.date = date;
  }
  public final int getVersion() {
    return version;
  }
  public final void setVersion(int version) {
    this.version = version;
  }
}

En el ejemplo anterior, se puede observar como se pueden especificar parámetros para las etiquetas @Column que definan mejor a cada atributo.

Etiquetado de Columnas

Todos los campos de una clase de entidad deben indicarse precediendo sus declaraciones con la etiqueta @Colum. Si un campo no tiene dicha etiqueta, será ignorado por Jaiberdroid.

  • primary: valor booleano que indica si el campo es clave primaria. Dicho campo deberá llamarse _id y ser de tipo int. Por defecto es false.
  • unique: valor booleano que indica si el campo es único. Por defecto es false.
  • nullable: valor booleano que indica si el campo puede almacenar valores nulos. Sólo los objetos puede utilizar dicha etiqueta. Puedes usar tipos de datos primitivos siempre y cuando nullable tenga valor false. Por defecto es true.
  • defaultValue: cadena que especifica un valor por defecto para la columna actual. Los valores por defecto siempre se almacenan como cadenas. Por defecto es "" (cadena vacía).
  • index: valor booleano que indica si la columna actual está indexada. Jaiberdroid creará un índice para la columna con el nombre index_nombretabla_nombrecampo.
  • ascOrder: valor booleano que indica el orden del índice. Si su valor es true el índice se ordenará ascendentemente, en caso contrario el orden será descendente. Por defecto es true.

Tipos de datos permitidos

Los tipos de datos permitidos para los atributos de las clases de entidad se indican en la tabla siguiente:

Primitivo Clase Comentarios
int Integer
long Long
float Float
double Double
- String
- java.util.Date Recude la precisión de la fecha a segundos.

Queries

Jaiberdroid utiliza clases llamadas Queries para poder ejecutar las consultas a base de datos. Se pueden utilizar tanto dichas clases, como instanciar la clase GenericQuery. En la instanciación de las clases se definirá un parámetro consistente en la clase entidad a utilizar.

Lo anterior dependerá de si queremos crear nuestras propias consultas, o sólo vamos a utilizar las consultas por defecto.

Ejemplo de herencia de GenericQuery

Fichero FileQuery.java
 public class FileQuery extends GenericQuery<File> {
 ...
 }
Fichero MainActivity.java
 final FileQuery query = new FileQuery();
 ....

Ejemplo de instancia directa de GenericQuery

 final GenericQuery query = new GenericQuery<File>;

Consultas por defecto

Al crear una query se tiene acceso a una serie de consultas ya predefinidas, por lo que para realizar dichas consultas no hay que realizar ninguna otra operación. Dichas consultas son:

Método Parámetro Retorno Descripción
count() - long Devuelve un valor long con el número de filas de la tabla.
exists() int id boolean Obtiene un valor booleano que será true cuando exista el identificador recibido en la tabla.
findByPk() int id Object Devuelve un objeto del tipo de la clase entidad con los datos del elemento cuya id se ha indicado.
insert() Object row boolean Almacena en base de datos el objeto recibido como parámetro. Devolverá un valor booleano que indica si la inserción fue correcta, y además actualizará el identificador del objecto para que coincida con el de base de datos.
remove() int id boolean Elimina la fila cuyo identificador se ha recibido como parámetro, devolviendo un valor booleano que indica si se eliminó la fila.
removeAll() - long Elimina todas las filas de la tabla, devolviendo un valor entero largo que indica el número de filas eliminadas.
update() Object row boolean Actualiza el objeto de entidad recibido en base de datos, devolviendo un valor booleano que indica si la operación fue correcta.

Consultas personalizadas

A partir de la versión 0.5 beta de Jaiberdroid se pueden crear consultas personalizadas. El método encargado de ejecutarlas es executeQuery() heredado de Generic Query. Dicho método dispone de dos tipos de parámetros:

  • Cadena de consulta SQL: con este tipo se puede ejecutar cualquier tipo de consulta. El resultado será una lista de mapas de cadenas, es decir, un objecto del tipo List<String, Map<String, String>>, donde cada elemento de la lista será una fila, y cada elemento del mapa estará compuesto del nombre del campo y su valor.
  • Objeto Query: representa una consulta sencilla para sólo una entidad. Tan sólo hay que especificar los valores de la consulta y llamar al método pasando el objeto. El valor de retorno será una lista de entidades al ejecutar un SELECT o el número de filas afectadas cuando se ejecuta un INSERT, UPDATE o DELETE.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.