Hibernate Javadoc (7.0.0.Alpha3)

Hibernate ORM Javadocs

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

  • a native API centered around SessionFactory and Session,
  • an implementation of the Java (or Jakarta) Persistence API (JPA), where the equivalent central interfaces are EntityManagerFactory and EntityManager,
  • a set of mapping 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 with SessionFactory and Session, applications using the native API will often make use of the following interfaces:

JPA

The JPA interfaces are defined by the JPA specification. For details see the latest specification along with the API documentation for the package jakarta.persistence.

Along with EntityManagerFactory and 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 entityManager.unwrap(Session.class), entityManagerFactory.unwrap(SessionFactory.class), or query.unwrap(Query.class). In certain cases it's also possible to access native functionality by passing a JPA-defined or Hibernate-defined hint, at the cost of a loss of type-safety.

These packages define additional extensions to the JPA APIs:

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

XML-based mappings

Annotation-based mappings are the best choice for most users, but Hibernate offers XML-based mappings as an alternative.
  • The JPA-standard XML schema is orm_3_0.xsd.
  • Hibernate extends this schema with some additional mapping elements. The extended schema is mapping-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 is hibernate-mapping-3.0.dtd

Bootstrapping Hibernate

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 EntityManager or Session and its association with container-managed transactions.

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

Annotations driving compile-time tooling

The annotations defined by org.hibernate.annotations.processing instruct the Metamodel Generator to validate HQL at compile time, and to automatically generate the implementation of finder methods and query 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:

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 org.hibernate.integrator.spi and org.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 have spi nor internal in their name, and are not under the namespace org.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 have spi in their name.
  • Some classes and interfaces are considered part of the internal implementation of Hibernate. This category includes packages with internal in their name, along with any class or interface annotated @Internal. Clients should avoid depending directly on these types.
  • The hibernate-testing module, and the namespace org.hibernate.testing contain testing support used in the Hibernate test suite.

More information

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

Packages
Package
Description
This package defines the central Hibernate APIs, beginning with SessionFactory, which represents an instance of Hibernate at runtime and is the source of new instances of Session and StatelessSession, the most important APIs exposing persistence-related operations for entities.
The various concrete action implementations.
This SPI package defines an abstraction over the notion of an "action" which is scheduled for asynchronous execution by the event listeners.
Implementation of ConnectionProvider using Agroal.
A set of mapping annotations which extend the O/R mapping annotations defined by JPA.
Annotations used to drive annotation processors: @Find is used to generate finder methods using the Metamodel Generator, @HQL and @SQL are used to generate query methods using the Metamodel Generator, and CheckHQL instructs the Query Validator to check all HQL queries in the annotated package or type.
This package defines an easy way to extend Hibernate with user-defined annotations that define customized O/R mappings of annotated entities and annotated entity attributes.
Built-in implementations of AttributeBinder and TypeBinder.
This package contains the interfaces that make up the bootstrap API for Hibernate.
The internals of archive scanning support.
 
SPI for scanning archives to discover managed classes and named resources.
Defines a model for archives which may be scanned to discover managed classes and named resources.
Support for integrating Jakarta Bean Validation.
Implementation of the service for processing and handling cfg.xml files.
An SPI service for processing and handling cfg.xml files.
 
JAXB support for orm.xml and hbm.xml mapping files
 
 
 
JAXB details.
 
 
 
Contains basic support for Java XML Processing (JAXP) via Streaming API for XML (StAX)
 
 
 
 
This package defines the boot-time metamodel, which is an interpretation of the domain model (entity classes, embeddable classes, and attributes) and the mapping of these "domain model parts" to the database.
 
Defines the SPI of a registry of JPA AttributeConverters.
 
This API allows intervention by generic code in the process of determining the names of database objects (tables, columns, and constraints).
 
Defines an SPI used during the process of transforming mapping sources into the Metadata reference.
Some SPIs related to DDL generation and schema management.
 
 
 
 
 
Overall, this module is responsible for taking managed-resources and building the hibernate-models model (ClassDetails, etc.) to ultimately be bound into Hibernate's boot-time model.
 
 
Support for processing an application's domain model, as known through ManagedResources and ultimately producing a mildly categorized model representing entities, embeddables, etc.
 
 
 
 
Support for processing mapping XML files, ultimately creating/updating ClassDetails, FieldDetails and annotation references based on the XML. First performs some pre-processing which aggregates information across all XML mappings Next performs XML processing which applies metadata-complete mappings and collects overlay/override XML for later application.
Support for processing mapping XML files and applying annotation references over the appropriate classes, fields and methods.
 
 
 
