Глава 3. Конфигурирование

1. 3.1. Программная конфигурация
2. 3.2. Получение SessionFactory
3. 3.3. Соединения JDBC
4. 3.4. Необязательные свойства конфигурации
   1. 3.4.1. Диалекты SQL
   2. 3.4.2. Outer Join Fetching
   3. 3.4.3. Двоичные потоки
   4. 3.4.4. Кэш второго уровня и кэш запросов
   5. 3.4.5. Замена языка запроса
   6. 3.4.6. Статистика Hibernate
5. 3.5. Логирование
6. 3.6. Имплементация NamingStrategy
7. 3.7. Имплементация PersisterClassProvider
8. 3.8. XML-файл конфигурации
9. 3.9. Интеграция на сервер приложений Java EE
   1. 3.9.1. Конфигурация стратегии транзакций
   2. 3.9.2. JNDI-связанный SessionFactory
   3. 3.9.3. Управление текущим контекстом сессии   помощью JTA

Hibernate предназначен для работы во многих различных средах, поэтому для него существует широкий диапазон параметров конфигурации. Большинство из них имеют разумные значения по умолчанию, а Hibernate распространяется с примером файла hibernate.properties в etc/, который отображает различные параметры. Просто подставьте пример файла в свой classpath и настройте его в соответствии с вашими потребностями.

3.1. Программная конфигурация

Экземпляр org.hibernate.cfg.Configuration представляет собой полный набор отображений типов Java приложения для базы данных SQL. Конфигурация org.hibernate.cfg.Configuration используется для создания неизменяемого org.hibernate.SessionFactory. Отображения компилируются из различных XML-файлов.

Вы можете получить экземпляр org.hibernate.cfg.Configuration, создав его непосредственно и указав XML-файлы отображений. Если файлы отображений находятся в classpath, используйте addResource(). Например:

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

Альтернативный способ — указать отображаемый класс и позволить Hibernate найти XML-файлы отображений:

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

Затем Hibernate будет искать файлы отображаемый с именами /org/hibernate/auction/Item.hbm.xml и /org/hibernate/auction/Bid.hbm.xml в classpath. Такой подход исключает любые жестко заданные имена файлов.

org.hibernate.cfg.Configuration также позволяет указать свойства конфигурации. Например:

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. Некоторые альтернативные варианты включают:

1. Передачу экземпляра java.util.Properties в Configuration.setProperties().
2. Размещение файла с именем hibernate.properties в корне classpath.
3. Установка System-свойств с использование java -Dproperty=value.
4. Включение элементов <property> в файл hibernate.cfg.xml (обсуждается ниже).

Самый простой способ из перечисленных - hibernate.properties.

Конфигурация org.hibernate.cfg.Configuration содержит стартовые настройки, которые будут отброшены после создания SessionFactory.

3.2. Получение SessionFactory

Когда все отображения были проанализированы с помощью org.hibernate.cfg.Configuration, приложение должно получить фабрику для экземпляров org.hibernate.Session. Эта фабрика предназначена для совместного использования всеми прикладными потоками:

SessionFactory sessions = cfg.buildSessionFactory();

Hibernate позволяет вашему приложению создавать экземпляры более чем одного org.hibernate.SessionFactory. Это полезно, если вы используете несколько баз данных.

3.3. Соединения JDBC

Желательно, чтобы org.hibernate.SessionFactory создавал и объединял в пул JDBC-соединения для вас. Такой подход позволяет очень просто открыть org.hibernate.Session:

Session session = sessions.openSession(); // открыть новый Session

После запуска задачи, требующей доступа к базе данных, соединение JDBC будет получено из пула.

Прежде чем вы сможете это сделать, нужно передать некоторые свойства соединения JDBC в Hibernate. Все имена и семантика свойств Hibernate определены в классе org.hibernate.cfg.Environment. Ниже перечислены наиболее важные настройки для конфигурации соединения JDBC.

Таблица 3.1. Свойства Hibernate JDBC

