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)

Overview

Eval results

Files

Entity Mapping

Name: tessl/maven-org-hibernate-orm--hibernate-core
Author: tessl

Hibernate Core provides extensive annotations and mapping capabilities beyond the standard JPA annotations. These include advanced caching, fetching strategies, custom types, natural identifiers, and specialized entity behaviors.

Capabilities

Caching Annotations

Advanced second-level caching configuration for entities and collections.

/**
 * Configures second-level caching for an entity or collection
 */
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface Cache {
    /**
     * Cache concurrency strategy
     * @return the concurrency strategy
     */
    CacheConcurrencyStrategy usage();

    /**
     * Cache region name
     * @return the region name (defaults to entity/collection name)
     */
    String region() default "";

    /**
     * Include lazy attributes in cache when loaded
     * @return whether to cache lazy fields (default true)
     */
    boolean includeLazy() default true;
}

/**
 * Cache concurrency strategies
 */
public enum CacheConcurrencyStrategy {
    /** No concurrency strategy specified */
    NONE,
    /** Read-only access - immutable objects */
    READ_ONLY,
    /** Read/write access with no locking - for rarely updated data */
    NONSTRICT_READ_WRITE,
    /** Read/write access with soft locks - for commonly updated data */
    READ_WRITE,
    /** Transactional access - requires JTA/XA integration */
    TRANSACTIONAL
}

Cache Runtime Interface

Runtime interface for programmatic cache interaction and management.

/**
 * Runtime cache interface for programmatic cache operations
 */
public interface Cache {
    /**
     * Get an item from the cache
     * @param key the cache key
     * @return the cached item or null if not found
     */
    Object get(Object key);

    /**
     * Put an item in the cache
     * @param key the cache key
     * @param value the value to cache
     */
    void put(Object key, Object value);

    /**
     * Remove an item from the cache
     * @param key the cache key
     */
    void evict(Object key);

    /**
     * Clear all entries from the cache
     */
    void clear();

    /**
     * Destroy/close the cache
     */
    void destroy();

    /**
     * Get the cache region name
     * @return the region name
     */
    String getRegionName();

    /**
     * Check if the cache contains the specified key
     * @param key the cache key
     * @return true if key exists in cache
     */
    boolean contains(Object key);

    /**
     * Get cache statistics
     * @return CacheStatistics instance or null if statistics disabled
     */
    CacheStatistics getStatistics();
}

/**
 * Cache statistics interface
 */
public interface CacheStatistics {
    /**
     * Get the number of cache hits
     * @return hit count
     */
    long getHitCount();

    /**
     * Get the number of cache misses
     * @return miss count
     */
    long getMissCount();

    /**
     * Get the cache hit ratio
     * @return hit ratio (0.0 to 1.0)
     */
    double getHitRatio();

    /**
     * Get the number of cached elements
     * @return element count
     */
    long getElementCountInMemory();

    /**
     * Clear the statistics
     */
    void clear();
}

Fetching Strategy Annotations

Control how associations are fetched from the database.

/**
 * Specifies the fetch strategy for an association
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Fetch {
    /**
     * The fetch mode to use
     * @return the fetch mode
     */
    FetchMode value();
}

/**
 * Available fetch modes
 */
public enum FetchMode {
    /** Use a select statement to load the association */
    SELECT,
    /** Use an outer join to load the association */
    JOIN,
    /** Use a subquery to load the association */
    SUBSELECT
}

/**
 * Batch size for fetching associations or entities
 */
@Target({TYPE, METHOD, FIELD})
@Retention(RUNTIME)
public @interface BatchSize {
    /**
     * The batch size
     * @return the batch size (must be positive)
     */
    int size();
}

/**
 * Lazy loading group for fine-grained lazy loading
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface LazyGroup {
    /**
     * The lazy group name
     * @return the group name
     */
    String value();
}

Natural Identifier Annotations

Support for natural identifiers as alternatives to surrogate keys.

/**
 * Marks a property as part of the natural identifier
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface NaturalId {
    /**
     * Whether the natural ID is mutable
     * @return true if mutable
     */
    boolean mutable() default false;
}

/**
 * Cache configuration specifically for natural ID lookups
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface NaturalIdCache {
    /**
     * Cache region for natural ID lookups
     * @return the cache region name
     */
    String region() default "";
}

Custom Type Annotations

Specify custom types for properties and parameters.

/**
 * Specifies a custom Hibernate type for a property
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Type {
    /**
     * The type implementation class
     * @return the type class
     */
    Class<? extends UserType<?>> value() default void.class;

    /**
     * Parameters for the type
     * @return array of parameters
     */
    Parameter[] parameters() default {};
}

/**
 * Specify Java type for a property
 */
@Target({METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface JavaType {
    /**
     * The Java type descriptor class
     * @return the descriptor class
     */
    Class<? extends JavaTypeDescriptor<?>> value();
}

/**
 * Specify JDBC type for a property
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface JdbcType {
    /**
     * The JDBC type descriptor class
     * @return the descriptor class
     */
    Class<? extends JdbcType> value();
}

Entity Behavior Annotations

Control entity lifecycle and behavior.

/**
 * Entity is immutable (read-only)
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface Immutable {
}

/**
 * Generate SQL dynamically for inserts
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface DynamicInsert {
    /**
     * Whether to use dynamic inserts
     * @return true for dynamic inserts
     */
    boolean value() default true;
}

