or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdentity-mapping.mdindex.mdqueries.mdsession-management.mdtransactions.mdtype-system.md
tile.json

tessl/maven-org-hibernate-orm--hibernate-core

Hibernate ORM core functionality - a powerful object/relational mapping solution for Java that implements JPA (Jakarta Persistence API)

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.hibernate.orm/hibernate-core@7.1.x

To install, run

npx @tessl/cli install tessl/maven-org-hibernate-orm--hibernate-core@7.1.0

index.mddocs/

Hibernate Core

Hibernate Core is the fundamental module of the Hibernate Object/Relational Mapping framework, providing comprehensive persistence capabilities for Java applications. It implements the full Jakarta Persistence API (JPA) specification while offering extensive additional features beyond the standard, including advanced entity mapping, session management, query processing, transaction management, caching, and performance optimization features.

Package Information

  • Package Name: hibernate-core
  • Package Type: maven
  • Group ID: org.hibernate.orm
  • Language: Java
  • Installation: Add to your Maven dependencies:
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.1.1</version>
</dependency>

For Gradle:

implementation 'org.hibernate.orm:hibernate-core:7.1.1'

Core Imports

// Core session management
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.Transaction;

// Configuration and bootstrapping
import org.hibernate.boot.MetadataSources;
import org.hibernate.boot.Metadata;
import org.hibernate.boot.SessionFactoryBuilder;

// Query APIs
import org.hibernate.query.Query;
import org.hibernate.query.SelectionQuery;
import org.hibernate.query.NativeQuery;

// Core annotations
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.NaturalId;
import org.hibernate.annotations.Fetch;

Basic Usage

import org.hibernate.*;
import org.hibernate.boot.MetadataSources;
import org.hibernate.boot.registry.StandardServiceRegistry;
import org.hibernate.boot.registry.StandardServiceRegistryBuilder;

// Configure and build SessionFactory
StandardServiceRegistry registry = new StandardServiceRegistryBuilder()
    .configure() // configures settings from hibernate.cfg.xml
    .build();

SessionFactory sessionFactory = new MetadataSources(registry)
    .buildMetadata()
    .buildSessionFactory();

// Use Session for persistence operations
try (Session session = sessionFactory.openSession()) {
    Transaction tx = session.beginTransaction();

    // Create and persist an entity
    MyEntity entity = new MyEntity("example");
    session.persist(entity);

    // Query entities
    List<MyEntity> entities = session.createQuery(
        "FROM MyEntity WHERE name = :name", MyEntity.class)
        .setParameter("name", "example")
        .getResultList();

    tx.commit();
}

Architecture

Hibernate Core is built around several key architectural components:

  • Session Management: Session and SessionFactory interfaces for managing persistence contexts and entity lifecycle
  • Configuration System: Bootstrap APIs for configuring mappings, connections, and runtime behavior
  • Query Engine: Multiple query APIs including HQL, Criteria API, and native SQL with full type safety
  • Type System: Comprehensive type mapping between Java objects and database columns
  • Caching: Multi-level caching system including first-level (session) and second-level caching
  • Transaction Management: Integration with JTA and resource-local transaction management
  • Event System: Extensible event/listener architecture for customizing persistence behavior

Capabilities

Session Management

Core session and persistence context management for entity lifecycle operations, including CRUD operations, lazy loading, and transaction coordination.

public interface Session extends SharedSessionContract, EntityManager {
    // Core persistence operations
    <T> T find(Class<T> entityClass, Object primaryKey);
    void persist(Object entity);
    <T> T merge(T entity);
    void remove(Object entity);
    void refresh(Object entity);

    // Transaction management
    Transaction beginTransaction();
    Transaction getTransaction();

    // Query creation
    <R> Query<R> createQuery(String queryString, Class<R> resultClass);
    <R> NativeQuery<R> createNativeQuery(String sqlString, Class<R> resultClass);
}

public interface SessionFactory extends EntityManagerFactory {
    Session openSession();
    Session getCurrentSession();
    <R> R inSession(Function<Session, R> work);
    <R> R inTransaction(Function<Session, R> work);
}

Session Management

