JPA visuale con Eclipse e i Dali tools

JPA 2 è la specifica Java per l'accesso, la persistenza e la gestione dei dati tra oggetti Java e database relazionali. Abbiamo già introdotto la specifica in articoli precedenti in cui abbiamo presentato un confronto con JDO e visto che uno dei principali motivi per cui JPA è preferibile è l'ampia popolarità che ha portato alla diffusione di diversi tools a supporto degli sviluppatori.

In questo articolo esaminiamo il Dali Java Persistence Tools di Eclipse, uno strumento utile a snellire lo sviluppo di applicazioni che richiedono il supporto di JPA. Esamineremo alcune delle principali funzionalità del tool e vedremo come impostare un nuovo progetto che supporti direttamente JPA o come convertire uno esistente in un progetto JPA.

Ci occuperemo anche di feature che consentono di velocizzare la creazione delle entità o di importarle direttamente dalle tabelle di un database già esistente.

Precondizioni

Per seguire gli esempi che faremo occorre avere installato il Java Development Kit (JDK 6), aver impostata la variabile d'ambiente JAVA_HOME e aggiornato il Path di sistema.

Inoltre daremo per acquisiti i concetti di base di JPA 2. Ecco due articoli importanti per approfondire o rinfrescare le conoscenze:

>> Leggi Introduzione a JPA e confronto con JDO

>> Leggi JPA 2: generare chiavi primarie e relazioni

In questi articoli troviamo qualche informazione in più su Hibernate che è l'implementazione di JPA che utilizziamo in coppia con il database relazionale HSQLDB (HyperSQL).

>> Leggi Introduzione a HyperSQL.

In allegato abbiamo il file di properties server.properties per inizializzare il database che utilizzeremo negli esempi seguenti.

Configurare Eclipse

I Dali Java Persistence Tools per Eclipse sono inclusi come parte dell'"Eclipse Web Tools Platform (WTP) 3.1", tools che si trovano inclusi negli Eclipse IDE for Java EE Developers a partire da Eclipse 3.5 Galileo, pertanto non occorrono ulteriori configurazioni o installazioni.

Quindi la via più semplice è lavorare direttamente con la versione JEE dell'IDE.

In alternativa, disponendo dei soli IDE di base (Eclipse Classic o Eclipse ID for Java Developers, a partire dal 3.5), è possibile scaricare il corrispondente Java EE Package.

Come ulteriore possibilità, se non si vuole effettuare l'installazione dell'intero Java EE Package, possiamo scaricare il Web Tools Platform per l'IDE in uso alla voce Help/Install New Software...

Ad esempio, per la versione Eclipse Indigo, occorrerà selezionare (Work with) la voce Indigo e selezionare il Web, XML, Java EE and OSGi Enterprise Development. Al suo interno sarà possibile spuntare il Dali Java Persistence Tools - JPA Support e avviare il download.

Per le versioni precedenti alla Indigo, selezionare l'update WTP dal sito (Work with) http://download.eclipse.org/webtools/updates/.

Impostare un progetto JPA

Negli articoli precedenti abbiamo già visto che è sufficiente un normale Java Project per utilizzare il supporto JPA. Eclipse con i Dali Java Persistence Tools, fornisce un insieme di strumenti utili a velocizzare le attività connesse con la persistenza.

Per iniziare a sperimentare il tooltik iniziamo con il creare un progetto JPA: (File > New > JPA Project oppure File > New > Project... > JPA > JPA Project). Occorrerà poi configurare alcune voci.

Nella prima schermata scegliamo il nome del progetto, ad esempio JPATestProject, e la versione di JPA (attualmente la 2.0). È possibile lasciare invariate le altre voci (ci viene chiesto ad esempio se le entità devono essere incluse nel file persistence.xml o scoperte in automatico).

Clicchiamo due volte sul pulsante Next passando alla schermata "JPA Facet". Qui possiamo scegliere la piattaforma JPA di riferimento. Se disponibile, scegliamo Hibernate (JPA 2.x), altrimenti possiamo utilizzare la voce Generic 2.0.

