270 lines
11 KiB
HTML
270 lines
11 KiB
HTML
<!--
|
|
~ Hibernate, Relational Persistence for Idiomatic Java
|
|
~
|
|
~ License: GNU Lesser General Public License (LGPL), version 2.1 or later.
|
|
~ See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
|
|
-->
|
|
<body>
|
|
|
|
<h2>Hibernate ORM Javadocs</h2>
|
|
|
|
<p>
|
|
Hibernate is a library for object/relation mapping (ORM). It provides:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
a <em>native API</em> centered around {@link org.hibernate.SessionFactory} and
|
|
{@link org.hibernate.Session},
|
|
</li>
|
|
<li>
|
|
an implementation of the <em>Java (or Jakarta) Persistence API</em> (JPA),
|
|
where the equivalent central interfaces are {@link jakarta.persistence.EntityManagerFactory}
|
|
and {@link jakarta.persistence.EntityManager},
|
|
</li>
|
|
<li>
|
|
a set of <em>mapping annotations</em> which augment the O/R mapping annotations defined
|
|
by JPA, and which may be used with either API, and
|
|
</li>
|
|
<li>
|
|
<em>compile-time tooling</em> for writing more type-safe code.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Native API</h3>
|
|
|
|
<p>
|
|
Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications
|
|
using the native API will often make use of the following interfaces:
|
|
</p>
|
|
<ul>
|
|
<li>{@link org.hibernate.cfg.Configuration} to configure and bootstrap Hibernate,</li>
|
|
<li>{@link org.hibernate.StatelessSession} for processes involving many entity instances,</li>
|
|
<li>{@link org.hibernate.Cache} to manage the second-level cache,</li>
|
|
<li>{@link org.hibernate.Transaction} to control local transactions,</li>
|
|
<li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
|
|
<li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
|
|
<li>{@link org.hibernate.Filter} to manage filters,</li>
|
|
<li>{@link org.hibernate.query.criteria.HibernateCriteriaBuilder} to construct criteria queries,
|
|
and</li>
|
|
<li>{@link org.hibernate.relational.SchemaManager} to execute DDL in tests.</li>
|
|
</ul>
|
|
|
|
<h3>JPA</h3>
|
|
|
|
<p>
|
|
The JPA interfaces are defined by the JPA specification. For details see the latest
|
|
<a href="https://jakarta.ee/specifications/persistence/">specification</a> along with the
|
|
<a href="https://jakarta.ee/specifications/persistence/3.1/apidocs/">API documentation</a>
|
|
for the package {@link jakarta.persistence}.
|
|
</p>
|
|
<p>
|
|
Along with {@link jakarta.persistence.EntityManagerFactory} and
|
|
{@link jakarta.persistence.EntityManager}, programs based on the standard JPA API often use:
|
|
</p>
|
|
<ul>
|
|
<li>{@link jakarta.persistence.Persistence} to bootstrap Hibernate via JPA,</li>
|
|
<li>{@link jakarta.persistence.TypedQuery} to execute queries,</li>
|
|
<li>{@link jakarta.persistence.EntityGraph} to control the boundaries of fetched data,</li>
|
|
<li>{@link jakarta.persistence.EntityTransaction} to control local transactions,</li>
|
|
<li>{@link jakarta.persistence.metamodel.Metamodel} to implement generic code which makes use of
|
|
persistent entity classes in a reflective fashion, and</li>
|
|
<li>{@link jakarta.persistence.criteria.CriteriaBuilder} to build JPA criteria queries.</li>
|
|
</ul>
|
|
<p>
|
|
Note that since Hibernate 5.2, the native API extends the JPA API rather than wrapping it.
|
|
For example, <code>SessionFactory</code> extends <code>EntityManagerFactory</code>, and
|
|
<code>Session</code> extends <code>EntityManager</code>.
|
|
</p>
|
|
<p>
|
|
It's always possible to fall back from JPA interfaces to native APIs, by calling
|
|
{@link jakarta.persistence.EntityManager#unwrap entityManager.unwrap(Session.class)},
|
|
{@link jakarta.persistence.EntityManagerFactory#unwrap entityManagerFactory.unwrap(SessionFactory.class)},
|
|
or {@link jakarta.persistence.Query#unwrap query.unwrap(Query.class)}. In certain cases
|
|
it's also possible to access native functionality by passing a
|
|
{@linkplain org.hibernate.jpa.SpecHints JPA-defined} or
|
|
{@linkplain org.hibernate.jpa.HibernateHints Hibernate-defined} hint, at the cost of a
|
|
loss of type-safety.
|
|
</p>
|
|
<p>
|
|
These packages define additional extensions to the JPA APIs:
|
|
</p>
|
|
<ul>
|
|
<li>{@link org.hibernate.query.criteria} packages extensions to {@link jakarta.persistence.criteria}, and</li>
|
|
<li>{@link org.hibernate.metamodel.model.domain} packages extensions to {@link jakarta.persistence.metamodel}.</li>
|
|
</ul>
|
|
|
|
<h3>Mapping annotations</h3>
|
|
|
|
<p>
|
|
The mapping annotations defined by the JPA specification provide a foundation for expressing
|
|
object/relational mappings in Hibernate and other JPA implementations.
|
|
</p>
|
|
<p>
|
|
The annotations in the package {@link org.hibernate.annotations} extend this foundation and
|
|
accommodate more specialized requirements. These annotation are not tied to the native API,
|
|
and may be used in conjunction with the JPA API.
|
|
</p>
|
|
<p>
|
|
The full power of Hibernate can only be unlocked via judicious use of these extra annotations.
|
|
</p>
|
|
|
|
<h3>XML-based mappings</h3>
|
|
|
|
Annotation-based mappings are the best choice for most users, but Hibernate offers XML-based
|
|
mappings as an alternative.
|
|
|
|
<ul>
|
|
<li>
|
|
The JPA-standard XML schema is
|
|
<a href="https://jakarta.ee/xml/ns/persistence/orm/orm_3_0.xsd">orm_3_0.xsd</a>.
|
|
</li>
|
|
<li>
|
|
Hibernate extends this schema with some additional mapping elements. The extended schema is
|
|
<a href="https://hibernate.org/xsd/orm/mapping/mapping-3.1.0.xsd">mapping-3.1.0.xsd</a>.
|
|
</li>
|
|
<li>
|
|
Prior to the existence of JPA, Hibernate had its own format for XML-based mappings,
|
|
which still works, though it has not been improved in a long time. The DTD is
|
|
<a href="https://www.hibernate.org/dtd/hibernate-mapping-3.0.dtd">hibernate-mapping-3.0.dtd</a>
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Bootstrapping Hibernate</h3>
|
|
|
|
<p>
|
|
There are four basic ways to obtain an instance of Hibernate:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
as a JPA <em>persistence provider</em>, by using
|
|
{@link jakarta.persistence.Persistence#createEntityManagerFactory},
|
|
</li>
|
|
<li>
|
|
by using the "simplified" {@link org.hibernate.cfg.Configuration} API,
|
|
</li>
|
|
<li>
|
|
for those who enjoy dirty hands, by using the APIs in {@link org.hibernate.boot}, or
|
|
</li>
|
|
<li>
|
|
in a <em>container environment</em> like
|
|
<a href="https://www.wildfly.org">WildFly</a> or <a href="https://quarkus.io">Quarkus</a>,
|
|
by letting the container take care of the bootstrap process and of injecting the
|
|
{@code EntityManagerFactory} or {@code SessionFactory}.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
All major Java application servers and microservice frameworks come with built-in support for
|
|
Hibernate. Such container environments also typically feature facilities to automatically
|
|
manage the lifecycle of a {@code EntityManager} or {@code Session} and its association with
|
|
container-managed transactions.
|
|
</p>
|
|
<p>
|
|
Example configuration files for JPA and native usage may be found {@linkplain org.hibernate.cfg
|
|
here}. A comprehensive list of configuration properties understood by Hibernate may be found in
|
|
the class {@link org.hibernate.cfg.AvailableSettings}. Most sensible programs will only ever need
|
|
to use a tiny handful of them.
|
|
</p>
|
|
|
|
<h3>Annotations driving compile-time tooling</h3>
|
|
|
|
<p>
|
|
The annotations defined by {@link org.hibernate.annotations.processing} instruct the Metamodel
|
|
Generator to {@linkplain org.hibernate.annotations.processing.CheckHQL validate HQL at compile
|
|
time}, and to automatically generate the implementation of
|
|
{@linkplain org.hibernate.annotations.processing.Find finder methods} and
|
|
{@linkplain org.hibernate.annotations.processing.HQL query methods}.
|
|
<p>
|
|
|
|
<h3>Popular extension points</h3>
|
|
|
|
<p>
|
|
Hibernate offers an enormous wealth of extension points for customizing almost any aspect of
|
|
its implementation. Most of these extension points are far too technical to be of interest to
|
|
the typical application developer.
|
|
</p>
|
|
<p>
|
|
However, the following extension points are of quite general interest:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
{@link org.hibernate.boot.model.naming} allows the quantity of repetitive O/R mapping
|
|
metadata to be minimized via the use of naming strategies,
|
|
</li>
|
|
<li>
|
|
{@link org.hibernate.type.descriptor.jdbc} and {@link org.hibernate.type.descriptor.java}
|
|
contain the built-in {@code JdbcType}s and {@code JavaType}s for "compositional" basic
|
|
attribute type mappings,
|
|
</li>
|
|
<li>
|
|
{@link org.hibernate.usertype} defines support for user-defined custom attribute types,
|
|
</li>
|
|
<li>
|
|
{@link org.hibernate.generator} defines support for generated attribute values,
|
|
</li>
|
|
<li>
|
|
{@link org.hibernate.context.spi} defines support for context-bound "current" sessions
|
|
and contextual multi-tenancy, and
|
|
</li>
|
|
<li>
|
|
{@link org.hibernate.binder} allows for user-defined mapping annotations.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
More advanced extension points include:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
{@link org.hibernate.dialect} provides a framework for modelling dialects of SQL,
|
|
</li>
|
|
<li>
|
|
{@link org.hibernate.cache.spi} defines an SPI for integrating with second-level cache
|
|
providers,
|
|
</li>
|
|
<li>
|
|
{@link org.hibernate.engine.jdbc.connections.spi} defines an SPI for integrating with
|
|
JDBC connection pools.
|
|
</li>
|
|
</ul>
|
|
<p>
|
|
Finally, Hibernate ORM Core is itself a framework for advanced extensions like Hibernate Search,
|
|
Hibernate Reactive, and Envers, which do much more than just implementing a single well-defined
|
|
extension point. The starting points for such extensions are found in the packages
|
|
{@link org.hibernate.integrator.spi} and {@link org.hibernate.event.spi}.
|
|
</p>
|
|
|
|
<h3>Package categories</h3>
|
|
|
|
<p>
|
|
The organization of code into packages is based on the following classification:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
<strong>API packages</strong> include classes and interfaces which are used directly by
|
|
a typical application. These packages never have <code>spi</code> nor <code>internal</code>
|
|
in their name, and are not under the namespace <code>org.hibernate.testing</code>.
|
|
</li>
|
|
<li>
|
|
<strong>SPI packages</strong> include classes and interfaces which are used by integrators,
|
|
library developers, and framework developers to develop extensions to Hibernate, or to alter
|
|
its behavior in some way. These packages usually have <code>spi</code> in their name.
|
|
</li>
|
|
<li>
|
|
Some classes and interfaces are considered part of the internal implementation of Hibernate.
|
|
This category includes packages with <code>internal</code> in their name, along with any class
|
|
or interface annotated {@link org.hibernate.Internal @Internal}. Clients should avoid depending
|
|
directly on these types.
|
|
</li>
|
|
<li>
|
|
The <code>hibernate-testing</code> module, and the namespace <code>org.hibernate.testing</code>
|
|
contain <strong>testing support</strong> used in the Hibernate test suite.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>More information</h3>
|
|
|
|
<p>
|
|
Complete documentation may be found online at
|
|
<a href="http://hibernate.org/orm/documentation">http://hibernate.org/orm/documentation/</a>.
|
|
</p>
|
|
|
|
</body> |