/**
 * Generate SQL dynamically for updates
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface DynamicUpdate {
    /**
     * Whether to use dynamic updates
     * @return true for dynamic updates
     */
    boolean value() default true;
}

/**
 * Select before update optimization
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface SelectBeforeUpdate {
    /**
     * Whether to select before update
     * @return true to select before update
     */
    boolean value() default true;
}

/**
 * Optimistic locking strategy
 */
@Target(TYPE)
@Retention(RUNTIME)
public @interface OptimisticLocking {
    /**
     * The optimistic locking type
     * @return the locking type
     */
    OptimisticLockType type() default OptimisticLockType.VERSION;
}

/**
 * Optimistic locking types
 */
public enum OptimisticLockType {
    /** No optimistic locking */
    NONE,
    /** Version-based locking */
    VERSION,
    /** Dirty fields locking */
    DIRTY,
    /** All fields locking */
    ALL
}

Timestamp and Generated Value Annotations

Automatic timestamp and value generation.

/**
 * Automatically set creation timestamp
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface CreationTimestamp {
}

/**
 * Automatically set update timestamp
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface UpdateTimestamp {
}

/**
 * Specify generation strategy for properties
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Generated {
    /**
     * When the value is generated
     * @return the generation timing
     */
    GenerationTime value();
}

/**
 * Generation timing options
 */
public enum GenerationTime {
    /** Never generated */
    NEVER,
    /** Generated on insert only */
    INSERT,
    /** Generated on insert and update */
    ALWAYS
}

Formula and Computed Properties

Define computed properties and SQL formulas.

/**
 * SQL formula for computed properties
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Formula {
    /**
     * The SQL formula
     * @return the SQL expression
     */
    String value();
}

/**
 * Derived property based on other properties
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface ColumnTransformer {
    /**
     * SQL expression for reading the column
     * @return the read expression
     */
    String read() default "";

    /**
     * SQL expression for writing the column
     * @return the write expression
     */
    String write() default "";
}

Collection and Association Annotations

Advanced collection and association mapping.

/**
 * Order collection by SQL expression
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OrderBy {
    /**
     * SQL ORDER BY clause
     * @return the ordering clause
     */
    String clause();
}

/**
 * Sort collection in memory
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface Sort {
    /**
     * The sorting type
     * @return the sort type
     */
    SortType type() default SortType.UNSORTED;

    /**
     * Comparator class for custom sorting
     * @return the comparator class
     */
    Class<? extends Comparator> comparator() default void.class;
}

/**
 * How to handle missing referenced entities
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface NotFound {
    /**
     * The action to take for missing references
     * @return the not found action
     */
    NotFoundAction action() default NotFoundAction.EXCEPTION;
}

/**
 * Actions for missing references
 */
public enum NotFoundAction {
    /** Throw exception */
    EXCEPTION,
    /** Ignore missing reference */
    IGNORE
}

/**
 * Database cascade actions
 */
@Target({METHOD, FIELD})
@Retention(RUNTIME)
public @interface OnDelete {
    /**
     * The cascade action
     * @return the delete action
     */
    OnDeleteAction action();
}

/**
 * Database cascade actions
 */
public enum OnDeleteAction {
    /** No action */
    NO_ACTION,
    /** Cascade delete */
    CASCADE,
    /** Set to null */
    SET_NULL,
    /** Set to default */
    SET_DEFAULT,
    /** Restrict delete */
    RESTRICT
}

Query and Filter Annotations

Named queries and entity filtering.

/**
 * Named HQL/JPQL query
 */
@Target(TYPE)
@Retention(RUNTIME)
@Repeatable(NamedQueries.class)
public @interface NamedQuery {
    /**
     * Query name
     * @return the query name
     */
    String name();

    /**
     * HQL/JPQL query string
     * @return the query string
     */
    String query();

    /**
     * Query hints
     * @return array of query hints
     */
    QueryHint[] hints() default {};
}

/**
 * Named native SQL query
 */
@Target(TYPE)
@Retention(RUNTIME)
@Repeatable(NamedNativeQueries.class)
public @interface NamedNativeQuery {
    /**
     * Query name
     * @return the query name
     */
    String name();

    /**
     * Native SQL query string
     * @return the SQL string
     */
    String query();

    /**
     * Result class
     * @return the result class
     */
    Class resultClass() default void.class;

    /**
     * Result set mapping name
     * @return the mapping name
     */
    String resultSetMapping() default "";
}

/**
 * Define a filter for the entity
 */
@Target(TYPE)
@Retention(RUNTIME)
@Repeatable(Filters.class)
public @interface Filter {
    /**
     * Filter name
     * @return the filter name
     */
    String name();

    /**
     * Filter condition
     * @return the SQL condition
     */
    String condition() default "";
}

/**
 * Filter definition with parameters
 */
