Hibernate Models

Hibernate Models provides a unified model of an application’s classes, members, type signatures, and annotations, including models that do not correspond to loaded Java classes. The model may be backed by Java reflection, a Jandex index, Byte Buddy TypePool, generated metadata, or a combination of sources. Consumers use the same API regardless of the source, and indexed or generated models do not require every represented class to be loaded.

Note	Hibernate Models replaces the Hibernate Commons Annotations library which was historically used across Hibernate projects.

Getting started

Hibernate Models requires Java 17 or later. Add the base artifact to use the standard JDK-backed model:

<dependency>
    <groupId>org.hibernate.models</groupId>
    <artifactId>hibernate-models</artifactId>
    <version>{hibernate-models-version}</version>
</dependency>

or with Gradle:

implementation "org.hibernate.models:hibernate-models:{hibernate-models-version}"

Replace {hibernate-models-version} with the desired released version.

The following example bootstraps the standard model and resolves details for a class:

ModelsContext modelsContext = new ModelsConfiguration().bootstrap();
ClassDetails classDetails = modelsContext.getClassDetailsRegistry()
        .resolveClassDetails(MyEntity.class.getName());

classDetails.getFields().forEach(field -> {
    String name = field.getName();
    TypeDetails type = field.getType();
    // inspect the field and its annotations
});

The principal API entry points are:

ModelsConfiguration

Bootstraps a ModelsContext, discovering an alternate backend through ServiceLoader when present.

ModelsContext

Provides access to the class, annotation, and module registries.

ClassDetailsRegistry

Resolves and tracks ClassDetails by name.

AnnotationDescriptorRegistry

Resolves and tracks annotation definitions.

Creator

Creates supported annotation, JDK-backed, and dynamic model objects.

TypeDetails

Models Java types and provides factories for common type forms.

TypeDetailsHelper

Implements cross-object type algorithms, including collection element and map key/value resolution.

ModelsContextProvider

ServiceLoader contract for discovering additional ModelsContext implementations.

Model

The model mirrors familiar Java reflection concepts while also representing dynamic types which have no corresponding loaded Class<?>:

ClassDetails

Analogous to java.lang.Class.

TypeDetails

Analogous to java.lang.reflect.Type.

MemberDetails

Common contract analogous to java.lang.reflect.Member.

FieldDetails

Analogous to java.lang.reflect.Field.

MethodDetails

Analogous to java.lang.reflect.Method.

RecordComponentDetails

Analogous to java.lang.reflect.RecordComponent.

A ModelsContext ties the principal parts of the model together:

ModelsContext
|-- ClassDetailsRegistry
|   `-- ClassDetails
|       `-- MemberDetails
`-- AnnotationDescriptorRegistry
    `-- AnnotationDescriptor
        `-- AnnotationUsage

Annotations

The main annotation abstractions are:

AnnotationDescriptor

Extended information about an annotation type.

AnnotationTarget

A model object, such as a class or method, on which an annotation may be used.

AnnotationUsage

A particular use of an annotation on a target.

AttributeDescriptor

Details about an annotation attribute, including its ValueTypeDescriptor.

ValueTypeDescriptor

Describes and converts an allowable annotation attribute type, including primitive values, enums, classes, annotations, and arrays.

AnnotationDescriptorRegistry

Registry of AnnotationDescriptor references.

Artifacts and Java modules

hibernate-models (org.hibernate.models)

The API and standard Java reflection-backed implementation.

hibernate-models-jandex (org.hibernate.models.jandex)

Optional Jandex-backed implementation using a Jandex Index.

hibernate-models-bytebuddy (org.hibernate.models.bytebuddy)

Optional Byte Buddy-backed implementation using a Byte Buddy TypePool.

hibernate-models-testing

Shared test support for Hibernate Models and its consumers; it is not intended as a production dependency.

Tip

When an Index or TypePool is already available, reading its metadata is generally faster than discovering the same information through reflection. These backends can also model types without loading the represented classes or materializing reflection objects, which is especially useful when their bytecode must remain available for enhancement.

The Jandex and Byte Buddy modules both require org.hibernate.models transitively. Placing either implementation on the module path or class path allows ModelsConfiguration to discover its ModelsContextProvider as a Java service.

Building Hibernate Models

Build the project and run its tests with:

./gradlew test

Hibernate Models is licensed under the Apache License 2.0. Report bugs and request enhancements through the issue tracker.