Hibernate ORM Javadocs

Hibernate is a library for object/relation mapping (ORM). It provides:

• anative API centered aroundSessionFactory andSession,
• an implementation of theJava (or Jakarta) Persistence API (JPA), where the equivalent central interfaces areEntityManagerFactory andEntityManager,
• a set ofmapping annotations which augment the O/R mapping annotations defined by JPA, and which may be used with either API, and
• compile-time tooling for writing more type-safe code.

Native API

Along withSessionFactory andSession, applications using the native API will often make use of the following interfaces:

• Configuration to configure and bootstrap Hibernate,
• StatelessSession for processes involving many entity instances,
• Cache to manage the second-level cache,
• Transaction to control local transactions,
• Query to execute HQL queries,
• NativeQuery to execute native SQL queries,
• Filter to manage filters,
• HibernateCriteriaBuilder to construct criteria queries, and
• SchemaManager to execute DDL in tests.

JPA

The JPA interfaces are defined by the JPA specification. For details see the latestspecification along with theAPI documentation for the packagejakarta.persistence.

Along withEntityManagerFactory andEntityManager, programs based on the standard JPA API often use:

• Persistence to bootstrap Hibernate via JPA,
• TypedQuery to execute queries,
• EntityGraph to control the boundaries of fetched data,
• EntityTransaction to control local transactions,
• Metamodel to implement generic code which makes use of persistent entity classes in a reflective fashion, and
• CriteriaBuilder to build JPA criteria queries.

Note that since Hibernate 5.2, the native API extends the JPA API rather than wrapping it. For example,SessionFactory extendsEntityManagerFactory, andSession extendsEntityManager.

It's always possible to fall back from JPA interfaces to native APIs, by callingentityManager.unwrap(Session.class),entityManagerFactory.unwrap(SessionFactory.class), orquery.unwrap(Query.class). In certain cases it's also possible to access native functionality by passing aJPA-defined orHibernate-defined hint, at the cost of a loss of type-safety.

These packages define additional extensions to the JPA APIs:

• org.hibernate.query.criteria packages extensions tojakarta.persistence.criteria, and
• org.hibernate.metamodel.model.domain packages extensions tojakarta.persistence.metamodel.

Mapping annotations

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 packageorg.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.

XML-based mappings

• The JPA-standard XML schema isorm_3_0.xsd.
• Hibernate extends this schema with some additional mapping elements. The extended schema ismapping-3.1.0.xsd.
• 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 ishibernate-mapping-3.0.dtd

Bootstrapping Hibernate

There are four basic ways to obtain an instance of Hibernate:

• as a JPApersistence provider, by usingPersistence.createEntityManagerFactory(java.lang.String),
• by using the "simplified"Configuration API,
• for those who enjoy dirty hands, by using the APIs inorg.hibernate.boot, or
• in acontainer environment likeWildFly orQuarkus, by letting the container take care of the bootstrap process and of injecting theEntityManagerFactory orSessionFactory.

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 aEntityManager orSession and its association with container-managed transactions.

Example configuration files for JPA and native usage may be foundhere. A comprehensive list of configuration properties understood by Hibernate may be found in the classAvailableSettings. Most sensible programs will only ever need to use a tiny handful of them.

Annotations driving compile-time tooling

The annotations defined byorg.hibernate.annotations.processing instruct the Metamodel Generator tovalidate HQL at compile time, and to automatically generate the implementation offinder methods andquery methods.

Popular extension points

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:

• org.hibernate.boot.model.naming allows the quantity of repetitive O/R mapping metadata to be minimized via the use of naming strategies,
• org.hibernate.type.descriptor.jdbc andorg.hibernate.type.descriptor.java contain the built-inJdbcTypes andJavaTypes for "compositional" basic attribute type mappings,
• org.hibernate.usertype defines support for user-defined custom attribute types,
• org.hibernate.generator defines support for generated attribute values,
• org.hibernate.context.spi defines support for context-bound "current" sessions and contextual multi-tenancy, and
• org.hibernate.binder allows for user-defined mapping annotations.

More advanced extension points include:

• org.hibernate.dialect provides a framework for modelling dialects of SQL,
• org.hibernate.cache.spi defines an SPI for integrating with second-level cache providers,
• org.hibernate.engine.jdbc.connections.spi defines an SPI for integrating with JDBC connection pools.

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 packagesorg.hibernate.integrator.spi andorg.hibernate.event.spi.

Package categories

The organization of code into packages is based on the following classification:

• API packages include classes and interfaces which are used directly by a typical application. These packages never havespi norinternal in their name, and are not under the namespaceorg.hibernate.testing.
• SPI packages 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 havespi in their name.
• Some classes and interfaces are considered part of the internal implementation of Hibernate. This category includes packages withinternal in their name, along with any class or interface annotated@Internal. Clients should avoid depending directly on these types.
• Thehibernate-testing module, and the namespaceorg.hibernate.testing containtesting support used in the Hibernate test suite.

More information

Complete documentation may be found online athttp://hibernate.org/orm/documentation/.