Support for handling named queries during the bootstrap process.
Defines service registry contracts a program may use for configuring Hibernate.
The class loading service internals.
The class loading service SPI.
The internals for building service registries.
Defines a feature set around named registration of implementations of various contracts and the ability to select those implementations.
Internals for building StrategySelector
Defines actual contract used for strategy selection.
A range of SPIs allowing integration with—and customization of—the process of building metadata.
Support for XSD handling.
This package defines an SPI for integrating bytecode libraries with Hibernate.
 
package containing bytecode enhancement code (internals)
specialized classes to keep track of changes
Package defining bytecode code enhancement (instrumentation) support.
Support for bytecode interceptor implementations.
 
Byte Buddy support internals
 
Package defining bytecode code enhancement (instrumentation) support.
Implementation of ConnectionProvider using the c3p0 Connection pool.
This package defines the API of the second-level cache service.
Implementation of the second-level cache configuration SPI.
An SPI modelling various aspects of the second-level cache configuration.
Internal implementations and support for second-level caching.
Hibernate caching provider for JSR-107 compliant caches.
 
Defines the integration aspect of Hibernate's second-level caching, allowing a "caching backend" to be plugged in as a cache provider.
Defines contracts for transactional and concurrent access to cached entity and collection data.
This package defines formats for disassembled state kept in the second level cache.
This package provides a framework intended to reduce the work needed to implement a caching provider.
This package defines APIs for configuring Hibernate.
This package historically provided backward-compatibility with Hibernate 2.1 APIs which were deprecated in Hibernate 3.
Internal implementations and support for persistent collections.
This package defines the SPI of a framework for lazy-initializing and state-tracking collection wrappers.
Contains SPIs which define: the notion of a context-bound or "current" session, and the notion of a "current" tenant id.
Internal implementations and support around "current session" handling.
SPI-level contracts around "current session" and "current tenant" support.
This package abstracts over the multifarious dialects of SQL understood by the databases supported by Hibernate.
Support for Dialect-specific aggregate column types, including user-defined composite types, and JSON or XML types.
Contains implementations of SqmFunctionDescriptor describing a range of relatively-sophisticated SQL functions available in various dialects.
 
Support for query hints using Dialect-specific syntax.
Support for Dialect-specific identity column handling.
Support for Dialect-specific locking strategies.
Support for Dialect-specific pagination strategies.
Support for Dialect-specific sequence handling.
Support for temporary tables.
Support for Dialect-specific unique constraint definition.
This package contains classes which are "shared" by other subsystems, and implementations of some key algorithms.
The built-in implementation of the configuration service.
Defines the SPI of the configuration service.
Support for many of the internal workings of Hibernate.
Support for various aspects of JDBC interaction.
Support for JDBC statement batching.
Internals for JDBC batching support.
Defines contracts for JDBC batching support.
Various implementations of the SPI contracts for obtaining JDBC Connections.
Defines SPI contracts for obtaining JDBC Connections from a provider implemented as a service.
Internals for JDBC REF_CURSOR support.
Defines contracts for JDBC REF_CURSOR support.
Internal support for Dialect resolution (from JDBC metadata) and Dialect building.
Contracts supporting Dialect resolution (from JDBC metadata) and Dialect building.
 
 
Internals for supporting various aspects of JDBC interaction
Package defining support for executing mutation SQL statements produced by an entity persister or collection persister.
 
 
 
SPI contracts supporting various aspects of JDBC interaction.
Support for JNDI within Hibernate
Internal contracts defining the JNDI support within Hibernate
The SPI contracts for integration with JNDI.
Models the fetch profiles defined by the application.
 
Support for dealing with parameters of native queries.
 
An SPI for dealing with parameters of native queries.
This package defines some central internal SPI abstractions used throughout the implementation of Hibernate.
 
 
A range of container-specific implementations of JtaPlatform.
An SPI for integrating with container-provided implementations of JTA.
An SPI abstracting the object which implements Transaction.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
This package defines a default set of event listeners that implement the default behaviors of Hibernate session operations.
Implementation of the event listener registration service.
An SPI for the event listener registration service.
Defines the event types and event listener interfaces for events produced by the stateful Session.
Defines certain very important flavors of JDBCException, along with an SPI for interpreting product-specific SQLExceptions arising from a JDBC driver into something more uniform and meaningful.
 
An SPI for Dialect-specific exception interpretation and conversion.
This package defines an abstraction over all kinds of automatic value generation, including id generation and version number generation.
 
Contains a framework of strategies for efficient retrieval of database-generated values.
 
 
 
 
 
