2010-10-12 16:41:27 -04:00
|
|
|
<!--
|
|
|
|
|
~ Hibernate, Relational Persistence for Idiomatic Java
|
|
|
|
|
~
|
2015-05-19 00:23:35 -04:00
|
|
|
~ 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>.
|
2010-10-12 16:41:27 -04:00
|
|
|
-->
|
|
|
|
|
<body>
|
|
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<h2>Hibernate ORM aggregated API documentation</h2>
|
2010-10-12 16:41:27 -04:00
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<p>
|
|
|
|
|
Hibernate is a library for object/relation mapping (ORM). It provides:
|
|
|
|
|
</p>
|
2022-12-29 05:39:20 -05:00
|
|
|
<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}, and
|
|
|
|
|
</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.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2010-10-12 16:41:27 -04:00
|
|
|
|
|
|
|
|
<h3>Native API</h3>
|
2022-07-04 05:33:33 -04:00
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<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>
|
2022-12-29 05:39:20 -05:00
|
|
|
<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>
|
2022-12-30 08:01:09 -05:00
|
|
|
<li>{@link org.hibernate.Transaction} to control local transactions,</li>
|
2022-12-29 05:39:20 -05:00
|
|
|
<li>{@link org.hibernate.query.Query} to execute HQL queries,</li>
|
|
|
|
|
<li>{@link org.hibernate.query.NativeQuery} to execute native SQL queries,</li>
|
2022-12-30 08:01:09 -05:00
|
|
|
<li>{@link org.hibernate.Filter} to manage filters,</li>
|
2022-12-29 05:39:20 -05:00
|
|
|
<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>
|
2010-10-12 16:41:27 -04:00
|
|
|
|
|
|
|
|
<h3>JPA</h3>
|
|
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<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/2.2/apidocs/">API documentation</a>
|
|
|
|
|
for the package {@link jakarta.persistence}.
|
|
|
|
|
</p>
|
|
|
|
|
<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>
|
2022-07-04 05:33:33 -04:00
|
|
|
|
|
|
|
|
<h3>Mapping annotations</h3>
|
|
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<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>
|
2022-11-05 07:21:51 -04:00
|
|
|
|
2022-12-29 05:39:20 -05:00
|
|
|
<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>
|
2022-12-29 11:03:18 -05:00
|
|
|
<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>
|
2022-12-30 05:29:08 -05:00
|
|
|
<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>
|
2022-12-29 05:39:20 -05:00
|
|
|
<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,
|
|
|
|
|
</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>
|
|
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<h3>Package categories</h3>
|
2018-01-03 12:23:37 -05:00
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<p>
|
|
|
|
|
The organization of code into packages is based on the following classification:
|
|
|
|
|
</p>
|
2022-12-29 05:39:20 -05:00
|
|
|
<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>
|
2022-11-05 07:21:51 -04:00
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<h3>More information</h3>
|
2010-10-12 16:41:27 -04:00
|
|
|
|
2022-12-26 16:42:42 -05:00
|
|
|
<p>
|
|
|
|
|
Complete documentation may be found online at
|
|
|
|
|
<a href="http://hibernate.org/orm/documentation">http://hibernate.org/orm/documentation/</a>.
|
|
|
|
|
</p>
|
2010-10-12 16:41:27 -04:00
|
|
|
|
|
|
|
|
</body>
|
