Документація розробника Hibernate – Глава I. Доступ до бази даних

Представляю вашій увазі переклад першої глави офіційній документації Hibernate.

Переклад статті актуальний для версії Hibernate 4.2.19.Final

Наступна голова — Документація розробника Hibernate – Глава II. Транзакції і контроль багатопоточності

Зміст
 <a href="#p>Передмова
 1. Доступ до бази даних
  1.1. Підключення
   1.1.1. Конфігурація
   1.1.2. Отримання JDBC-з'єднання
  1.2. Пулинг сполук (Connection pooling)
   1.2.1. Пулинг з допомогою с3р0
   1.2.2. Пулинг з допомогою Proxool
   1.2.3. Отримання сполук від сервера додатків, через JNDI
   1.2.4. Інше по конфігурації з'єднань
   1.2.5. Додаткові властивості конфігурації
  1.3. Діалекти
   1.3.1. Вказівка діалекту для використання
   1.3.2. Дозвіл діалекту
  1.4. Автоматична генерація схеми за допомогою Schema Export
   1.4.1. Кастомізація файлів мапінгу (Customizing the mapping files)
   1.4.2. Запуск інструменту SchemaExport

Передмова
Робота з об'єктно-орієнтованим, так і з реляційними базами даних (далі БД, прим.перекл.) може бути вельми обтяжливою і витратною з точки зору витраченого часу. Витрати на розробку істотно вище з-за неспівпадання парадигм подання даних в об'єктах і реляційних БД. Hibernate є рішенням т. н. об'єктно-реляційного проектування для Java. Термін об'єктно-реляційного проектування відноситься до техніки проектування (мапінгу даних з об'єктної моделі подання до реляційної моделі представлення (і навпаки). См. en.wikipedia.org/wiki/Object-relational_mapping для більш докладного ознайомлення.

ВажливоХоча для використання Hibernate не обов'язково добре володіти SQL, розуміння основних концепцій зіграє непогану роль у швидкому і повному освоєнні Hibernate. Кращим підмогою в освоєнні є розуміння принципів моделювання даних. Інформація за нижченаведеним посиланням може виявитися корисною

Hibernate не тільки дбає про проектуванні Java-класів у таблиці БД (а також проектуванні базових типів Java типів SQL), але і надає механізми формування запитів і вибірок даних. Він може істотно знизити час на розробку, яка в старому стилі велася шляхом ручної роботи з даними з використанням SQL і JDBC. Головна мета архітектурного дизайну Hibernate – позбавлення розробника від щоденних завдань роботи з даними БД, шляхом позбавлення від потреб написання власної логіки роботи з даними через SQL і JDBC. Однак, на відміну від інших persistence-рішень, Hibernate не приховує від вас можливість використовувати всю міць SQL, і гарантує, що ваші вкладення в реляційні технології і знання, як і раніше мають силу.
Hibernate може бути не кращим рішенням для додатків, що зберігають всю свою бізнес-логіку в збережених процедурах, воно скоріше підходить для об'єктно-орієнтованих моделей і логіки в середньому (бізнес) шарі додатку, написаному на Java. Однак, Hibernate абсолютно точно може допомогти вам позбавитися або инкапсулировать логіку специфічного SQL-коду, а також впоратися з повсякденними завданнями трансляції результатів ваших запитів з табличного подання до граф об'єктів.

1. Доступ до бази даних
1.1. Підключення
Hibernate з'єднується з базою від імені вашої програми. З'єднання може здійснюватися через різного роду механізми, а саме:
  • Вбудований пул з'єднань
  • javax.sql.DataSource
  • Пули сполук, також можна використовувати сторонні відкриті рішення для пулів:
    • c3p0
    • proxool

  • Власноруч створені додатком JDBC-з'єднання. Це нерекомендуемый підхід і єдина причина його використання – робота з застарілим (legacy) оточенням.
ВажливоВбудований пул з'єднань не призначений для роботи в «бойовому» оточенні.

Hibernate отримує JDBC-з'єднання по мірі необхідності через інтерфейс org.hibernate.service.jdbc.connections.spi.ConnectionProvider. Додатки можуть також надавати свої реалізації інтерфейсу org.hibernate.service.jdbc.connections.spi.ConnectionProvider для визначення кастомного підходу до надання сполук Hibernate'у. (З іншого пулу з'єднань, наприклад)

1.1.1. Конфігурація
Ви можете налаштувати з'єднання до бази даних, використовуючи property-файл, через XML-дескриптор розгортання або програмно.

Приклад 1.1. hibernate.properties для пулу з'єднань c3p0

hibernate.connection.driver_class = org.postgresql.Driver
hibernate.connection.url = jdbc:postgresql://localhost/mydatabase
hibernate.connection.username = myuser
hibernate.connection.password = secret
hibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20
hibernate.c3p0.timeout=1800
hibernate.c3p0.max_statements=50
hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect

Приклад 1.2. hibernate.cfg.xml для з'єднання до вбудованій базі даних HSQL

<?xml version='1.0' encoding='utf-8'?>

<hibernate-configuration
xmlns="http://www.hibernate.org/xsd/hibernate-configuration"
xsi:schemaLocation="http://www.hibernate.org/xsd/hibernate-configuration hibernate-configuration-4.0.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<session-factory>
<!-- Database connection settings -->
<property name="connection.driver_class">org.hsqldb.jdbcDriver</property>
<property name="connection.url">jdbc:hsqldb:hsql://localhost</property>
<property name="connection.username">sa</property>
<property name="connection.password"></property>

<!-- JDBC connection pool (use the built-in) -->
<property name="connection.pool_size">1</property>

<!-- SQL dialect -->
<property name="dialect">org.hibernate.dialect.HSQLDialect</property>

<!-- Enable Hibernate's automatic session context management -->
<property name="current_session_context_class">thread</property>

<!-- Disable the second level cache -->
<property name="cache.provider_class">org.hibernate.cache.internal.NoCacheProvider</property>

<!-- Echo all executed SQL to stdout -->
<property name="show_sql">true</property>

<!-- Drop and re-create the database schema on startup -->
<property name="hbm2ddl.auto">update</property>
<mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/>
</session-factory>
</hibernate-configuration>


1.1.1.1. Програмна конфігурація
Екземпляр об'єкта org.hibernate.cfg.Configuration представляє повний набір типів маппингов на базу даних. Об'єкт org.hibernate.cfg.Configuration створює иммутабельный об'єкт org.hibernate.SessionFactory, і компілює маппинги з різних XML-файлів. Ви можете вказати файли для мапінгу безпосередньо, або Hibernate може знайти їх за вас.

Приклад 1.3. Вказівка файлів для мапінгу безпосередньо

Ви можете отримати об'єкт org.hibernate.cfg.Configuration, створивши його і вказавши XML-документи для мапінгу безпосередньо. Якщо файли для мапінгу знаходяться в classpath, використовуйте метод addResource().

Configuration cfg = new Configuration()
.addResource("Item.hbm.xml")
.addResource("Bid.hbm.xml");


Приклад 1.4. Hibernate знаходить файли за вас

Метод addClass() вказує Hibernate шукати mapping-файли через classpath, грунтуючись на ім'я класу, при цьому позбавляючи вас від необхідності вказувати імена файлів самому. У наступному прикладі, він шукає org/hibernate/auction/Item.hbm.xml org/hibernate/auction/Bid.hbm.xml.

Configuration cfg = new Configuration()
.addClass(org.hibernate.auction.Item.class)
.addClass(org.hibernate.auction.Bid.class);


Приклад 1.5. Зазначення властивостей конфігурації

Configuration cfg = new Configuration()
.addClass(org.hibernate.auction.Item.class)
.addClass(org.hibernate.auction.Bid.class)
.setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
.setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
.setProperty("hibernate.order_updates", "true");


Інші способи програмної конфігурації Hibernate
  • Передача примірника java.util.Properties Configuration.setProperties().
  • Установка системного властивості, використовуючи java -Dproperty=value


1.1.2. Отримання JDBC-з'єднання
Після того, як ви сконфигурируете Основні jdbc-властивості Hibernate, ви можете використовувати метод openSession класу org.hibernate.SessionFactory для відкриття сесій. Сесії відкриють JDBC-з'єднання на вимогу, грунтуючись на наданій конфігурації.

Приклад 1.6. Відкриття сесії

Session session = sessions.openSession();

Основні jdbc-властивості Hibernate
  • hibernate.connection.driver_class
  • hibernate.connection.url
  • hibernate.connection.username
  • hibernate.connection.password
  • hibernate.connection.pool_size


1.2. Пулинг сполук (Connection pooling)
Внутрішній алгоритм пулинга сполук в Hibernate досить рудіментарен, і потрібен, здебільшого, для розробки і тестування. Використовуйте сторонні (3rd party) пули для кращої продуктивності та стабільності. Для використання 3rd party пулу, замініть значення властивості hibernate.connection.pool_size на відповідні специфіці вашого вибраного пулу. Це відключить використання вбудованого пулу Hibernate.

1.2.1. Пулинг з допомогою c3p0
C3P0 – опенсорсний пул JDBC-з'єднань, що розповсюджується разом з Hibernate в директорії lib/. Hibernate буде використовувати свій власний org.hibernate.service.jdbc.connections.internal.C3P0ConnectionProvider для пулинга сполук, при налаштуванні властивостей hibernate.c3p0.*

Важливі конфігураційні властивості для c3p0
  • hibernate.c3p0.min_size
  • hibernate.c3p0.max_size
  • hibernate.c3p0.timeout
  • hibernate.c3p0.max_statements


1.2.2. Пулинг з допомогою Proxool
Proxool — інший опенсорсний пул, поширюваний разом з Hibernate в директорії lib/. Hibernate буде використовувати свій власний org.hibernate.service.jdbc.connections.internal.ProxoolConnectionProvider для пулинга з'єднань при відповідній настройці hibernate.proxool.*. На відміну від c3p0, proxool вимагає деяких додаткових параметрів налаштування, які описані в документації, доступною на proxool.sourceforge.net/configure.html.

Таблиця 1.1. Важливі конфігураційні властивості для пулу з'єднань Proxool
Властивість Опис
hibernate.proxool.xml Налаштуйте провайдер Proxool, використовуючи вказаний файл XML (.xml додається автоматично)
hibernate.proxool.properties Налаштуйте провайдер Proxool, використовуючи зазначений property-файл (.properties додається автоматично)
hibernate.proxool.existing_pool Конфігурувати провайдер Proxool з наявного пулу
hibernate.proxool.pool_alias Псевдонім пулу Proxool. Необхідний.
1.2.3. Отримання сполук від сервера додатків, через JNDI
Для використання Hibernate всередині сервера додатків, налаштуйте Hibernate для отримання сполук від javax.sql.Datasource, зареєстрованому в JNDI, встановивши принаймні одне з наступних властивостей:
Важливі властивості для джерел даних JNDI
  • hibernate.connection.datasource ()
  • hibernate.jndi.url
  • hibernate.jndi.class
  • hibernate.connection.username
  • hibernate.connection.password
JDBC-з'єднання, отримані з джерела даних JNDI, автоматично беруть участь у container-managed транзакції сервера додатків.

1.2.4. Інше по конфігурації з'єднань
Ви можете передавати довільні властивості з'єднання, додаючи перед ними hibernate.connection. Наприклад, для вказівки властивості charSet використовуйте ім'я hibernate.connection.charSet.
Ви можете визначити свою стратегію для отримання JDBC-з'єднань, реалізувавши інтерфейс org.hibernate.service.jdbc.connections.spi.ConnectionProvider, і вказавши вашу власну реалізацію за допомогою властивості hibernate.connection.provider_class

1.2.5. Додаткові властивості конфігурації
На додаток до властивостей, перерахованих вище, Hibernate включає в себе безліч інших параметрів. См. більш докладний список на http://docs.jboss.org/hibernate/orm/4.2/devguide/en-US/html_single/.

1.3. Діалекти
Хоча SQL відносно стандартизований, кожен постачальник СУБД використовує свій набір підтримуваних синтаксисів. У цього є і інший термін, званий діалектом. Hibernate підтримує різні варіації діалектів через клас org.hibernate.dialect.Dialect і різні підкласи для кожного vendor-діалекту.

Таблиця 1.2. Підтримувані діалекти СУБД


1.3.1. Вказівка діалекту для використання
Розробник може вручну вказати діалект для використання, вказавши у властивості hibernate.dialect потрібне ім'я підкласу org.hibernate.dialect.Dialect.

1.3.2. Дозвіл діалекту
Заздалегідь припустивши, що org.hibernate.service.jdbc.connections.spi.ConnectionProvider був налаштований, Hibernate спробує автоматично визначити діалект, грунтуючись на java.sql.DatabaseMetaData одержуваним з об'єкта java.sql.Connection, який у свою чергу дістається з org.hibernate.service.jdbc.connections.spi.ConnectionProvider.
Ця функціональність надається примірниками org.hibernate.service.jdbc.dialect.spi.DialectResolver, зареєстрованими самим фреймворком. Hibernate йде разом зі стандартним набором распознаваний. Якщо у вашому додатку потрібні додаткові можливості розпізнавання діалекту, цілком можливо зареєструвати кастомний реалізацію org.hibernate.service.jdbc.dialect.spi.DialectResolver, як показано нижче:
Зареєстровані реалізації org.hibernate.service.jdbc.dialect.spi.DialectResolver додаються у внутрішній список resolverов, так що вони мають пріоритет над вже раніше зареєстрованими resolver'ами, а також над стандартними.

1.4. Автоматична генерація схеми за допомогою SchemaExport
SchemaExport – утиліта Hibernate, яка генерує DDL-скрипти з ваших файлів мапінгу. Згенерована схема включає в себе обмеження посилальної цілісності (referential integrity constraints), основні та зовнішні ключі сутностей і таблиць колекцій. Вона також створює таблиці для послідовностей(sequences) і спроецированных id-генераторів (identity generators).
ВажливоВи повинні вказати діалект SQL через властивість hibernate.dialect, коли використовуєте цю утиліту, так як DDL сам по собі специфічний для кожного вендора. Див подробиці Секції 1.3, «Діалекти».

Перед тим, як Hibernate зможе згенерувати вашу схему, ви повинні кастомизировать ваші файли мапінгу.

1.4.1. Кастомізація файлів мапінгу (Customizing the mapping files)
Hibernate надає ряд елементів і атрибутів для ваших файлів мапінгу. Вони перераховані в Таблиці 1.3, «Елементи і аттрібути, що надаються для кастомізації файлів мапінгу», а логічний порядок кастомізації представлений у Процедурі 1.1, «Кастомізація схеми».

Таблиця 1.3. Елементи та атрибути, що надаються для кастомізації файлів мапінгу
Ім'я Тип значення Опис
length number Довжина колонки
precision number Десяткову точність колонки
scale number Десятковий масштаб колонки
not-null true або false Може колонка містити null-значення
unique true або false Містить колонка тільки унікальні значення
index string Ім'я багатоколонкового індексу
unique-key string Ім'я багатоколонкового обмеження на унікальність
foreign-key string назва обмеження зовнішнього ключа, що генерується для асоціацій.
Це відноситься до <one-to-one>, <many-to-one>, <key>, і <many-to-many> елементів. inverse=«true» пропускаються SchemaExport.
sql-type string Перевизначає тип колонки по-замовчуванню. Це відноситься тільки до елемента <column>.
default string Значення за замовчуванням для колонки
check string SQL обмеження (SQL check constraint) або на колонку, або на таблицю
Процедура 1.1. Кастомізація схеми

1. Установка довжини, точності, і масштабу елементів мапінгу.

Безліч елементів мапінгу визначають необов'язкові атрибути, такі як довжина, точність та масштаб.
<property name="zip" length="5"/>
<property name="balance" precision="12" scale="2"/>


2. Установка not-null, UNIQUE, unique-key атрибутів.

not-null та UNIQUE атрибути генерують обмеження на табличні колонки.
Атрибут unique-key групує колонки в єдине обмеження унікальності. Атрибут перевизначає ім'я будь-якого згенерованого обмеження унікальності.
<many-to-one name="bar" column="barId" not-null="true"/>
<element column="serialNumber" type="long" not-null="true" unique="true"/>

<many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>
<property name="employeeId" unique-key="OrgEmployee"/>

3. Установка index і foreign-key атрибутів.

Атрибут index вказує ім'я індексу для його створення, використовуючи спроецированную колонку або колонки. Ви можете згрупувати кілька колонок по одному індексу, вказавши в кожній з них ім'я одного і того ж індексу.
Атрибут зовнішнього ключа (foreign key) перевизначає ім'я будь-якого згенерованого обмеження зовнішнього ключа.
<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>


4. Установка дочірніх <column>-елементів.

Безліч елементів мапінгу допускають використання дочірніх <column> елементів. Це буває корисно для мапінгу типів, що включають у себе кілька колонок.
<property name="name" type="my.customtypes.Name"/>
<column name="last" not-null="true" index="bar_idx" length="30"/>
<column name="first" not-null="true" index="bar_idx" length="20"/>
<column name="initial"/>
</property>


5. Установка атрибута default.

Атрибут default являє собою значення за замовчуванням для колонки. Додати значення до спроецированному властивості перед збереженням нового екземпляра класу.
<property name="credits" type="integer" insert="false">
<column name="credits" default="10"/>
</property>
<version name="version" type="integer" insert="false">
<column name="version" default="0"/>
</version>


6. Установка атрибута sql-type.
Використовуйте атрибут sql-type для перевизначення мапінгу за замовчуванням для типів Java типи SQL.
<property name="balance" type="float">
<column name="balance" sql-type="decimal(13,3)"/>
</property>


7. Установка атрибута check.
Використовуйте атрибут check для вказівки обмеження check.
<property name="foo" type="integer">
<column name="foo" check="foo > 10"/>
</property>
<class name="Foo" table="foos" check="bar < 100.0">
...
<property name="bar" type="float"/>
</class>


8.Додавання <comment> елементів до вашої схемою.
Використовуйте елемент <comment> для вказівки коментарів для згенерованої схеми.
<class name="Customer" table="CurCust">
<comment>Current customers only</comment>
...
</class>


1.4.2. Запуск інструменту SchemaExport
Інструмент SchemaExport записує DDL-скрипт в стандартний потік виводу, виконує DDL, або і те, і інше відразу.
Приклад 1.7. Синтаксис SchemaExport
java -cp hibernate_classpaths org.hibernate.tool.hbm2ddl.SchemaExport options mapping_files 

Таблиця 1.4. Опції SchemaExport
Опція Опис
--quiet Не виводити скрипт в стандартний потік виводу
--drop Тільки видаляти таблиці
--create Тільки створювати таблиці
--text Не експортувати в БД
--output=my_schema.ddl Вивести скрипт в зазначений файл
--naming=eg.MyNamingStrategy вибір NamingStrategy
--namingdelegator=eg.MyNamingStrategyDelegator вибір NamingStrategyDelegator
--config=hibernate.cfg.xml Читання конфігурації Hibernate з файлу XML
--properties=hibernate.properties Читання властивостей БД з вказаного файлу
--format Охайне форматування SQL
--delimiter=; Роздільник рядків
ВажливоОпції --naming і --namingdelegator, не повинні використовуватися разом

Приклад 1.8. Вбудовування SchemaExport в ваш додаток

Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);

Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.