shared/javadoc/overview.html
Hibernate is a library for object/relation mapping (ORM). It provides:
Along with {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications using the native API will often make use of the following interfaces:
The JPA interfaces are defined by the JPA specification. For details see the latest specification along with the API documentation for the package {@link jakarta.persistence}.
Along with {@link jakarta.persistence.EntityManagerFactory} and {@link jakarta.persistence.EntityManager}, programs based on the standard JPA API often use:
Note that since Hibernate 5.2, the native API extends the JPA API rather than wrapping it. For example, SessionFactory extends EntityManagerFactory, and Session extends EntityManager.
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.
These packages define additional extensions to the JPA APIs:
The mapping annotations defined by the JPA specification provide a foundation for expressing object/relational mappings in Hibernate and other JPA implementations.
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.
The full power of Hibernate can only be unlocked via judicious use of these extra annotations.
Annotation-based mappings are the best choice for most users, but Hibernate offers XML-based mappings as an alternative.
There are four basic ways to obtain an instance of Hibernate:
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.
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.
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}.
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.
However, the following extension points are of quite general interest:
More advanced extension points include:
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}.
The organization of code into packages is based on the following classification:
spi nor internal in their name, and are not under the namespace org.hibernate.testing.spi in their name.internal in their name, along with any class or interface annotated {@link org.hibernate.Internal @Internal}. Clients should avoid depending directly on these types.hibernate-testing module, and the namespace org.hibernate.testing contain testing support used in the Hibernate test suite.Complete documentation may be found online at http://hibernate.org/orm/documentation/.