Java Hibernate Jpa

Identifiers and entity design

Identifier generation

Sequence with pooled optimizer

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "order_seq")
@SequenceGenerator(name = "order_seq", sequenceName = "order_seq", allocationSize = 50)
private Long id;

• allocationSize (default 50) must equal the sequence's INCREMENT BY in the database. A mismatch causes duplicate-key errors or wasteful gaps. Hibernate uses a pooled optimizer by default: one sequence call reserves allocationSize ids.

• Other applications or SQL scripts inserting rows must use the same increment, or draw ids from the sequence in a compatible way.

• Create the sequence in the migration (CREATE SEQUENCE order_seq START WITH 1 INCREMENT BY 50).

UUID

@Id
@GeneratedValue(strategy = GenerationType.UUID)   // Jakarta Persistence 3.1+
private UUID id;

Random v4 UUIDs fragment B-tree indexes on large tables; prefer time-ordered ids (UUIDv7) generated by the application or Hibernate's @UuidGenerator(style = UuidGenerator.Style.TIME) (Hibernate 6.x; check the docs of your version for the v7 option). Store as native uuid columns, not varchar(36).

Anti-patterns

• IDENTITY on a table you bulk-load.

• Natural keys that change; use a surrogate id plus a unique constraint, or @NaturalId.

• @GenericGenerator (Hibernate-specific, deprecated in 6.5+): use @SequenceGenerator, @UuidGenerator, or the newer id generator annotations documented for your version.

equals and hashCode

Problems: the id is null until persist; default identity equality breaks Set semantics across detached/merged instances; Hibernate proxies are subclasses, so getClass() comparisons fail.

Option A (generated id, recommended pattern):

@Override
public final boolean equals(Object o) {
    if (this == o) return true;
    if (o == null) return false;
    Class<?> oClass = o instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getPersistentClass() : o.getClass();
    Class<?> thisClass = this instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getPersistentClass() : getClass();
    if (thisClass != oClass) return false;                  // proxy-safe, symmetric
    Book other = (Book) o;
    Object thisId = this instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getInternalIdentifier() : getId();
    Object otherId = other instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getInternalIdentifier() : other.getId();
    return thisId != null && thisId.equals(otherId);
}

@Override
public final int hashCode() {
    return this instanceof HibernateProxy p
            ? p.getHibernateLazyInitializer().getPersistentClass().hashCode()
            : getClass().hashCode();   // constant per persistent class; stable before/after persist
}

Keep both methods final so Hibernate does not intercept them and initialize the proxy before the method body runs. Use getInternalIdentifier() for proxies: unlike getIdentifier() or an intercepted getId(), it does not initialize them even with JPA proxy compliance enabled. This is a Hibernate-specific pattern, not a provider-portable JPA recipe.

Constant hashCode is fine for entity sets of modest size (hundreds); large in-memory sets of entities are a design smell anyway. getClass() on a proxy returns the generated subclass, so both methods resolve the persistent class first (Hibernate.getClass(x) does the same but initializes the proxy). The class comparison keeps equals symmetric and consistent with hashCode; for entity hierarchies where a subclass should equal its parent type, compare against the root entity class instead.

Validate with two distinct transient books (not equal), the same book before/after persist (hash unchanged), and an uninitialized em.getReference(Book.class, id) after closing its entity manager. Adding that detached proxy to a HashSet, comparing it to a detached book with the same id in both directions, and calling contains must not throw or initialize the proxy. Also check zero additional SQL while the proxy is still attached, including with hibernate.jpa.compliance.proxy=true.

Option B (business/natural key): compare an immutable, unique attribute (ISBN, email), using getters. Implement hashCode on the same field. Mark it @NaturalId. Never use mutable fields.

Option C (client-assigned UUID id): compare/hash the UUID; it exists from construction.

Never include associations or lazy collections in equals/hashCode/toString.

Lombok on entities

• Do not use @Data, @EqualsAndHashCode, @ToString (default) on entities: they touch lazy collections (triggering loads or LazyInitializationException), cause infinite recursion in bidirectional associations, and make hashCode change after persist.

• Use @Getter/@Setter selectively (setters on collections and ids usually should not exist), and @ToString(onlyExplicitlyIncluded = true) with basic fields only.

• @Builder and @AllArgsConstructor bypass invariants and require a protected no-arg constructor (@NoArgsConstructor(access = AccessLevel.PROTECTED)); initialize collections with @Builder.Default.

• Entities must be non-final with a non-private no-arg constructor (Hibernate proxies); do not make fields final.

Records vs entities

• Java records cannot be entities: entities need a no-arg constructor, mutability, and non-final classes. (Hibernate 6+ does support records as @Embeddable components and as projection/DTO types.)

• Use records for DTOs, projections, and embeddables; keep entities as classes.

Enums and converters

• @Enumerated(EnumType.STRING) (readable, resilient to reordering). ORDINAL breaks when constants are reordered or inserted.

• Add a DB check constraint or a native/PostgreSQL enum mapping if invalid values must be rejected at storage level.

• Custom types: AttributeConverter<X, Y> with @Converter(autoApply = false) and @Convert on the attribute. Converters must be stateless and null-safe, and are not applied to ids or in some JPQL comparisons; test queries that compare converted attributes.

• Prefer java.time types over java.util.Date; Instant/OffsetDateTime with UTC (hibernate.jdbc.time_zone=UTC).

• BigDecimal columns: set precision and scale.

Other design points

• Embedded value objects with @Embeddable instead of loose columns.

• Use @Version for optimistic locking on aggregate roots (locking-transactions-caching.md).

• Mark read-only reference entities @Immutable.

• @ElementCollection for small value sets only; large or queried collections deserve their own entity.

• Prefer Long/UUID wrapper ids (null means transient).