Алгоритм объединения пула Hibernate довольно рудиментарный. Он призван помочь вам начать работу и не предназначен для использования в продакшене или даже для тестирования производительности. Вы должны использовать сторонний пул для обеспечения максимальной производительности и стабильности. Просто замените свойство hibernate.connection.pool_size с конкретными настройками пула соединений. Это отключит внутренний пул Hibernate. Например, вы можете использовать c3p0.

C3P0 — пул соединений JDBC с открытым исходным кодом, распространяемый вместе с Hibernate в каталоге lib. Hibernate будет использовать свой org.hibernate.connection.C3P0ConnectionProvider для объединения пулов если вы установите свойства hibernate.c3p0.*. Если вы хотите использовать Proxool, обратитесь к упакованным hibernate.properties и веб-сайту Hibernate за дополнительной информацией.

Ниже приведен пример файла 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

Для использования внутри сервера приложений вы почти всегда должны настраивать Hibernate для получения соединений с помощью javax.sql.Datasource, зарегистрированного в JNDI. Вам нужно будет установить хотя бы одно из следующих свойств:

Таблица 3.2. Свойства Hibernate Datasource

Ниже приведен пример файла hibernate.properties для сервера приложений, предоставляемого источником данных JNDI:

hibernate.connection.datasource = java:/comp/env/jdbc/test
hibernate.transaction.factory_class = \
    org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
    org.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = org.hibernate.dialect.PostgreSQL82Dialect

Соединения JDBC, полученные из источника данных JNDI, будут автоматически участвовать в транзакциях, управляемых контейнером сервера приложений.

Произвольные свойства соединения могут быть заданы путем добавления «hibernate.connection» к имени свойства соединения. Например, вы можете указать свойство соединения charSet с помощью hibernate.connection.charSet.

Вы можете определить свою собственную стратегию плагина для получения соединений JDBC, реализовав интерфейс org.hibernate.connection.ConnectionProvider и указав свою пользовательскую реализацию через свойство hibernate.connection.provider_class.

3.4. Необязательные свойства конфигурации

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

Таблица 3.3. Свойства конфигурации Hibernate

Таблица 3.4. Свойства JDBC и соединений в Hibernate

Таблица 3.5. Свойства кэша в Hibernate

Таблица 3.6. Свойства транзакций в Hibernate

Таблица 3.7. Прочие свойства

3.4.1. Диалекты SQL

Всегда устанавливайте свойство hibernate.dialect в соответствующий подкласс org.hibernate.dialect.Dialect для вашей базы данных. Если вы укажете диалект Hibernate будет использовать разумные значения по умолчанию для некоторых других свойств, перечисленных выше. Это означает, что вам не нужно будет указывать их вручную.

Таблица 3.8. Hibernate SQL диалекты (hibernate.dialect)

3.4.2. Outer Join Fetching

Если ваша база данных поддерживает внешние соединения (outer joins) типа ANSI, Oracle или Sybase, outer join fetching (выборка по внешнему соединению) часто увеличивает производительность, ограничивая количество обращений в ту или иную базу данных за счет большей работы, выполняемой самой базой данных. Выборка по внешнему соединению (outer join fetching) позволяет получить целый граф объектов, соединённых ассоциациями «один-ко-многим», «многие-ко-многим» и «один-к-одному», которые будут извлекаться в одном SQL SELECT.

Выборку по внешнему соединению (outer join fetching) можно отключить глобально, установив свойство hibernate.max_fetch_depth равным 0. Параметр 1 или выше позволяет использовать выборку по внешнему соединению для ассоциаций «один к одному» и «многие-к-одному», которые были отображены с помощью fetch=«join».

Дополнительную информацию см. в разделе 20.1 «Стратегии выборки».

3.4.3. Двоичные потоки (binary streams)

Oracle ограничивает размер массивов типа byte, которые могут быть переданы в и/или из его драйвера JDBC. Если вы хотите использовать большие экземпляры типов byte или serializable, вы должны включить hibernate.jdbc.use_streams_for_binary. Это свойство системного уровня.

3.4.4. Кэш второго уровня и кэш запросов

Свойства с префиксом hibernate.cache позволяют использовать систему кэширования второго уровня с областью видимости процесса или кластера. Дополнительную информацию см. в разделе 20.2 «Кэш второго уровня».