Configuration and Bootstrap

Configuration and bootstrap APIs for setting up Hibernate, including metadata sources, service registries, and SessionFactory creation.

public class MetadataSources {
    public MetadataSources(ServiceRegistry serviceRegistry);
    public MetadataSources addAnnotatedClass(Class<?> annotatedClass);
    public MetadataSources addResource(String name);
    public Metadata buildMetadata();
}

public interface Metadata {
    SessionFactoryBuilder getSessionFactoryBuilder();
    Database getDatabase();
    Collection<EntityBinding> getEntityBindings();
}

Configuration and Bootstrap

Query APIs

Comprehensive querying capabilities including HQL, JPQL, type-safe Criteria API, and native SQL queries with parameter binding and result mapping.

public interface Query<R> extends CommonQueryContract {
    List<R> getResultList();
    R getSingleResult();
    R getSingleResultOrNull();

    // Parameter binding
    <P> Query<R> setParameter(String name, P value);
    <P> Query<R> setParameter(int position, P value);

    // Pagination
    Query<R> setFirstResult(int startPosition);
    Query<R> setMaxResults(int maxResult);
}

public interface SelectionQuery<R> extends Query<R> {
    // Selection-specific operations
    SelectionQuery<R> setOrder(List<Order> orderList);
    SelectionQuery<R> setOrder(Order... orders);
}

// Type-safe Criteria API
public interface CriteriaBuilder {
    <T> CriteriaQuery<T> createQuery(Class<T> resultClass);
    Predicate and(Predicate... restrictions);
    Predicate equal(Expression<?> x, Object y);
    <Y extends Comparable<? super Y>> Predicate greaterThan(Expression<? extends Y> x, Y y);
}

Query APIs

Entity Mapping Annotations

Hibernate-specific annotations for advanced entity mapping, caching, fetching strategies, and custom behaviors beyond JPA standard annotations.

// Caching annotations
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface Cache {
    CacheConcurrencyStrategy usage() default CacheConcurrencyStrategy.READ_WRITE;
    String region() default "";
}

// Fetching strategy annotations
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Fetch {
    FetchMode value();
}

// Natural identifier annotation
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface NaturalId {
    boolean mutable() default false;
}

Entity Mapping

Transaction Management

Transaction management APIs for coordinating database transactions, including JTA and resource-local transaction support.

public interface Transaction {
    void begin();
    void commit();
    void rollback();
    boolean isActive();

    // Timeout configuration
    void setTimeout(int seconds);
    int getTimeout();
}

Transaction Management

Type System

Hibernate's type system for mapping Java types to database types, including custom type definitions and user-defined types.

public interface UserType<J> {
    int getSqlType();
    Class<J> returnedClass();
    boolean equals(J x, J y);
    int hashCode(J x);
    J nullSafeGet(ResultSet rs, int position, SharedSessionContractImplementor session, Object owner);
    void nullSafeSet(PreparedStatement st, J value, int index, SharedSessionContractImplementor session);
}

Type System

Core Types

// Core enums
public enum FlushMode {
    /** Never flush unless explicitly requested */
    MANUAL,
    /** Flush when transaction commits */
    COMMIT,
    /** Automatically flush when needed */
    AUTO,
    /** Always flush before query execution */
    ALWAYS
}

public enum CacheMode {
    /** Normal cache interaction */
    NORMAL,
    /** Ignore second-level cache completely */
    IGNORE,
    /** Only read from cache, never write */
    GET,
    /** Only write to cache, never read */
    PUT,
    /** Refresh cache entries */
    REFRESH
}

public enum LockMode {
    /** No locking */
    NONE,
    /** Read lock */
    READ,
    /** Optimistic locking */
    OPTIMISTIC,
    /** Pessimistic read lock */
    PESSIMISTIC_READ,
    /** Pessimistic write lock */
    PESSIMISTIC_WRITE
}

// Core interfaces
public interface SharedSessionContract extends AutoCloseable {
    Transaction beginTransaction();
    Query createQuery(String queryString);
    Criteria createCriteria(Class persistentClass);
    void flush();
    void clear();
    boolean isOpen();
}