Въведение в ORMLite

1. Общ преглед

ORMLite е лека ORM библиотека за Java приложения. Той предоставя стандартни функции на ORM инструмент за най-често използваните случаи, без допълнителната сложност и режийни разходи на други ORM рамки.

Основните му характеристики са:

  • дефиниране на обектни класове чрез използване на Java анотации
  • разширяеми DAO класове
  • а QueryBuilder клас за създаване на сложни заявки
  • генерирани класове за създаване и пускане на таблици на база данни
  • подкрепа за транзакции
  • подкрепа за взаимоотношения между субектите

В следващите раздели ще разгледаме как можем да настроим библиотеката, да дефинираме класове обекти и да извършим операции върху базата данни, използвайки библиотеката.

2. Зависимости на Maven

За да започнем да използваме ORMLite, трябва да добавим зависимостта ormlite-jdbc към нашия pom.xml :

 com.j256.ormlite ormlite-jdbc 5.0 

По подразбиране това също включва зависимостта h2 . В нашите примери ще използваме H2 база данни в паметта, така че не се нуждаем от друг JDBC драйвер.

Ако искате да използвате различна база данни, ще ви трябва и съответната зависимост.

3. Дефиниране на класове обекти

За да настроим нашите класове модели за постоянство с ORMLite, има две основни пояснения, които можем да използваме:

  • @DatabaseTable за класа на обекта
  • @DatabaseField за свойствата

Нека започнем с дефиниране на обект на библиотека с поле с име и поле на libraryId, което също е първичен ключ:

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

В @DatabaseTable анотацията има желание tableName атрибут, който посочва името на таблицата, ако ние не искаме да се разчита на име на клас подразбиране.

За всяко поле, което искаме да продължи като колона в таблицата на базата данни, трябва да добавим анотацията @DatabaseField .

Свойството, което ще служи като първичен ключ за таблицата, може да бъде маркирано или с атрибути id , generatedId или generatedSequence . В нашия пример избираме атрибута generatedId = true , така че първичният ключ да бъде автоматично увеличен.

Също така имайте предвид, че класът трябва да има конструктор без аргументи с поне видимост на обхвата на пакета .

Няколко други познати атрибута, които можем да използваме за конфигуриране на полетата, са columnName , dataType , defaultValue , canBeNull , уникални .

3.1. Използване на JPA анотации

В допълнение към специфичните за ORMLite пояснения, ние също можем да използваме пояснения в стил JPA, за да дефинираме нашите обекти .

Еквивалентът на обекта на библиотеката , който дефинирахме преди да използваме стандартни анотации на JPA, ще бъде:

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

Въпреки че ORMLite разпознава тези пояснения, ние все още трябва да добавим зависимостта javax.persistence-api, за да ги използваме.

Пълният списък на поддържаните JPA анотации е @ Entity , @Id, @Column, @GeneratedValue, @ OneToOne , @ManyToOne, @ JoinColumn , @ Version .

4. ConnectionSource

За да работим с дефинираните обекти, трябва да настроим ConnectionSource .

За това можем да използваме класа JdbcConnectionSource, който създава единична връзка, или JdbcPooledConnectionSource, който представлява прост обединен източник на връзка:

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

Може да се използва и друг външен източник на данни с по-добра производителност, като ги обвиете в обект DataSourceConnectionSource .

5. Клас TableUtils

Въз основа на ConnectionSource , ние можем да използваме статични методи от клас TableUtils за извършване на операции върху схемата на базата данни :

  • createTable () - за създаване на таблица въз основа на дефиниция на клас на обект или обект DatabaseTableConfig
  • createTableIfNotExists () - подобно на предишния метод, с изключение на това, че ще създаде таблицата само ако не съществува; това работи само в бази данни, които го поддържат
  • dropTable () - за изтриване на таблица
  • clearTable () - за изтриване на данните от таблица

Нека да видим как можем да използваме TableUtils, за да създадем таблицата за нашия клас в библиотеката :

TableUtils.createTableIfNotExists(connectionSource, Library.class);

6. DAO Обекти

ORMLite съдържа една DaoManager клас, който може да създаде DAO обекти за нас с CRUD функционалност :

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

The DaoManager doesn't regenerate the class for each subsequent call of createDao(), but instead reuses it for better performance.

Next, we can perform CRUD operations on Library objects:

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);

The DAO is also an iterator that can loop through all the records:

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

However, ORMLite will only close the underlying SQL statement if the loop goes all the way to the end. An exception or a return statement may cause a resource leak in your code.

For that reason, the ORMLite documentation recommends we use the iterator directly:

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

This way, we can close the iterator using a try-with-resources or a finally block and avoid any resource leak.

6.1. Custom DAO Class

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

Всеки DAO може да се използва за получаване на обект QueryBuilder , който след това можем да използваме за изграждане на по-мощни заявки.

Този клас съдържа методи, които съответстват на общи операции, използвани в SQL заявка като: selectColumns (), where (), groupBy (), having (), countOf (), distinct (), orderBy (), join ().

Нека да видим пример за това как можем да намерим всички записи в библиотеката , които имат повече от една свързана книга :

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

9. Заключение

В тази статия видяхме как можем да дефинираме обекти, използващи ORMLite, както и основните характеристики на библиотеката, които можем да използваме за манипулиране на обекти и свързаните с тях релационни бази данни.

Пълният изходен код на примера може да бъде намерен в GitHub.