Introduzione a ORMLite

1. Panoramica

ORMLite è una libreria ORM leggera per applicazioni Java. Fornisce le funzionalità standard di uno strumento ORM per i casi d'uso più comuni, senza la complessità aggiuntiva e il sovraccarico di altri framework ORM.

Le sue caratteristiche principali sono:

  • definizione di classi di entità utilizzando le annotazioni Java
  • classi DAO estensibili
  • una classe QueryBuilder per la creazione di query complesse
  • classi generate per creare ed eliminare tabelle di database
  • supporto per le transazioni
  • supporto per le relazioni di entità

Nelle sezioni successive, daremo un'occhiata a come possiamo impostare la libreria, definire classi di entità ed eseguire operazioni sul database utilizzando la libreria.

2. Dipendenze di Maven

Per iniziare a utilizzare ORMLite, dobbiamo aggiungere la dipendenza ormlite-jdbc al nostro pom.xml :

 com.j256.ormlite ormlite-jdbc 5.0 

Per impostazione predefinita, questo introduce anche la dipendenza h2 . Nei nostri esempi, useremo un database in memoria H2 , quindi non abbiamo bisogno di un altro driver JDBC.

Se desideri utilizzare un database diverso, avrai bisogno anche della dipendenza corrispondente.

3. Definizione delle classi di entità

Per impostare le nostre classi modello per la persistenza con ORMLite, ci sono due annotazioni principali che possiamo usare:

  • @DatabaseTable per la classe di entità
  • @DatabaseField per le proprietà

Iniziamo definendo un'entità Library con un campo nome e un campo libraryId che è anche una chiave primaria:

@DatabaseTable(tableName = "libraries") public class Library { @DatabaseField(generatedId = true) private long libraryId; @DatabaseField(canBeNull = false) private String name; public Library() { } // standard getters, setters }

Il @DatabaseTable annotazione possiede un optional tableName attributo che specifica il nome della tabella, se non vogliamo fare affidamento su un nome di classe di default.

Per ogni campo che vogliamo rendere persistente come colonna nella tabella del database, dobbiamo aggiungere l' annotazione @DatabaseField .

La proprietà che fungerà da chiave primaria per la tabella può essere contrassegnata con gli attributi id , generatedId o generatedSequence . Nel nostro esempio, scegliamo l' attributo generatedId = true in modo che la chiave primaria venga automaticamente incrementata.

Inoltre, si noti che la classe deve avere un costruttore senza argomenti con almeno visibilità dell'ambito del pacchetto .

Alcuni altri attributi familiari che possiamo usare per configurare i campi sono columnName , dataType , defaultValue , canBeNull , unique .

3.1. Utilizzo delle annotazioni JPA

Oltre alle annotazioni specifiche di ORMLite, possiamo anche utilizzare annotazioni in stile JPA per definire le nostre entità .

L'equivalente dell'entità Library che abbiamo definito prima di utilizzare le annotazioni standard JPA sarebbe:

@Entity public class LibraryJPA { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private long libraryId; @Column private String name; // standard getters, setters }

Sebbene ORMLite riconosca queste annotazioni, è comunque necessario aggiungere la dipendenza javax.persistence-api per utilizzarle.

L'elenco completo dei supportati JPA annotazioni è @ Entity , @Id, @Column, @GeneratedValue, @ OnetoOne , @ManyToOne, @ JoinColumn , @ Version .

4. ConnectionSource

Per lavorare con gli oggetti definiti, dobbiamo impostare un ConnectionSource .

Per questo, possiamo usare la classe JdbcConnectionSource che crea una singola connessione, o la JdbcPooledConnectionSource che rappresenta una semplice sorgente di connessione in pool:

JdbcPooledConnectionSource connectionSource = new JdbcPooledConnectionSource("jdbc:h2:mem:myDb"); // work with the connectionSource connectionSource.close();

È possibile utilizzare anche altre origini dati esterne con prestazioni migliori, inserendole in un oggetto DataSourceConnectionSource .

5. TableUtils Class

In base a ConnectionSource , possiamo utilizzare metodi statici della classe TableUtils per eseguire operazioni sullo schema del database :