3.4.5. Замена языка запроса

Вы можете определить новые токены запросов Hibernate, используя hibernate.query.substitutions. Например:

hibernate.query.substitutions true=1, false=0

Это приведет к тому, что токены true и false будут переведены в целочисленные (integer) литералы в сгенерированном SQL.

hibernate.query.substitutions toLowercase=LOWER

Это позволит вам переименовать SQL функцию LOWER.

3.4.6. Статистика Hibernate

Если вы включите hibernate.generate_statistics, то Hibernate предоставит ряд показателей, которые полезны при настройке запущенной системы через SessionFactory.getStatistics(). Также для отображения этих статистических данных Hibernate может быть настроен через JMX. Прочтите об интерфейсах org.hibernate.stats в Javadoc для получения дополнительной информации.

3.5. Логирование

Hibernate использует Simple Logging Facade for Java (SLF4J) для логирования различных системных событий. SLF4J может направлять вывод журнала в несколько фреймворков регистрации (NOP, Simple, log4j v1.2, JDK 1.4 logging, JCL или logback) в зависимости от выбранного вами. Чтобы настроить ведение журнала вам понадобится slf4j-api.jar в вашем classpath вместе с файлом jar для выбранного вами логгера (slf4j-log4j12.jar в случае Log4J). Более подробную информацию см. в документации SLF4J. Для использования Log4j вам также необходимо поместить файл log4j.properties в classpath. Пример файла свойств распространяется вместе с Hibernate в каталоге src/.

Рекомендуется ознакомиться с сообщениями журнала Hibernate. Было сделано много работы, чтобы сделать журнал Hibernate максимально подробным, не делая его нечитаемым. Наиболее интересными категориями журналов являются:

Таблица 3.9. Категории лога Hibernate

При разработке приложений с Hibernate вы почти всегда должны работать с включённым debug для категории org.hibernate.SQL или установить свойство hibernate.show_sql в true.

3.6. Имплементация NamingStrategy

Интерфейс org.hibernate.cfg.NamingStrategy позволяет указать «стандарт именования» для объектов базы данных и элементов схемы.

Вы можете предоставить правила для автоматического создания идентификаторов базы данных из идентификаторов Java или для обработки «логических» столбцов и имен таблиц, указанных в файле отображения, в «физические» имена таблиц и столбцов. Эта функция помогает уменьшить многословие файла отображения, устраняя повторяющийся куски (например, префиксы TBL_). Стратегия по умолчанию, используемая Hibernate, минимальна.

Вы можете указать другую стратегию, вызвав Configuration.setNamingStrategy() перед добавлением отображений:

SessionFactory sf = new Configuration()
    .setNamingStrategy(ImprovedNamingStrategy.INSTANCE)
    .addFile("Item.hbm.xml")
    .addFile("Bid.hbm.xml")
    .buildSessionFactory();

org.hibernate.cfg.ImprovedNamingStrategy — это встроенная стратегия, которая может быть полезной отправной точкой для некоторых приложений.

3.7. Имплементация PersisterClassProvider

Вы можете настроить реализацию persister, используемую для сохранения ваших сущностей и коллекций:

• по умолчанию Hibernate использует persisters, которые имеют смысл в реляционной модели и следуют спецификации Java Persistence
• вы можете определить реализацию PersisterClassProvider, которая предоставляет класс persister, используемый для данной сущности или коллекции
• наконец, вы можете переопределить их на основе сущности и коллекции в отображении с использованием @Persister или его XML эквивалента.

Каждый последующий элемент в списке выше по приоритету.

Вы можете передать экземпляр PersisterClassProvider в объект Configuration.

SessionFactory sf = new Configuration()
    .setPersisterClassProvider(customPersisterClassProvider)
    .addAnnotatedClass(Order.class)
    .buildSessionFactory();

Методы провайдера класса persister при возврате непустого класса persister переопределяют константы Hibernate по умолчанию. Имя сущности или роль коллекции передаются методам. Это хороший способ централизовать основную логику persist-приложений вместо того, чтобы распространять их на каждом отображении сущности или коллекции.

