Difference between revisions of "EN/Documentation/BASIC Guide/Database Access"

Revision as of 18:22, 25 June 2009

Template:EN/Documentation/BASICGuideTOC/v2

Per accedere a un database è necessario un collegamento con il database, ovvero un canale di trasferimento che consente la comunicazione diretta con il database. A differenza delle sorgenti di dati presentate nella sezione precedente, il collegamento al database deve essere ristabilito ad ogni riavvio del programma.

Apache OpenOffice offre diversi modi di stabilire i collegamenti al database. Di seguito viene riportato un esempio del metodo basato su una sorgente di dati preesistente.

Dim DatabaseContext As Object
Dim DataSource As Object
Dim Connection As Object
Dim InteractionHandler as Object
 
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")
DataSource = DatabaseContext.getByName("Customers")
 
If Not DataSource.IsPasswordRequired Then
  Connection = DataSource.GetConnection("","")
Else
  InteractionHandler = createUnoService("com.sun.star.sdb.InteractionHandler")
  Connection = DataSource.ConnectWithCompletion(InteractionHandler)
End If

Il codice utilizzato nell'esempio controlla prima se il database è protetto da una password. In caso contrario, crea il collegamento al database richiesto utilizzando la chiamata GetConnection. Le due stringhe vuote nella riga di comando rappresentano il nome utente e la password.

Se il database è protetto da password, l'esempio crea un InteractionHandler e apre il collegamento al database mediante il metodo ConnectWithCompletion. L'InteractionHandler assicura cheApache OpenOffice richieda all'utente i dati di login necessari.

Iterazione delle tabelle

Per accedere a una tabella in Apache OpenOffice si procede generalmente dall'oggetto ResultSet. Un ResultSet è un tipo di marcatore che indica un gruppo corrente di dati all'interno di un volume di risultati ottenuti utilizzando il comando SELECT.

L'esempio mostra come utilizzare un ResultSet per ricercare i valori da una tabella del database.

Dim DatabaseContext As Object
Dim DataSource As Object
Dim Connection As Object
Dim InteractionHandler as Object
Dim Statement As Object
Dim ResultSet As Object
 
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")
DataSource = DatabaseContext.getByName("Customers")
 
If Not DataSource.IsPasswordRequired Then
  Connection = DataSource.GetConnection("","")
Else
  InteractionHandler = createUnoService("com.sun.star.sdb.InteractionHandler")
  Connection = DataSource.ConnectWithCompletion(InteractionHandler)
End If
 
Statement = Connection.createStatement()
ResultSet = Statement.executeQuery("SELECT ""CustomerNumber"" FROM ""Customer""") 
 
If Not IsNull(ResultSet) Then
  While ResultSet.next
    MsgBox ResultSet.getString(1)
  Wend
End If