  • createTable () - per creare una tabella basata su una definizione di classe di entità o un oggetto DatabaseTableConfig
  • createTableIfNotExists () - simile al metodo precedente, tranne che creerà la tabella solo se non esiste; funziona solo su database che lo supportano
  • dropTable () - per eliminare una tabella
  • clearTable () - per eliminare i dati da una tabella

Vediamo come possiamo usare TableUtils per creare la tabella per la nostra classe Library :

TableUtils.createTableIfNotExists(connectionSource, Library.class);

6. Oggetti DAO

ORMLite contiene una classe DaoManager che può creare oggetti DAO per noi con funzionalità CRUD :

Dao libraryDao = DaoManager.createDao(connectionSource, Library.class);

Il DaoManager non rigenera la classe per ogni chiamata successiva di createDao (), ma invece riutilizza per prestazioni migliori.

Successivamente, possiamo eseguire operazioni CRUD sugli oggetti Library :

Library library = new Library(); library.setName("My Library"); libraryDao.create(library); Library result = libraryDao.queryForId(1L); library.setName("My Other Library"); libraryDao.update(library); libraryDao.delete(library);

Il DAO è anche un iteratore che può scorrere tutti i record:

libraryDao.forEach(lib -> { System.out.println(lib.getName()); });

Tuttavia, ORMLite chiuderà l'istruzione SQL sottostante solo se il ciclo va fino alla fine. Un'eccezione o un'istruzione di ritorno può causare una perdita di risorse nel codice.

Per questo motivo, la documentazione di ORMLite consiglia di utilizzare direttamente l'iteratore:

try (CloseableWrappedIterable wrappedIterable = libraryDao.getWrappedIterable()) { wrappedIterable.forEach(lib -> { System.out.println(lib.getName()); }); }

In questo modo, possiamo chiudere l'iteratore usando un try-with-resources o un blocco finally ed evitare qualsiasi perdita di risorse.

6.1. Classe DAO personalizzata

If we want to extend the behavior of the DAO objects provided, we can create a new interface which extends the Dao type:

public interface LibraryDao extends Dao { public List findByName(String name) throws SQLException; }

Then, let's add a class that implements this interface and extends the BaseDaoImpl class:

public class LibraryDaoImpl extends BaseDaoImpl implements LibraryDao { public LibraryDaoImpl(ConnectionSource connectionSource) throws SQLException { super(connectionSource, Library.class); } @Override public List findByName(String name) throws SQLException { return super.queryForEq("name", name); } }

Note that we need to have a constructor of this form.

Finally, to use our custom DAO, we need to add the class name to the Library class definition:

@DatabaseTable(tableName = "libraries", daoClass = LibraryDaoImpl.class) public class Library { // ... }

This enables us to use the DaoManager to create an instance of our custom class:

LibraryDao customLibraryDao = DaoManager.createDao(connectionSource, Library.class);

Then we can use all the methods from the standard DAO class, as well as our custom method:

Library library = new Library(); library.setName("My Library"); customLibraryDao.create(library); assertEquals( 1, customLibraryDao.findByName("My Library").size());

7. Defining Entity Relationships

ORMLite uses the concept of “foreign” objects or collections to define relationships between entities for persistence.

Let's take a look at how we can define each type of field.

7.1. Foreign Object Fields

We can create a unidirectional one-to-one relationship between two entity classes by using the foreign=true attribute on a field annotated with @DatabaseField. The field must be of a type that's also persisted in the database.

First, let's define a new entity class called Address:

@DatabaseTable(tableName="addresses") public class Address { @DatabaseField(generatedId = true) private long addressId; @DatabaseField(canBeNull = false) private String addressLine; // standard getters, setters }

Next, we can add a field of type Address to our Library class which is marked as foreign:

@DatabaseTable(tableName = "libraries") public class Library { //... @DatabaseField(foreign=true, foreignAutoCreate = true, foreignAutoRefresh = true) private Address address; // standard getters, setters }

Notice that we've also added two more attributes to the @DatabaseField annotation: foreignAutoCreate and foreignAutoRefresh, both set to true.

The foreignAutoCreate=true attribute means that when we save a Library object with an address field, the foreign object will also be saved, provided its id is not null and has a generatedId=true attribute.

If we set foreignAutoCreate to false, which is the default value, then we'd need to persist the foreign object explicitly before saving the Library object that references it.

Similarly, the foreignAutoRefresh=true attribute specifies that when retrieving a Library object, the associated foreign object will also be retrieved. Otherwise, we'd need to refresh it manually.

Let's add a new Library object with an Address field and call the libraryDao to persist both:

Library library = new Library(); library.setName("My Library"); library.setAddress(new Address("Main Street nr 20")); Dao libraryDao = DaoManager.createDao(connectionSource, Library.class); libraryDao.create(library);

Then, we can call the addressDao to verify that the Address has also been saved:

Dao addressDao = DaoManager.createDao(connectionSource, Address.class); assertEquals(1, addressDao.queryForEq("addressLine", "Main Street nr 20") .size());

7.2. Foreign Collections

For the many side of a relationship, we can use the types ForeignCollection or Collection with a @ForeignCollectionField annotation.

Let's create a new Book entity like the ones above, then add a one-to-many relationship in the Library class:

@DatabaseTable(tableName = "libraries") public class Library { // ... @ForeignCollectionField(eager=false) private ForeignCollection books; // standard getters, setters }

In addition to this, it's required that we add a field of type Library in the Book class:

@DatabaseTable public class Book { // ... @DatabaseField(foreign = true, foreignAutoRefresh = true) private Library library; // standard getters, setters }

The ForeignCollection has add() and remove() methods that operate on the records of type Book:

Library library = new Library(); library.setName("My Library"); libraryDao.create(library); libraryDao.refresh(library); library.getBooks().add(new Book("1984"));

Here, we've created a library object, then added a new Book object to the books field, which also persists it to the database.

Note that since our collection is marked as lazily loaded (eager=false), we need to call the refresh() method before being able to use the book field.

We can also create the relationship by setting the library field in the Book class:

Book book = new Book("It"); book.setLibrary(library); bookDao.create(book);

To verify that both Book objects are added to the library we can use the queryForEq() method to find all the Book records with the given library_id:

assertEquals(2, bookDao.queryForEq("library_id", library).size());

Here, the library_id is the default name of the foreign key column, and the primary key is inferred from the library object.

8. QueryBuilder

Ogni DAO può essere utilizzato per ottenere un oggetto QueryBuilder che possiamo quindi sfruttare per creare query più potenti.

Questa classe contiene metodi che corrispondono alle operazioni comuni utilizzate in una query SQL come: selectColumns (), where (), groupBy (), having (), countOf (), separate (), orderBy (), join ().

Vediamo un esempio di come possiamo trovare tutti i record della Biblioteca che hanno più di un Libro associato:

List libraries = libraryDao.queryBuilder() .where() .in("libraryId", bookDao.queryBuilder() .selectColumns("library_id") .groupBy("library_id") .having("count(*) > 1")) .query();

9. Conclusione

In questo articolo, abbiamo visto come possiamo definire entità usando ORMLite, così come le caratteristiche principali della libreria che possiamo usare per manipolare oggetti e i loro database relazionali associati.

Il codice sorgente completo dell'esempio può essere trovato su GitHub.