3.8. XML-файл конфигурации

Альтернативный подход к настройке — указать полную конфигурацию в файле с именем hibernate.cfg.xml. Этот файл может использоваться как замена файла hibernate.properties или, если они присутствуют, для переопределения свойств.

Файл конфигурации XML по умолчанию должен находиться в корне вашего CLASSPATH. Вот пример:

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://www.hibernate.org/dtd/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
    <!-- a SessionFactory instance listed as /jndi/name -->
    <session-factory
        name="java:hibernate/SessionFactory">
        <!-- properties -->
        <property name="connection.datasource">java:/comp/env/jdbc/MyDB</property>
        <property name="dialect">org.hibernate.dialect.MySQLDialect</property>
        <property name="show_sql">false</property>
        <property name="transaction.factory_class">
            org.hibernate.transaction.JTATransactionFactory
        </property>
        <property name="jta.UserTransaction">java:comp/UserTransaction</property>
        <!-- mapping files -->
        <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
        <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>
        <!-- cache settings -->
        <class-cache class="org.hibernate.auction.Item" usage="read-write"/>
        <class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
        <collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/>
    </session-factory>
</hibernate-configuration>

Преимуществом этого подхода является экстернализация имен файлов отображения для конфигурации. hibernate.cfg.xml также более удобен, если вам нужно настроить кэш-память Hibernate. Это ваш выбор использовать либо hibernate.properties, либо hibernate.cfg.xml. Оба они эквивалентны, за исключением вышеупомянутых преимуществ использования синтаксиса XML.

С конфигурацией XML запуск Hibernate прост:

SessionFactory sf = new Configuration().configure().buildSessionFactory();

Вы можете выбрать другой файл конфигурации XML, используя:

SessionFactory sf = new Configuration()
    .configure("catdb.cfg.xml")
    .buildSessionFactory();

3.9. Интеграция на сервер приложений Java EE

Hibernate имеет следующие точки интеграции для инфраструктуры J2EE:

• Container-managed datasources (Источники данных (datasource), управляемые контейнерами): Hibernate может использовать JDBC-соединения, управляемые контейнером, и предоставляемые через JNDI. Обычно JTA-совместимый TransactionManager и ResourceManager заботятся об управлении транзакциями (CMT), особенно распределенной обработкой транзакций из нескольких источниках данных (datasource). Вы также можете разделаить границы транзакций (BMT) или использовать дополнительный API транзакций Hibernate для того, чтобы сохранить ваш код переносимым.
• Automatic JNDI binding (Автоматическое связывание JNDI): Hibernate может связать свой SessionFactory с JNDI после запуска.
• JTA Session binding: Hibernate Session может автоматически привязываться к объёму транзакций JTA. Просто найдите SessionFactory в JNDI и получите текущую сессию (Session). Пусть Hibernate управляет очисткой (flushing) и закрытием сессии, когда ваша транзакция JTA завершается. Разделение транзакций является либо декларативной (CMT), либо программной (BMT/UserTransaction).
• JMX deployment (Развертывание JMX): если у вас есть сервер приложений, поддерживающий JMX (например, JBoss AS), вы можете выбрать для развертывания Hibernate в качестве управляемого MBean. Это экономит вам одну строку кода (создание SessionFactory) в конфигурации. Контейнер запустит ваш HibernateService, а также позаботится о зависимостях службы (источник данных (datasource) должен быть доступен до запуска Hibernate и т. д.).

В зависимости от вашей среды вам может потребоваться установить для параметра конфигурации hibernate.connection.aggressive_release значение true, если на вашем сервере приложений отображаются исключения «connection containment».

3.9.1. Конфигурация стратегии транзакций

API сессии Hibernate не зависит от любой системы разделения транзакций в вашей архитектуре. Если вы позволяете Hibernate использовать JDBC напрямую через пул соединений, вы можете начинать и заканчивать свои транзакции вызовами JDBC API. Если вы запустили сервер приложений J2EE, вы можете использовать транзакции, управляемые бинами, и при необходимости обращаться к API JTA и UserTransaction.