Occorre quindi scegliere il set di librerie dell'implementazione JPA. Scegliendo la voce Disable Library Configuration e ci assumiamo la responsabilità di importare le librerie successivamente. Scegliendo invece la voce User Library possiamo caricare o creare ex novo una libreria utente che accoglierà il set minimo di librerie di cui necessitiamo.

Se non è già disponibile una Libreria Utente idonea, come evidenziato dall'immagine seguente, scegliere l'opzione Manage libraries... quindi New o Import.

Una volta creata una Libreria Utente, i progetti JPA successivi potranno utilizzare direttamente questa libreria risparmiando il tempo necessario a caricare a mano i singoli Jar.

Scelto un nome, ad esempio "HibHSQL Libraries", senza spuntare la voce System library JPA 2 e la persistenza in Java

La voce Connection <None>

Possiamo quindi premere Finish META-INF persistence.xml

In generale, per ragioni di portabilità del progetto, è buona regola importare nel progetto stesso le librerie usate. Il JPA Project mette a disposizione la cartella "build

Quanto presentato finora è il caso standard nel quale si dispone di un database indipendente. È possibile fare riferimento a un embedded database Target runtime Library Provided by Target Runtime

Persistence XML Editor

L'XML è potente ma scomodo, soprattutto quando vogliamo popolare il file di configurazione come il persistence.xml. Per questo i Dali Tools mettono a disposizione un'interfaccia per agevolare l'inserimento dei dati.

Cliccando col tasto destro sul file persistence.xml, si potrà aprirlo in modalità Persistence XML Editor (persistence.xml > Open With > Persistence XML Editor).

Appariranno le informazioni su diverse schede. Per fare un po' di pratica, ricostruiamo il file properties.xml usato negli articoli precedenti precedenti.

La prima scheda è la scheda "General", contenente le informazioni sulle persistence-unit. Di default viene impostata una persistence-unit con il nome del progetto. Cambiamola in "testhsqldb". È interessante notare che, nonostante nei precedenti articoli su JPA abbiamo visto che è possibile avere in contemporanea più di una persistence-unit nel file persistence.xml, in questo caso l'azione verrebbe interpretata come un errore (nella sezione seguente vedremo come è possibile evitare il messaggio d'errore).

Nella scheda "Connection" modifichiamo il campo Transaction type, impostando Resource local.

Nella scheda "Properties" aggiungeremo (Add...) le seguenti voci:

Parametro	Valore
hibernate.hbm2ddl.auto	update
hibernate.connection.url	jdbc:hsqldb:hsql://localhost/testdb1
hibernate.connection.username	sa
hibernate.connection.password

Una volta salvato, il file persistence.xml sarà pronto. Cliccando sulla scheda "Source", sarà possibile vedere direttamente il codice XML. Se si dispone dell'Hibernate Settings, tra le schede troveremo anche "Hibernate" con le principali proprietà impostabili.

Nella prossima sezione vedremo come creare entità e relazioni.

JPA Entity

Possiamo ora pensare a introdurre la prima entità del progetto. Utilizziamo il wizard messo a disposizione dai JPA tools. Una volta creato un package nella cartella src, lo chiamiamo "jpatestpack", premere con il tasto destro sul package, quindi New > JPA Entity (oppure New > Other > JPA > JPA Entity).

Inseriamo il nome della classe, "EntityTest", premiamo su Next e osserviamo le opzioni che abbiamo a disposizione nella scheda successiva.

Possiamo personalizzare il nome della tabella (Table name), scegliere il tipo di accesso (Access type), e soprattutto aggiungere gli attributi di cui necessitiamo. Come primo esempio, ci limitiamo ad aggiungere (Add...) due campi:

Type	Name
int	id
String	nome

Spuntiamo la voce Key

Cliccando su Finish, potremo esplorare l'entità realizzata automaticamente. Di default la classe:

