Hibernate Javadoc (7.0.0.Alpha2)
Hibernate ORM Javadocs
Hibernate is a library for object/relation mapping (ORM). It provides:
-
a native API centered around
SessionFactoryandSession, -
an implementation of the Java (or Jakarta) Persistence API (JPA),
where the equivalent central interfaces are
EntityManagerFactoryandEntityManager, - 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:
Configurationto configure and bootstrap Hibernate,StatelessSessionfor processes involving many entity instances,Cacheto manage the second-level cache,Transactionto control local transactions,Queryto execute HQL queries,NativeQueryto execute native SQL queries,Filterto manage filters,HibernateCriteriaBuilderto construct criteria queries, andSchemaManagerto execute DDL in tests.
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:
Persistenceto bootstrap Hibernate via JPA,TypedQueryto execute queries,EntityGraphto control the boundaries of fetched data,EntityTransactionto control local transactions,Metamodelto implement generic code which makes use of persistent entity classes in a reflective fashion, andCriteriaBuilderto build JPA criteria queries.
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:
org.hibernate.query.criteriapackages extensions tojakarta.persistence.criteria, andorg.hibernate.metamodel.model.domainpackages 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 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:
-
as a JPA persistence provider, by using
Persistence.createEntityManagerFactory(java.lang.String), -
by using the "simplified"
ConfigurationAPI, -
for those who enjoy dirty hands, by using the APIs in
org.hibernate.boot, or -
in a container environment like
WildFly or Quarkus,
by letting the container take care of the bootstrap process and of injecting the
EntityManagerFactoryorSessionFactory.
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:
-
org.hibernate.boot.model.namingallows the quantity of repetitive O/R mapping metadata to be minimized via the use of naming strategies, -
org.hibernate.type.descriptor.jdbcandorg.hibernate.type.descriptor.javacontain the built-inJdbcTypes andJavaTypes for "compositional" basic attribute type mappings, -
org.hibernate.usertypedefines support for user-defined custom attribute types, -
org.hibernate.generatordefines support for generated attribute values, -
org.hibernate.context.spidefines support for context-bound "current" sessions and contextual multi-tenancy, and -
org.hibernate.binderallows for user-defined mapping annotations.
More advanced extension points include:
-
org.hibernate.dialectprovides a framework for modelling dialects of SQL, -
org.hibernate.cache.spidefines an SPI for integrating with second-level cache providers, -
org.hibernate.engine.jdbc.connections.spidefines 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 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
spinorinternalin 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 have
spiin their name. -
Some classes and interfaces are considered part of the internal implementation of Hibernate.
This category includes packages with
internalin their name, along with any class or interface annotated@Internal. Clients should avoid depending directly on these types. -
The
hibernate-testingmodule, and the namespaceorg.hibernate.testingcontain 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.
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 filesJAXB 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 a
managed-resources and
table them 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
annotation references
on the model's targets
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 implied
AnnotationUsage
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.
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.
Defines a service for creating
id generators.
Implementation of the SPI for id generator factories.
Contains an SPI for id generator factories.
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.
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 details about model mapping.
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 APIsDefines 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
callbacksInternal 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 CockroachDBA 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 eventsExtensions 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.