@Target(TYPE)
@Retention(RUNTIME)
@Repeatable(FilterDefs.class)
public @interface FilterDef {
    /**
     * Filter name
     * @return the filter name
     */
    String name();

    /**
     * Filter parameters
     * @return array of parameters
     */
    ParamDef[] parameters() default {};

    /**
     * Default condition
     * @return the default condition
     */
    String defaultCondition() default "";
}

Usage Examples

Entity with Caching and Natural ID

@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE, region = "users")
@NaturalIdCache
@DynamicUpdate
@SelectBeforeUpdate
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NaturalId(mutable = false)
    @Column(unique = true, nullable = false)
    private String username;

    @Column(nullable = false)
    private String name;

    @CreationTimestamp
    @Column(name = "created_date")
    private LocalDateTime createdDate;

    @UpdateTimestamp
    @Column(name = "last_modified")
    private LocalDateTime lastModified;

    // Computed property
    @Formula("(SELECT COUNT(*) FROM orders o WHERE o.customer_id = id)")
    private int orderCount;

    // Constructors, getters, setters
}

Advanced Association Mapping

@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
@FilterDef(name = "activeOrders", parameters = @ParamDef(name = "status", type = String.class))
public class Customer {
    @Id
    private Long id;

    private String name;

    @OneToMany(mappedBy = "customer", fetch = FetchType.LAZY, cascade = CascadeType.ALL)
    @Fetch(FetchMode.SUBSELECT)
    @BatchSize(size = 10)
    @Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
    @OrderBy("orderDate DESC")
    @Filter(name = "activeOrders", condition = "status = :status")
    private Set<Order> orders = new HashSet<>();

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "address_id")
    @NotFound(action = NotFoundAction.IGNORE)
    @OnDelete(action = OnDeleteAction.SET_NULL)
    private Address primaryAddress;

    // Constructors, getters, setters
}

Custom Type Usage

@Entity
public class Product {
    @Id
    private Long id;

    private String name;

    // Custom type for monetary values
    @Type(value = MoneyType.class)
    @Column(name = "price")
    private Money price;

    // JSON type mapping
    @Type(value = JsonType.class)
    @Column(name = "attributes", columnDefinition = "json")
    private Map<String, Object> attributes;

    // Custom Java type
    @JavaType(UUIDJavaType.class)
    @Column(name = "external_id")
    private UUID externalId;

    // Encrypted field
    @ColumnTransformer(
        read = "AES_DECRYPT(credit_card, 'key')",
        write = "AES_ENCRYPT(?, 'key')"
    )
    @Column(name = "credit_card")
    private String creditCard;

    // Constructors, getters, setters
}

Immutable Entity with Formula

@Entity
@Immutable
@Table(name = "order_summary_view")
public class OrderSummary {
    @Id
    private Long orderId;

    private String customerName;

    @Formula("(SELECT SUM(oi.quantity * oi.price) FROM order_items oi WHERE oi.order_id = order_id)")
    private BigDecimal totalAmount;

    @Formula("(SELECT COUNT(*) FROM order_items oi WHERE oi.order_id = order_id)")
    private Integer itemCount;

    @Type(value = PostgreSQLEnumType.class)
    @Column(name = "status", columnDefinition = "order_status")
    private OrderStatus status;

    // Constructors, getters, setters (no setters for immutable entity)
}

Using Filters

// Enable filter for active records only
@Entity
@FilterDef(name = "activeOnly", defaultCondition = "active = true")
@Filter(name = "activeOnly")
public class Employee {
    @Id
    private Long id;

    private String name;

    private boolean active;

    // Entity definition
}

// Usage in session
session.enableFilter("activeOnly");
List<Employee> activeEmployees = session.createQuery("FROM Employee", Employee.class)
    .getResultList(); // Only returns active employees

// Filter with parameters
session.enableFilter("activeOrders")
    .setParameter("status", "ACTIVE");

Lazy Loading Groups

@Entity
public class Document {
    @Id
    private Long id;

    private String title;

    // Metadata loaded eagerly
    private String author;
    private LocalDateTime createdDate;

    // Content loaded lazily in separate group
    @Basic(fetch = FetchType.LAZY)
    @LazyGroup("content")
    @Lob
    private String content;

    // Binary data loaded lazily in separate group
    @Basic(fetch = FetchType.LAZY)
    @LazyGroup("binary")
    @Lob
    private byte[] attachments;

    // Constructors, getters, setters
}

Mapping Best Practices

Performance Considerations

Use @Cache judiciously on frequently read, infrequently modified entities
Implement @BatchSize for associations to avoid N+1 queries
Use @LazyGroup to separate rarely accessed large properties
Consider @DynamicUpdate for entities with many nullable columns

Natural Identifiers

Use @NaturalId for business keys (username, email, etc.)
Enable @NaturalIdCache for frequently accessed natural IDs
Keep natural IDs immutable when possible

Custom Types

Implement custom types for domain-specific value objects
Use @Type for complex mappings that don't fit standard types
Consider @Formula for computed properties that don't need persistence

Install with Tessl CLI

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

docs

session-management.md

transactions.md

type-system.md

tile.json