Gestire database SQLite con Adobe AIR usando Flash CS6 (terza parte)

Segue la terza e ultima parte del tutorial dedicato alle tecniche di base per dialogare con un database locale tramite un’applicazione AIR. Segnalo di seguito i link relativi alla prima e la seconda parte.
In questo ultimo appuntamento completeremo l’interfaccia e arricchiremo la classe documento con dei metodi dedicati alla scrittura e alla cancellazione dei dati. A questo indirizzo è possibile scaricare i sorgenti dell’esempio completo: Scarica la cartella.
Ci sarebbero ancora cose da dire sui databse locali e AIR, ma mi riservo di riprendere l’argomento più avanti.

Completiamo l’interfaccia utente

Per completare l’interfaccia sono stati inserito ulteriori oggetti interattivi nel documento Flash. Per la precisione, un componente in grado di mostrare i dati presenti nel database, dei campi di inserimento per poter aggiungere nuovi contatti e dei pulsati per inviare e cancellare dati. Apriamo il fil esempioDB.fla disponibile nella cartella dei sorgenti e analizziamo il contenuto del livello elementi. Come è possibile osservare, nella parte alta sono stati collocati tre campi di testo TLF modificabili, denominati campoNome, campoCognome e campoTelefono. Accanto a questi campi si trova un pulsante il cui nome di istanza è p1. Per inserire un nuovo contatto nella rubrica, l’utente non deve fare altro che compilare i campi e premere il pulsante.
Nella parte sottostante è stato inserito un componente DataGrd il cui nome di istanza è grid. Poiché questo tipo di componente consente di visualizzare una raccolta di dati in una griglia di righe, è l’ideale per visualizzare i modo veloce tutti i contatti della nostra rubrica. Inoltre, se il numero dei dati supera lo spazio verticale, offre il vantaggio di mostrare una barra scorrevole.
Se come me non siete abituati ad usare i componenti (non li amo particolarmente per motivi estetici e di conseguenza li uso pochissimo), potete optare per un ripasso veloce grazie a questo breve videotutorial di RiverCityGraphix.
In ogni caso, il componente usato nel tutorial è stato ridimensionato manualmente in modo da occupare più o meno il centro dello Stage. Tuttavia la posizione e le dimensioni usate non sono vincolanti.
Nella parte finale ci sono infine due pulsanti denominati rispettivamente: p2 e p3. Il primo cancella un singolo contatto selezionato e il secondo elimina tutta la rubrica.

La classe documento

Per poter completare il nostro applicativo, è necessario aggiungere le istruzioni relative ai compiti svolti dai nuovi oggetti posti sullo Stage. Come è possibile notare osservando il codice, sono stati aggiunte nuove proprietà e nuovi metodi al codice postato nell’articolo precedente.

Il listato è decisamente ingrassato: ha messo su ben 139 righe contro le precedenti 49. E’ anche vero che, pur essendo il codice per creare un piccola applicazione simbolica, stiamo pur sempre dialogando con un database. Vediamo di “spezzettare” la classe in modo da analizzare poco alla volta i vari blocchi di codice inediti.
Prima di tutto, nella parte iniziale del codice posta dopo la dichiarazione di classe, sono state create quattro nuove proprietà private corrispondenti ad altrettante istanze della classe SQLStatement.

La classe SQLStatement serve ad eseguire delle istruzioni SQL su un database. Nel nostro listato i quattro oggetti SQLStatement si occuperanno di: creare la tabella se non esiste,  inserire nuovi dati, individuare i dati inseriti e cancellare i dati.
Tra le nuove istruzioni presenti nella parte iniziale del codice abbiamo anche la creazione di un array che ci servirà a inviare i contatti della rubrica al componente DataGrid.
Passiamo quindi alla funzione costruttore  MioDB(), che in questa versione del listato mostra qualche riga di codice in più.