Implements and extends the JPA-defined entity graph API.
 
 
This package defines an internal SPI abstracting over implementations of the APIs defined in org.hibernate.graph.
Implementation of ConnectionProvider using HikariCP.
This package and its subpackages, especially org.hibernate.id.enhanced, contain the built-in id generators, all of which implement either IdentifierGenerator or PostInsertIdentifierGenerator.
Enhanced/improved versions of table and sequence based identifier generators targeting portability and unified configuration.
Contains a framework of strategies for retrieving database-generated ids.
Contains the UuidGenerator.
Implementation of the SPI for extensions which integrate with Hibernate via the Service mechanism.
An SPI for extensions which integrate with Hibernate via the Java ServiceLoader facility.
An internal package containing implementations of central Hibernate APIs, mostly defined in org.hibernate.
 
 
Internal utility classes
 
 
 
 
 
 
A small API allowing the client of a Hibernate session to interact directly with JDBC, using the same connection and transaction obtained by the session.
The packages in this namespace are responsible for implementing certain requirements of the JPA specification, especially things which are only needed when Hibernate is acting as a JPA persistence provider.
 
An SPI used to initiate and control the JPA bootstrap process, along with SPI interfaces allowing certain sorts of extensions to be contributed during the bootstrap process.
Internal details of implementing support for JPA callbacks
The SPI contracts for supporting JPA lifecycle callbacks.
Defines Hibernate implementation of Java Persistence specification.
 
 
An SPI for managing cases where, by default, Hibernate intentionally violates the letter of the JPA specification.
 
This package defines functionality for processing JDBC result sets and returning complex graphs of persistent objects.
 
 
 
This package defines the Hibernate configuration-time mapping model.
This package defines an API for accessing the runtime metamodel describing persistent entities in Java and their mappings to the relational database schema.
 
Defines the runtime mapping metamodel, which describes the mapping of the application's domain model parts (entities, attributes) to relational database objects (tables, columns).
 
Support for set and map ordering
 
Defines the runtime domain metamodel, which describes the Java aspect of the application's domain model parts (entities, attributes).
Implementation of the SPI for the runtime domain metamodel.
An SPI for the runtime domain metamodel.
An SPI supporting custom instantiation of entity instances and embeddable objects.
This package abstracts persistence mechanisms for collections.
Defines support for performing mutation operations against collections.
This package abstracts persistence mechanisms for entities.
Defines support for performing mutation operations originating from persistence-context events.
Built-in implementation of the SPI for integrating entity and collection persisters.
An SPI for integrating custom entity and collection persisters.
Package for "walking" associations through metadata definition.
Contains some functions for pretty-printing things for exception and log messages.
Defines support for executing database stored procedures and functions and accessing their outputs.
Defines the internal implementation of the stored procedure SPI.
Defines an SPI for calling stored procedures and functions.
The main package of this annotation processor.
Implementation of the model classes backed by annotations.
 
Helper classes for string and type processing as well as access type detection.
XML helper classes.
Validation for HQL queries.
Implementation of the model classes backed by annotations.
Contains various implementations of PropertyAccessStrategy.
An SPI abstracting how persistent attributes of an entity or embeddable type are accessed by Hibernate.
Implementation of ConnectionProvider using the proxool Connection pool.
This package defines a framework for lazy-initializing entity proxies.
Proxies for entity objects represented as Java maps.
Proxies for plain Java objects.
 
Everything related to HQL/JPQL, native SQL, and criteria queries.
The JPA-standard criteria query API defines all the operations needed express any query written in standard JPQL.
 
SPI for extending HibernateCriteriaBuilder with additional functionality by registering a Service.
 
Package defining support for HQL, including JPQL as a subset of HQL.
Implementation of the SPIs for HQL support.
SPIs for HQL support.
 
Support for named queries
Support SQL functions in the SQM model.
Support for defining result set mappings used in NativeQuery, ProcedureCall, and StoredProcedureQuery.
Support for immutable result/fetch builder graph nodes built from static sources such as SqlResultSetMapping or the hbm.xml mapping element <resultset/>.
Support for mutable result/fetch builder graphs nodes built dynamically via Hibernate's NativeQuery APIs
Defines support for implicit ResultSet mappings.
Contains a range of internal abstractions for dealing with query execution, query plans, query options, and query parameters.
Package defining support for native SQL queries.
Implementation of the SPIs for native SQL query support.
SPIs for native SQL query support.
This package defines a semantic model of HQL queries.
An SPI for defining, registering, and rendering functions in HQL.
Package for the SQM-backed Query implementation details
 
 
 
Support for multi-table SQM mutation (insert, update, delete) operations using a table to temporarily hold the matching ids.
SPI for handling SQM UPDATE and DELETE queries
Package defining support for SqmFunctionDescriptor handling.
 
SPI-level SQM contracts
Package for the translation of SQM into SQL AST
 
This package contains the classes that make up the SQM tree nodes.
Nodes representing common table expressions (CTE) in the SQM tree.
Nodes representing delete statements in the SQM tree.
Nodes representing path expressions in the SQM tree.
Nodes representing expressions in the SQM tree.
Nodes representing root entities and joins in the SQM tree.
Nodes representing insert statements in the SQM tree.
 