Чтобы переносить код между этими двумя (и другими) средами, мы рекомендуем дополнительный Hibernate Transaction API, который обертывает и скрывает базовую систему. Вы должны указать фабричный класс для экземпляров транзакций, установив свойство конфигурации Hibernate hibernate.transaction.factory_class.

Существуют три стандартных или встроенных варианта:

org.hibernate.transaction.JDBCTransactionFactory

делегирует транзакции базе данных (JDBC) (по умолчанию)

org.hibernate.transaction.JTATransactionFactory

делегирует транзакции, управляемые контейнером, если в этом контексте выполняется существующая транзакция (например, метод бина сессии (session) EJB). В противном случае запускается новая транзакция и используются транзакции, управляемые бином.

org.hibernate.transaction.CMTTransactionFactory

делегирует JTA транзакциям, управляемым контейнерами

Вы также можете определить свои собственные стратегии транзакций (например для сервиса транзакций CORBA).

Некоторые функции в Hibernate (кэш второго уровня, контекстные сессии с JTA и т. д.) требуют доступа к JTA TransactionManager в управляемой среде. На сервере приложений, поскольку J2EE не стандартизирует единый механизм, вы должны указать, как Hibernate должен получить ссылку на TransactionManager:

Таблица 3.10. JTA TransactionManagers

3.9.2. JNDI-связанный SessionFactory

Связанный с JNDI Hibernate SessionFactory может упростить функцию поиска фабрики и создать новые сессии (Session). Однако это не связано с источником данных (Datasource), связанным с JNDI; оба просто используют один и тот же реестр.

Если вы хотите связать SessionFactory с пространством имен JNDI, укажите имя (например, java:hibernate/SessionFactory), используя свойство hibernate.session_factory_name. Если это свойство опущено SessionFactory не будет привязан к JNDI. Это особенно полезно в средах с реализацией JNDI только для чтения (например, в Tomcat).

При привязке SessionFactory к JNDI, Hibernate будет использовать значения hibernate.jndi.url, hibernate.jndi.class для создания исходного контекста. Если они не указаны, будет использоваться InitialContext по умолчанию.

Hibernate автоматически поместит SessionFactory в JNDI после вызова cfg.buildSessionFactory(). Это означает, что у вас будет этот вызов в коде запуска или классе утилиты в вашем приложении, если только вы не используете JMX-развертывание с HibernateService (это более подробно обсуждается позже).

Если вы используете JNDI SessionFactory, EJB или любой другой класс, вы можете получить SessionFactory с помощью поиска JNDI.

Рекомендуется привязать SessionFactory к JNDI в управляемой среде и использовать статический singleton. Чтобы защитить ваш код приложения от этих деталей, мы также рекомендуем скрыть фактический код поиска для SessionFactory в вспомогательном классе, например HibernateUtil.getSessionFactory(). Обратите внимание, что такой класс также является удобным способом запуска Hibernate — см. главу 1.

3.9.3. Управление текущим контекстом сессии с помощью JTA

Самый простой способ обработки сессий (Sessions) и транзакций  — это автоматическое управление «текущем» сессией (Session) Hibernate. Обсуждение контекстных сессии см. в параграфе «2.2. Контекстные сессии». Используйте контекст сессии (Session) «jta», если сессия (Session) Hibernate не связана с текущей транзакцией JTA. Он будет запущен и связан с этой транзакцией JTA при первом вызове sessionFactory.getCurrentSession(). Сессии (Sessions), полученные через getCurrentSession() в контексте «jta», автоматически устанавливаются до завершения транзакции, закрываются после завершения транзакции и принудительно освобождают соединения JDBC после каждой инструкции. Это позволяет сеесиям (Sessions) управлять жизненным циклом транзакции JTA, к которой она привязана, что сохраняет код пользователя "чистым" от кода управления. Ваш код может либо использовать JTA программно через UserTransaction, либо (рекомендуется для переносимого кода) использовать Hibernate Transaction API для установки границ транзакций. Если вы запускаете контейнер EJB предпочтительной является разделение транзакций с CMT.