In corrispondenza dei tre pulsanti collocati sullo Stage, sono attribuiti tre funzioni listener: scriviTabella(), cancellaRiga() e cancellaTabella(). I nomi delle funzioni sono abbastanza intuitivi per cui è facile capire a cosa servono. Nella funzione costruttore sono anche state settate le proprietà restrict dei tre campi TLF modificabili. In particolare, viene fatto in modo che i primi campi accettino solo lettere (maiuscole oppure minuscole) che il terzo campo accetti solo valori numerici.In questo modo impediamo agli utenti di inserire dati errati durante la digitazione.
Una volta analizzata la funzione costruttore passiamo al codice eseguito automaticamente ad ogni avvio dell’applicazione. Nella funzione listener apri(), abbiamo la chiamata della funzione creaTabella() assente nella precedente versione del codice.
Come abbiamo visto la volta scorsa, la funzione apri() si innesca non appena si apre la connessione con il database. La creazione della tabella è la prima istruzione da eseguire per poter concretamente interagire con il file .DB. Per comodità riporto di seguito il codice della funzione creaTabella():

La prima istruzione passa alla proprietà creatabellaStmt un nuovo oggetto SQLStatement. La seconda istruzione passa alla proprietà sqlConnection dell’oggetto SQLStatement l’istanza connect. Con questi due semplici passaggi creiamo una oggetto per dare ordini SQL e specifichiamo che farà riferimento al  database DBesempio.db.
Alla stringa sql passiamo i comandi destinati a manipolare il database. Osservando il codice è possibile intuire le istruzioni SQL a colpo d’occhio. In pratica, viene creata (se non esiste già) una tabella chiamata rubrica. Allo stesso tempo vengono anche definite la varie colonne della tabella: una chiave primaria, due stringhe (nome e cognome) e un numero intero (il numero di telefono).
Per attribuire l’istruzione SQL al database è necessario passare la stringa sql alla proprietà text dell’oggetto SQLStatement.
Nelle ultime righe della funzione, abbiamo due istruzioni  addEventListener() e un metodo execute(). La prima istruzione  addEventListener() chiama una funzione da eseguire al verificarsi dell’evento RESULT che stabilisce se il comando SQL viene eseguito con successo.
La seconda istruzione  addEventListener() innesca la funzione errore() al verificarsi di un evento ERROR. Infine l’istruzione execute() innesca l’esecuzione del codice SQL.
A ben guardare abbiamo una sequenza di operazioni che potrebbero essere riassunte in uno schema generale valido per tutte le volte in cui vogliamo interagire con un database. Riepilogando:

1. Si crea un oggetto SQLStatement.
2. Si passa alla proprietà  sqlConnection dell’oggetto SQLStatement, un’istanza SQLConnection. Questo implica che dobbiamo aver precedentemente creato una connessione con il database tramite la classe SQLConnection (ne abbiamo parlato nell’articolo precedente).
3. Si passa ad una variabile le istruzioni SQL sottoforma di stringa.
4. La variabile stringa viene a sua volta passata alla proprietà text dell’oggetto SQLStatement.
5. Si specificano la funzioni listener da eseguire nel caso in cui le istruzioni SQL vengano eseguite correttamente (evento RESULT).
6. Si specfica una funzione listener da eseguire in caso di errore.
7. Si attiva concretamente l’istruzione SQL tramite il metodo execute().

Troviamo questo stesso schema ripetuto in molte istruzioni della nostra classe documento. Per cui, una volta chiarito questo meccanismo, possiamo concentraci sulla logica generale del codice senza ripetere ogni volta gli stessi concetti.
Eravamo rimasti alla creazione della tabella. Un volta creata con successo la tabella, viene chiamata la funzione scrivi(), che si limita a inserire un messaggio nel campo TLF miocampo e chiama la funzione mostraDatiScritti(). Riepiloghiamo il codice della funzione mostraDatiScritti():

In questo caso, invece di creare una tabella, le istruzioni SQL selezionano i dati della tabella in ordine ascendente. Una volta eseguita con successo l’istruzione (al verificarsi dell’evento SQLEvent.RESULT) viene chiamata la funzione listener passaDataGrid() che ha il compito di inserire nel componente DataGrid i dati estrapolati dal database. Vediamo il codice di questa funzione:

