## Guida: QBE - Query By Example

Questa guida descrive l'utilizzo della feature denominata Query By Example, corrispondente alla modellazione di un particolare tipo di Finder, il QBEFinder.

### Introduzione

Con il termine Query by example si intende una modalità per indicare i criteri di filtro per una query su un oggetto DB ben definito basata sulla predisposizione di due insiemi di esempi:

- un insieme di esempi positivi
- un insieme di esempi negativi

Il risultato di una query basata su tali insiemi di esempi è tale che l'insieme dei risultati della query contiene tutti e soli gli elementi del DB che:

- soddisfano (match) almeno uno degli esempi positivi
- non soddisfano (don't match) nessuno degli esempi negativi

Ad esempio, supponiamo di dover utilizzare tale tecnica su una tabella Persona contenente le colonne:

- codiceFiscale (stringa)
- nome (stringa)
- cognome (stringa)
- eta (intero)

Supponiamo di dover effettuare la ricerca delle persone che soddisfano questi criteri:

- sono maggiorenni
- hanno il cognome che iniza per "A" oppure per "F"
- NON si chiamano "MARIO"

Per realizzare tale query in modalità QBE è necessario utilizzare il seguente insieme di esempi:

- esempi positivi:
  1. Esempio 1+:
     - cognome like ('%A%')
     - eta > 18
  2. Esempio 2+:
     - cognome like ('%F%')
     - eta > 18
- esempi negativi:
  1. Esempio 1-:
     - nome = 'MARIO'

Articolando opportunamente esempi posivi e negativi è possibile definire praticamente qualsiasi criterio di filtro basato sull'analisi dei valori del singolo record. Tipicamente negli applicativi gestionali, dove le ricerche sono spesso basate su una pagina di filtri di ricerca, l'insieme degli esempi dati in pasto al generatore di query by example si riduce ad un numero molto ristretto (spesso 1) di esempi positivi.

### Implementazione del QBE in datagen

In datagen la modalità QBE viene realizzata in due momenti:

1. a tempo di modellazione, definendo un QBEFinder tra le operazioni di un DataAccessObject
2. a tempo di codifica java, sul progetto generato, richiamando il metodo generato a fronte del QBEFinder e fornendo gli opportuni esempi (positivi e negativi).

Nell'implementazione QBE fornita da datagen gli esempi sono classi java associate ai DataAccessObject, che assomigliano ai DTO per nome e numero dei campi, ma se ne differenziano per quanto riguarda il tipo di tali campi. Mentre infatti nei DTO il tipo dei campi è in pratica il tipo JDBC corrispondente al tipo SQL della colonna associata a tale campo, nel caso degli examples il tipo è un tipo astratto: `FieldChk`. Questo permette a chi popola gli esempi di introdurre per ciascun campo un criterio di filtro specifico istanziando particolari tipi di `FieldChack`.

Esistono differenti tipi di check su field che possono essere utilizzati, e sono disponibili nel package `qbe` generato da datagen in ogni progetto:

- EQCheck: permette la verifica di una condizione di uguaglianza, eventualmente con tolleranza sul case del testo
- RangeCheck: permette a verifica di una condizione di appartenenza di un valore ad un range continuo di valori delimitato da due estremi (inferiore, superiore)
- NullCheck: permette di verificare se il valore di un cmapo è nullo o non nullo

N.B: in futuro verranno aggiunti altri tipi di check. Allo stato attuale è possibile utilizzare solo questi tre tipi di check: il meccanismo non è estendibile in autonomia dall'utilizzatore.

### Approfondimenti

Esempi pratici dell'utilizzo della modalità query-by-example si possono trovare all' interno della Reference Application MDD.