• implementa l'interfaccia Serializable
• contiene i metodi di get set
• viene aggiunta in automatico come tag <class> persistence-unit persistence.xml

Creare semplici entità è molto semplice, ottenendo un POJO senza dovere mettere mano al codice. È possibile immettere tipi complessi come un java.util.ArrayList, specificando anche il parametro della lista (ad esempio java.util.ArrayList <String>).

Segnalazione di warnings ed errori

Hibernate non richiede la presenza dei nomi delle entità nel file persistence.xml. Provando a rimuovere il tag <class> relativo all'entità appena creata, otterremo per risposta la segnalazione di un errore del tipo:

Class "jpatestpack.EntityTest" is mapped, but is not included in any persistence unit

Negli articoli precedenti abbiamo visto però che lavorando con Hibernate questo non è un errore, pertanto possiamo modificare le impostazioni del progetto affinché tale errore non venga sollevato.

Possiamo scegliere se ignorarlo, oppure se segnalarlo come Info o come Warning. Ad esempio potremmo segnalarlo con un Warning giusto per tenerne traccia nel caso si decidesse di cambiare il persistence provider.

Per modificare le impostazioni, accedere alle proprietà del progetto, selezionare la sottoscheda JPA > Errors/Warnings, abilitare le modifiche (Enable project specific settings), esplorare il campo Type e modificare la voce "Class is mapped, but is not a persistence unit:", impostando nel menu a tendina la voce Warning e dare l'OK.

L'errore lascerà il posto a un semplice Warning. Allo stesso modo potremo evitare che la presenza di più di una persistence-unit generi un messaggio d'errore agendo sulla voce: Project/Multiple persistence units defined.

JPA Perspective, chiavi primarie e relazioni

Abbiamo esaminato un primo insieme di possibilità che ci viene offerto dal Dali tools. Aprendo la prospettiva JPA avremo a disposizione l'intero spettro di possibilità. Se la prospettiva non è già attiva: Window > Open Perspective > JPA (eventualmente Window > Open Perspective > Other… > JPA)

In basso a destra osserviamo la scheda JPA Details Embeddable Primary Key Generation

Premendo con il tasto sinistro sugli attributi dell'entità, la scheda mostrerà i dettagli del mapping dei campi. Avremo la possibilità di mappare l'attributo come Transient

Relazioni

Creando una seconda entità, ad esempio EntityTest2, tra i tipi messi a disposizione dall'Entity Properties sarà presente anche il tipo dell'entità creata in precedenza, EntityTest. Potremo pertanto impostare il tipo di relazione che lega le due classi.

Ipotizziamo dunque che l'entità EntityTest2 possiede un campo del tipo EntityTest. Cliccandoci sopra con il tasto sinistro del mouse potremo impostare il tipo di relazione nella scheda JPA Details.

Agendo sulle impostazioni del mapping, possiamo aggiungere l'annotazione desiderata, nel nostro caso @OneToOne. Una volta scelta l'annotazione nella scheda verranno mostrati una serie di dettagli personalizzabili, come entità target, tipo di Fetch, l'eventuale politica di Cascade, la strategia di Join. Per il nostro esempio è possibile lasciare tutto invariato.

Nella prossima sezione vedremo come generare le entità a partire dalle tabelle.

Connessione al database e generazione delle entità dalle tabelle

Finora abbiamo sempre ottenuto la tabella partendo dall'entità. JPA Project ci mette a disposizione il passaggio inverso, ottenere le entità partendo dalle tabella di un database. Per poter adoperare questo strumento serve però una connessione al database e un supporto non generico da parte delle piattaforma. In questa sezione vedremo come impostare la connessione, ottenere un supporto specializzato, per poter infine ottenere le entità partendo da un database già esistente.

Connessione al database

Avevamo già visto durante la creazione del progetto la possibilità di connettersi a un database ma l'avevamo tralasciata. Questa possibilità di norma non è necessaria, per cui avevamo sorvolato l'argomento.