Prima di tutto viene creato un’istanza della classe SQLResult. Si tratta di una classe attraverso la quale è possibile accedere ai dati restituiti da un’istruzione SQL tramite il metodo getResult().
Nella riga di codice successiva vengono passati all’array mioArray i dati estrapolati dal database.
Inserendo mioArray come parametro della funzione costruttore della classe DataProvider, otteniamo un oggetto dp da passare alla proprietà dataProvider dell’oggetto grid. Con questa istruzione inseriamo i dati estrapolati nel componente datagrid.
L’ultima istruzione della funzione ci consente di definire in quale ordine visualizzare i dati nel componente. Nel nostro caso avremo prima la colonna dei nomi, poi quella de cognomi e infine la colonne dei numeri di telefono.
Dopo aver analizzato le istruzioni eseguite all’avvio dell’applicazione, passiamo alle funzioni innescate dai pulsanti p1, p2 e p3. Cominciamo da scriviTabella():

Rispetto alle altre funzioni dedicate alla manipolazione del database, abbiamo un codice nidificato in un’istruzione condizionale. In altri termini, viene fatto in modo che l’utente possa inserire i dati solo quando i campi non sono vuoti. Per quanto riguarda l’istruzione SQL, in questo caso viene inserito un nuovo contatto della rubrica dove il nome, il cognome e il numero di telefono vengono attribuiti in base al contenuto dei relativi campi TLF. Una volta eseguita correttamente l’istruzione SQL, viene chiamata nuovamente l’istruzione mostraDatiScritti() in modo da visualizzare la rubrica subito dopo l’inserimento dei nuovi dati.
A questo punto passiamo alla funzione cancellaRiga():

Il ciclo for ci consente di analizzare tutte le righe presenti nell’array alla ricerca di una condizione da verificare. Se uno dei contatti mostrati nel componente è stato selezionato dall’utente, in quel caso vengono eseguite le istruzioni specificate nel codice dell’if().
L’istruzione SQL cancella una riga a partire dal un valore mioid specificato. Tale valore è fornito dalla selezione effettuata sul componente, ovvero dall’istruzione grid.selectedItem.mioid.
Una volta cancellato il record, viene innescata come di consjueto la funzione listener mostraDatiScritti() in modo da visualizzare immediatamente la rubrica con i contatti aggiornati.
Per finire non ci resta che analizzare la funzione cancellaTabella():

L’istruzione SQL passata alla variabile stSQL cancella la tabella rubrica se esiste. subito dopo il metodo execute(), oltre al solito meccanismo usato per dare dei comandi al database, abbiamo una serie di istruzioni “preparatorie” che servono a rendere l’applicazione in grado di proseguire il lavoro nonostante la cancellazione della tabella. In altre parole, l’utente deve essere in grado di poter aggiungere nuovi dati senza incappare in malfunzionamenti. Per cui abbiamo lo svuotamento dell’array, la creazione di un nuovo oggetto DataProvider, un scritta che comunica la cancellazione della tabella e la chiamata al metodo creaTabella() per creare una nuova tabella vuota.

Note finali

Per quanto riguarda la pubblicazione, vale quanto detto la volta scorsa. Inoltre, se non abbiamo cambiato i valori presenti nella finestra Impostazioni AIR, non è necessario disinstallare la versione precedente della rubrica: nel momento in cui andiamo ad installare il file.air, se nome e versione non cambiano, il programma di installazione si limita a sovrascrivere la versione precedente.
Per concludere, una rubrica telefonica in AIR come quella che abbiamo appena descritto ha una qualche utilità pratica? La risposta è no. Usare una rubrica di questo tipo non ha alcuna valenza nel mondo reale.
Però spero che questo esercizio sia stato utile. Nel mio caso, questo stesso script mi ha aiutato a salvare il punteggio di un videogame per Android che sto sviluppando. Della serie: non tutte le rubriche vengono per nuocere…