Nodes representing logical predicates in the SQM tree.
Nodes representing select statements in the SQM tree.
Nodes representing update statements in the SQM tree.
Programmatic access to the schema management tool.
 
An implementation of the bean container SPI based on CDI.
An SPI abstracting over CDI-like bean containers.
 
Defines an SPI for integration with CDI-like containers.
A facility for managing logical JDBC connections and keeping track of other heavyweight resources.
Implementation of the SPI for managing JDBC connections and other heavyweight resources.
An SPI for managing JDBC connections and other heavyweight resources, based around the idea of a "JDBC session".
Defines the resource-level transaction capabilities of Hibernate, centered around the TransactionCoordinator contract.
An implementation of TransactionCoordinator based on JdbcResourceTransaction.
An SPI which models the concept of a JDBC resource-level transaction.
Implementations of TransactionCoordinator based on JTA.
Internal implementation details for reacting to JTA transaction completion via Synchronization callbacks
Internal implementation details for the resource-level transaction capabilities of Hibernate.
Extended SPI contracts for the resource-level transaction capabilities of Hibernate.
Defines support for dealing with results returned from database via JDBC.
 
 
Defines a framework for pluggable services, allowing for customization of key components of Hibernate, and abstraction of these components as SPI interfaces.
Implementation of the SPI for integrating pluggable services.
Defines an SPI for integrating pluggable services.
 
 
 
 
SpatialDialects for CockroachDB
 
 
 
 
 
 
 
 
 
 
 
A tiny SPI for dealing with compound names and navigable paths.
This package contains helper classes for rendering SQL fragments and SQL statements.
Package defining a SQL AST for use in generation of SQL.
 
Package defining support for creating and consuming a SQL AST.
Package defining the SQL AST.
Support for common table expressions (CTE) in a SQL tree.
AST nodes representing delete statements in a SQL tree.
AST nodes representing expressions in a SQL tree.
AST nodes representing root tables and joins in a SQL tree.
AST nodes representing insert statements in a SQL tree.
AST nodes representing logical predicates in a SQL tree.
AST nodes representing select statements in a SQL tree.
AST nodes representing update statements in a SQL tree.
Support for execution of SQL statements via JDBC.
Implementation of the SPI for execution of SQL statements via JDBC.
SPI for execution of SQL statements via JDBC.
Package contains specialized SQL AST nodes and builders for table mutations of model parts originating from normal persistence-context events.
SQL AST extensions for model mutations.
Support for building TableMutation references for persisting entity mutation events
Concrete implementations of MutationGroup, MutationOperation, and TableMutation.
Extensions to JdbcOperation for model mutations.
Package for processing JDBC ResultSets into hydrated domain model graphs based on a "load plan" defined by a "domain result graph", that is, one or more DomainResult nodes with zero or more Fetch nodes.
Support for caching of query results.
 
Defines domain result graphs.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
This package exposes statistics about a running instance of SessionFactory and its interaction with the database and second-level cache.
The built-in implementation of the statistics collection service.
An SPI allowing customized statistics collection.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Standard model for Hibernate's legacy Animal model used in HQL testing
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Contains tooling related to DDL generation, export, migration, and validation.
Implementation of the SPI for schema information extraction from the database via JDBC.
Defines an SPI for schema information extraction from the database via JDBC.
An implementation of the SPI for the tooling related to DDL generation, export, migration, and validation.
Support for exporting generated DDL to the database or to SQL scripts.
Support for reading SQL scripts supplied to the schema tooling.
An SPI for tooling related to DDL generation, export, migration, and validation.
Defines strategies for post-processing criteria query results into a form convenient to the application.
Most contracts here have been replaced by the new runtime mapping model.
 
 
A Hibernate Type is a strategy for mapping a Java property type to a JDBC type or types.
Contracts for reading and writing values to and from JDBC.
Implements the SPI for basic-typed value conversions.
An SPI for basic-typed value conversions, including support for handling JPA AttributeConverter instances as part of the Hibernate Type system.
Integrates a range of types defined by the JDK with the type system of Hibernate.
 
Defines handling of almost the full range of standard JDBC-defined SQL data types.
 
 
An API for working with abstract families of DDL types parameterized by varying length, precision, and scale.
Includes several general-purpose implementations of DdlType.
Defines a registry for DdlTypes.
Support for type mappings which format composite values to a structured text format (JSON or XML) for storage in a database-specific column type supporting that structured format.
Implementations of FormatMapper using Jackson.
An implementation of FormatMapper using Jakarta JSON.
An implementation of FormatMapper using JAXB.
 
Defines a registry for Hibernate Types.
An API for user-defined custom types which extend the set of built-in types defined in org.hibernate.type.
 
Implementation of ConnectionProvider using ViburDBCP.