Entrati nelle proprietà del progetto, accediamo alla voce JPA. Alla voce Connection potremo aggiungere una connessione (o selezionare una aggiunta in passato).

Scelto di aggiungere una connessione (Add connection...), selezioniamo il RDBMS cui siamo interessati (nel nostro caso HSQLDB), modifichiamo il nome proposto (se interessati a farlo) e premiamo su Next.

Se è la prima volta che effettuiamo la connessione, potremmo dover definire un nuovo driver (il pulsante New Driver Definition mostrato nell'immagine precedente). E, sempre se è la prima volta che effettuiamo la connessione, potremmo dover indicare la posizione dei driver hsqldb.jar. In tal caso, dalla scheda JAR List selezionare la voce hsqldb.jar e cliccare sul pulsante Edit Jar/Zip..., ciò consentirà di selezionare la posizione corretta del jar (è possibile trovarlo nella cartella hsqldb/lib).

A questo punto si aprirà una schermata che ci permetterà di impostare i parametri di connessione al database. Ipotizziamo di avere già disponibile un database attivo in modalità server. Ipotizzando che il database si chiami "db1", alias "testdb1", con user e password impostati sui valori default, dovremo impostare i seguenti campi:

Campo	Valore
Database	db1
Database location	hsql://localhost/testdb1

Per verificare il corretto inserimento dei dati utilizzare il tasto Test Connection Finish

Impostata la connessione, se non si è scelto di attivarla alla chiusura del wizard (Connect when the wizard completes Connect

Se la prospettiva JPA è attiva, le connessioni appaiono in basso a sinistra, nella scheda Data Source Explorer db1/Catalogs/PUBLIC/Schemas/PUBLIC/Tables

Hibernate Settings

Volendo generare le entità dal database, occorrerà qualcosa di più del supporto generico offerto dall'IDE. Accedendo alle proprietà del progetto, osservare la voce Platform. Se è disponibile o già selezionata la voce Hibernate (JPA 2.x), una volta selezionata questa voce non occorre fare altro, è possibile passare al prossimo paragrafo.

Se invece la voce non è disponibile e si vuole procedere con la generazione delle entità dalle tabelle del database, occorrerà installare il supporto Hibernate sull'IDE Eclipse. Per farlo, è possibile accedere all'Eclipse Marketplace, cercare la versione di Hibernate Tools idonea al proprio IDE e installarla.

Una volta completato il processo di installazione e riavviato l'IDE, occorrerà impostare la voce Platform (proprietà del progetto, scheda JPA) su Hibernate. È possibile a questo punto che sarà necessario modificare alcune delle impostazioni relative ai messaggi d'errore JPA, come visto nella precedente sezione.

Se permane un errore relativo al progetto (Console configuration "" does not exist), sarà necessario impostare le configurazioni di Hibernate (incorrere in problematiche di questo tipo non è raro nei progetti già esistenti). Occorre per prima cosa andare nelle configurazioni della console:

Run -> Run Configurations...

e selezionare le impostazioni di Hibernate, come mostrato nella figura seguente:

Occorrerà creare una nuova configurazione (tasto destro su Hibernate Console Configuration New JPATestProject Type JPA (jdk 1.5+) Database Connection [JPA Project Configured Connection] Hibernate Settings Enable Hibernate support Default Hibernate Console configuration

Una volta premuto OK clean Project -> Clean...

Generate Entities from Tables

Impostata una connessione (non deve essere necessariamente attiva, è sufficiente che sia stata impostata e provata per verificarne il corretto funzionamento) e impostato correttamente il supporto della piattaforma, siamo finalmente in grado di generare le entità partendo direttamente dalle tabelle.

Premendo con il tasto destro sul progetto troveremo tra le scelte la voce JPA Tools > Generate Entities from Tables...

Una volta scelto il package di destinazione (se scelto un package non esistente verrà creato automaticamente), sarà possibile utilizzare la configurazione della console già impostata, oppure (rimuovendo la spunta dalla voce Use Console Configuration), sarà possibile scegliere una specifica connessione al database. È possibile lasciare invariato l'autodetect per il dialetto del database.

Premuto il tasto Finish, le entità saranno importate nel progetto. A questo punto è possibile la presenza di alcune entità ripetute o eventuali segnalazioni di errori dovute al disallineamento tra il file persistence.xml e le entità, nel caso in cui non sia stata disattivata la segnalazione di errore riguardante la presenza di entità non mappate sul file persistence.xml.

SQL statements e Named Queries

Tra gli strumenti messi a disposizione dalla prospettiva JPA c'è l'editor per la scrittura ed esecuzione di statements SQL. Di norma può essere utilizzato come un'alternativa al Database Manager, con il vantaggio di non richiedere una finestra esterna all'IDE. Per attivare l'editor occorrerà premere sul pulsante Open scrapbook to edit SQL statements, presente nella scheda Data Source Explorer, cerchiato in rosso nell'immagine seguente in basso a sinistra.

L'immagine evidenzia i principali elementi di interesse. Premuto il pulsante indicato, si aprirà il Connection profile

Ora è possibile scrivere una interrogazione nella scheda SQL Scrapbook

select * from EntityTest

Premendo con il tasto destro sulla scheda SQL Scrapbook Execute Current Text SQL Results Status ResultX

Named Queries

Per la creazione di Named Queries, una volta selezionata una entità, sarà possibile aggiungerne una dalla scheda JPA Details. Esplorando il menu Queries, aggiungere (Add...) una query impostandone il nome e il tipo (Named Query o Named Native Query). Selezionata la query aggiunta, verranno visualizzati nella stessa scheda ulteriori dettagli e la possibilità di specificare la forma della query.

Convertire un progetto Java in un progetto JPA

Abbiamo visto che è possibile lavorare con normali progetti Java, ma che i tools del JPA Project possono risultare comodi, soprattutto nel caso di grossi progetti. Può risultare utile allora convertire un progetto Java già esistente in un progetto JPA. Per convertire un progetto esistente premere con il tasto destro sul progetto e scegliere l'opzione Configure > Convert to JPA Project...

Spuntare la voce JPA (di norma dovrebbe essere già spuntata), premere Next due volte e... ritorneremo alla schermata "JPA Facet" che ormai ci è divenuta familiare. A questo punto potremo specificare la piattaforma, le librerie e la connessione, tutti task già affrontati in precedenza.

Una volta terminato di impostare la schermata possiamo premere FINISH e il progetto verrà convertito. Potrebbe essere sollevato qualche errore (ad esempio il solito errore dovuto all'assenza del mapping delle entità nel file persistence.xml o qualche imprecisione nel file di persistenza), ma in compenso se si imposterà la piattaforma Hibernate le impostazioni Hibernate (Hibernate Settings) verranno impostate in automatico.

Perché utilizzare un progetto JPA

Abbiamo già visto che è possibile utilizzare JPA con un comune progetto Java. Perché allora ricorrere al progetto JPA? Un progetto JPA permette di risparmiare tempo, ad esempio evitando la necessità di scrivere i POJO, fornendo dei comodi wizard per l'impostazione delle entità o ottenendo le entità partendo direttamente dalle tabelle di un database. Inoltre la panoplia di strumenti messi a disposizione spesso evita la necessità di ricorrere a interfacce esterne all'IDE, ad esempio l'editor per SQL Statements consente di minimizzare l'uso del Database Manager.

Se si vuole cercare un difetto, l'unico riscontrato riguarda il tempo necessario ad estendere le funzionalità del'IDE. Se abbiamo un IDE per progetti JEE, probabilmente non occorrerà aggiungere niente, mentre se lavoriamo con un IDE classico e sarà necessario un po' di tempo per installare Dali Tools e supporti complementari per le funzionalità avanzate. Considerando i vantaggi precedentemente descritti, non è comunque tempo perso.