Una volta stabilito il collegamento al database, il codice utilizzato nell'esempio utilizza prima la chiamata Connection.createObject per creare un oggetto Statement. L'oggetto Statement usa quindi la chiamata executeQuery per restituire il valore effettivo di ResultSet. Il programma controlla ora se ResultSet esiste effettivamente e vaglia i record di dati utilizzando un ciclo. I valori richiesti (nell'esempio, quelli dal campo CustomerNumber) restituiscono il ResultSet utilizzando il metodo getString mentre il parametro 1 determina che la chiamata è relativa ai valori della prima colonna.

Template:Documentation/Note

Template:Documentation/Note

Metodi specifici del tipo per richiamare i valori

Come illustrato dall'esempio della sezione precedente, Apache OpenOffice fornisce un metodo getString per accedere ai contenuti delle tabelle. Il risultato di questo metodo assume la forma di una stringa. Sono disponibili i seguenti metodi get:

getByte()

Supporta i tipi di dati SQL per numeri, caratteri e stringhe.

getShort()

Supporta i tipi di dati SQL per numeri, caratteri e stringhe.

getInt()

Supporta i tipi di dati SQL per numeri, caratteri e stringhe.

getLong()

Supporta i tipi di dati SQL per numeri, caratteri e stringhe.

getFloat()

Supporta i tipi di dati SQL per numeri, caratteri e stringhe.

getDouble()

Supporta i tipi di dati SQL per numeri, caratteri e stringhe.

getBoolean()

Supporta i tipi di dati SQL per numeri, caratteri e stringhe.

getString()

Supporta tutti i tipi di dati SQL.

getBytes()

Supporta i tipi di dati SQL per i valori binari.

getDate()

Supporta i tipi di dati SQL per numeri, stringhe, data e contrassegno dell'ora.

getTime()

Supporta i tipi di dati SQL per numeri, stringhe, data e contrassegno dell'ora.

getTimestamp()

Supporta i tipi di dati SQL per numeri, stringhe, data e contrassegno dell'ora.

getCharacterStream()

Supporta i tipi di dati SQL per numeri, stringhe e valori binari.

getUnicodeStream()

Supporta i tipi di dati SQL per numeri, stringhe e valori binari.

getBinaryStream()

Valori binari.

getObject()

Supporta tutti i tipi di dati SQL.

In tutti i casi, il numero di colonne dovrebbe essere elencato come parametro di cui ricercare i valori.

Le varianti ResultSet

La velocità è spesso un fattore critico per l'accesso ai database. Apache OpenOffice offre pertanto diversi modi per ottimizzare ResultSets e controllare quindi la velocità di accesso. Maggiore è il numero di funzioni fornito da ResultSet, più complessa sarà l'implementazione e di conseguenza più lente saranno le funzioni.

Un ResultSet, fornisce la gamma minima di funzioni disponibili. Consente di applicare l'iterazione solo in avanti e per i valori oggetto dell'interrogazione. Opzioni di navigazione più estese, quali la possibilità di modificare i valori, non sono pertanto incluse.

L'oggetto Statement utilizzato per creare il ResultSet fornisce alcune proprietà che consentono di incidere sulle funzioni del ResultSet:

ResultSetConcurrency (const)

Specifiche sulla possibilità di modificare o meno i dati (specifiche conformi a com.sun.star.sdbc.ResultSetConcurrency).

ResultSetType (const)

Specifiche riguardanti il tipo di ResultSets (specifiche conformi a com.sun.star.sdbc.ResultSetType).

I valori definiti in com.sun.star.sdbc.ResultSetConcurrency sono:

UPDATABLE

ResultSet consente di modificare i valori.

READ_ONLY

ResultSet non consente modifiche.

Il gruppo di costanti com.sun.star.sdbc.ResultSetConcurrency fornisce le seguenti specifiche:

FORWARD_ONLY

ResultSet consente solo lo spostamento in avanti.

SCROLL_INSENSITIVE

ResultSet consente qualsiasi tipo di spostamento,

tuttavia le modifiche ai dati originali non sono registrate.

SCROLL_SENSITIVE

ResultSet consente qualsiasi tipo di spostamento; le modifiche ai dati originali incidono su ResultSet

Template:Documentation/Note

Quando si utilizzano le proprietà ResultSet's UPDATEABLE e SCROLL_SENSITIVE, la portata della funzione di un ResultSet è paragonabile a un Dynaset di tipo Recordset di ADO e DAO.

Metodi per lo spostamento nei ResultSets

Se un ResultSet è di tipo SCROLL_INSENSITIVE o SCROLL_SENSITIVE supporta una serie completa di metodi di spostamento nel gruppo di dati. I metodi principali sono i seguenti:

next()

Spostamento al record di dati successivo.

previous()

Spostamento al record di dati precedente.

first()

Spostamento al primo record di dati.

last()

Spostamento all'ultimo record di dati.

beforeFirst()

Spostamento a prima del primo record di dati.

afterLast()

Spostamento a dopo l'ultimo record di dati.

Tutti i metodi restituiscono un parametro booleano (logico) che specifica se lo spostamento ha avuto successo.

Per determinare la posizione corrente del cursore, sono disponibili i seguenti metodi di test, che restituiscono tutti un valore logico:

isBeforeFirst()

ResultSet è prima del primo record di dati.

isAfterLast()

ResultSet è dopo l'ultimo record di dati.

isFirst()

ResultSet è il primo record di dati.

isLast()

ResultSet è l'ultimo record di dati.

Modifica dei record di dati

Se è stato creato un ResultSet con il valore ResultSetConcurrency = UPDATEABLE, il suo contenuto può essere modificato. Ciò è applicabile solo finché il comando SQL consente di riscrivere i dati nel database (dipende dal principio). Non è ad esempio possibile con i comandi SQL complessi con colonne collegate o valori accumulati.

L'oggetto ResultSet fornisce i metodi Update per la modifica dei valori, che sono strutturati nello stesso modo dei metodi get per il richiamo dei valori. Il metodo updateString, ad esempio, consente di scrivere una stringa.

Dopo la modifica, i valori devono essere trasferiti nel database utilizzando il metodo updateRow(). La chiamata dovrà aver luogo prima del comando di navigazione successivo, altrimenti i valori andranno persi.

Se viene commesso un errore durante le modifiche, è possibile procedere all'annullamento utilizzando il metodo cancelRowUpdates(). Questa chiamata è disponibile solo se i dati non sono stati sovrascritti nel database mediante updateRow().